geutebruck-api/specs/001-surveillance-api/plan.md

Implementation Plan: Geutebruck Video Surveillance API

Branch: 001-surveillance-api | Date: 2025-11-13 | Spec: spec.md Input: Feature specification from /specs/001-surveillance-api/spec.md

Summary

Build a complete RESTful API for Geutebruck GeViScope/GeViSoft video surveillance system control, enabling developers to create custom surveillance applications without direct SDK integration. The API will provide authentication, live video streaming, PTZ camera control, real-time event notifications, recording management, and video analytics configuration through a secure, well-documented REST/WebSocket interface.

Technical Approach: Python FastAPI service running on Windows, translating REST/WebSocket requests to GeViScope SDK actions through an abstraction layer, with JWT authentication, Redis caching, and auto-generated OpenAPI documentation.

Technical Context

Language/Version: Python 3.11+ Primary Dependencies:

• FastAPI 0.104+ (async web framework with auto OpenAPI docs)
• Pydantic 2.5+ (data validation and settings management)
• python-jose 3.3+ (JWT token generation and validation)
• passlib 1.7+ (password hashing with bcrypt)
• Redis-py 5.0+ (session storage and caching)
• python-multipart (file upload support for video exports)
• uvicorn 0.24+ (ASGI server)
• websockets 12.0+ (WebSocket support built into FastAPI)
• pywin32 or comtypes (GeViScope SDK COM interface)

Storage:

• Redis 7.2+ for session management, API key caching, rate limiting counters
• Optional: SQLite for development / PostgreSQL for production audit logs
• GeViScope SDK manages video storage (ring buffer architecture)

Testing:

• pytest 7.4+ (test framework)
• pytest-asyncio (async test support)
• httpx (async HTTP client for API testing)
• pytest-cov (coverage reporting, target 80%+)
• pytest-mock (mocking for SDK bridge testing)

Target Platform: Windows Server 2016+ or Windows 10/11 (required for GeViScope SDK)

Project Type: Single project (API-only service, clients consume REST/WebSocket)

Performance Goals:

• 500 requests/second throughput under normal load
• < 200ms response time for metadata queries (p95)
• < 500ms for PTZ commands
• < 100ms event notification delivery
• Support 100+ concurrent video streams
• Support 1000+ concurrent WebSocket connections

Constraints:

• Must run on Windows (GeViScope SDK requirement)
• Must interface with GeViScope SDK COM/DLL objects
• Channel-based operations (Channel ID parameter required)
• Video streaming limited by GeViScope SDK license and hardware
• Ring buffer architecture bounds recording capabilities
• TLS 1.2+ required in production

Scale/Scope:

• 10-100 concurrent operators
• 50-500 cameras per deployment
• 30 API endpoints across 6 resource types
• 10 WebSocket event types
• 8 video analytics types (VMD, NPR, OBTRACK, etc.)

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

✅ Principle I: Security-First (NON-NEGOTIABLE)

• JWT authentication implemented for all protected endpoints
• TLS 1.2+ enforced (configured in deployment, not code)
• RBAC with 3 roles (viewer, operator, administrator)
• Granular per-camera permissions
• Audit logging for privileged operations
• Rate limiting on authentication endpoints
• No credentials in source code (environment variables)

Status: ✅ PASS - Security requirements addressed in architecture

✅ Principle II: RESTful API Design

• Resources represent surveillance entities (cameras, events, recordings)
• Standard HTTP methods (GET, POST, PUT, DELETE)
• URL structure /api/v1/{resource}/{id}/{action}
• JSON data exchange
• Proper HTTP status codes
• Stateless JWT authentication
• API versioning in URL path

Status: ✅ PASS - REST principles followed

✅ Principle III: Test-Driven Development (NON-NEGOTIABLE)

• Tests written before implementation (TDD enforced)
• 80% coverage target for SDK bridge layer
• Unit, integration, and E2E tests planned
• pytest framework selected
• CI/CD blocks on test failures

Status: ✅ PASS - TDD workflow defined

✅ Principle IV: SDK Abstraction Layer

• SDK Bridge isolates GeViScope SDK from API layer
• Translates REST → SDK Actions, SDK Events → WebSocket
• Error code translation (Windows → HTTP)
• Mockable for testing without hardware
• No direct SDK calls from route handlers

Status: ✅ PASS - Abstraction layer designed

✅ Principle V: Performance & Reliability

• Performance targets defined and measurable
• Retry logic with exponential backoff (3 attempts)
• Circuit breaker pattern for SDK communication
• Graceful degradation under load (503 vs crash)
• Health check endpoint planned

Status: ✅ PASS - Performance and reliability addressed

✅ Technical Constraints Satisfied

• Windows platform acknowledged
• Python 3.11+ selected
• FastAPI framework chosen
• Redis for caching
• Pytest for testing
• SDK integration strategy defined

Status: ✅ PASS - All technical constraints satisfied

✅ Quality Standards Met

• 80% test coverage enforced
• Code review via PR required
• Black formatter + ruff linter
• Type hints mandatory (mypy)
• OpenAPI auto-generated

Status: ✅ PASS - Quality standards defined

Overall Gate Status: ✅ PASS - Proceed to Phase 0 Research

Project Structure

Documentation (this feature)

specs/001-surveillance-api/
├── spec.md              # Feature specification (complete)
├── plan.md              # This file (in progress)
├── research.md          # Phase 0 output (pending)
├── data-model.md        # Phase 1 output (pending)
├── quickstart.md        # Phase 1 output (pending)
├── contracts/           # Phase 1 output (pending)
│   └── openapi.yaml     # OpenAPI 3.0 specification
└── tasks.md             # Phase 2 output (via /speckit.tasks)

Source Code (repository root)

geutebruck-api/
├── src/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── routes/
│   │   │   │   ├── auth.py          # Authentication endpoints
│   │   │   │   ├── cameras.py       # Camera management & streaming
│   │   │   │   ├── events.py        # Event subscriptions
│   │   │   │   ├── recordings.py    # Recording management
│   │   │   │   ├── analytics.py     # Video analytics config
│   │   │   │   └── system.py        # Health, status endpoints
│   │   │   ├── dependencies.py      # Route dependencies (auth, etc.)
│   │   │   ├── schemas.py           # Pydantic request/response models
│   │   │   └── __init__.py
│   │   ├── middleware/
│   │   │   ├── auth.py              # JWT validation middleware
│   │   │   ├── error_handler.py     # Global exception handling
│   │   │   ├── rate_limit.py        # Rate limiting middleware
│   │   │   └── logging.py           # Request/response logging
│   │   ├── websocket.py             # WebSocket connection manager
│   │   └── main.py                  # FastAPI app initialization
│   ├── sdk/
│   │   ├── bridge.py                # Main SDK abstraction interface
│   │   ├── actions/
│   │   │   ├── system.py            # SystemActions wrapper
│   │   │   ├── video.py             # VideoActions wrapper
│   │   │   ├── camera.py            # CameraControlActions wrapper
│   │   │   ├── events.py            # Event management wrapper
│   │   │   └── analytics.py         # Analytics actions wrapper
│   │   ├── events/
│   │   │   ├── dispatcher.py        # Event listener and dispatcher
│   │   │   └── translator.py        # SDK Event → JSON translator
│   │   ├── errors.py                # SDK exception types
│   │   └── connection.py            # SDK connection management
│   ├── services/
│   │   ├── auth.py                  # Authentication service (JWT, passwords)
│   │   ├── permissions.py           # RBAC and authorization logic
│   │   ├── camera.py                # Camera business logic
│   │   ├── recording.py             # Recording management logic
│   │   ├── analytics.py             # Analytics configuration logic
│   │   └── notifications.py         # Event notification service
│   ├── models/
│   │   ├── user.py                  # User entity
│   │   ├── camera.py                # Camera entity
│   │   ├── event.py                 # Event entity
│   │   ├── recording.py             # Recording entity
│   │   └── session.py               # Session entity
│   ├── database/
│   │   ├── redis.py                 # Redis connection and helpers
│   │   └── audit.py                 # Audit log persistence (optional DB)
│   ├── core/
│   │   ├── config.py                # Settings management (Pydantic Settings)
│   │   ├── security.py              # Password hashing, JWT utilities
│   │   └── logging.py               # Logging configuration
│   └── utils/
│       ├── errors.py                # Custom exception classes
│       └── validators.py            # Custom validation functions
├── tests/
│   ├── unit/
│   │   ├── test_auth_service.py
│   │   ├── test_sdk_bridge.py
│   │   ├── test_camera_service.py
│   │   └── test_permissions.py
│   ├── integration/
│   │   ├── test_auth_endpoints.py
│   │   ├── test_camera_endpoints.py
│   │   ├── test_event_endpoints.py
│   │   ├── test_recording_endpoints.py
│   │   └── test_websocket.py
│   ├── e2e/
│   │   └── test_user_workflows.py   # End-to-end scenarios
│   ├── conftest.py                  # Pytest fixtures
│   └── mocks/
│       └── sdk_mock.py              # Mock SDK for testing
├── docs/
│   ├── api/                         # API documentation
│   ├── deployment/                  # Deployment guides
│   └── sdk-mapping.md               # GeViScope action → endpoint mapping
├── docker/
│   ├── Dockerfile                   # Windows container
│   └── docker-compose.yml           # Development environment
├── .env.example                     # Environment variable template
├── requirements.txt                 # Python dependencies
├── pyproject.toml                   # Project metadata, tool config
├── README.md                        # Project overview
└── .gitignore

Structure Decision: Single project structure selected because this is an API-only service. Frontend/mobile clients will be separate projects that consume this API. The structure separates concerns into:

• api/ - FastAPI routes, middleware, WebSocket
• sdk/ - GeViScope SDK abstraction and translation
• services/ - Business logic layer
• models/ - Domain entities
• database/ - Data access layer
• core/ - Cross-cutting concerns (config, security, logging)
• utils/ - Shared utilities

Complexity Tracking

No constitution violations requiring justification.

All technical choices align with constitution principles. The selected technology stack (Python + FastAPI + Redis) directly implements the decisions made in the constitution.

Phase 0: Research & Technical Decisions

Status: Pending - To be completed in research.md

Research Topics

1. GeViScope SDK Integration

   • Research COM/DLL interface patterns for Python (pywin32 vs comtypes)
   • Document GeViScope SDK action categories and parameters
   • Identify SDK event notification mechanisms
   • Determine video stream URL/protocol format

2. Video Streaming Strategy

   • Research options: Direct URLs vs API proxy vs WebRTC signaling
   • Evaluate bandwidth implications for 100+ concurrent streams
   • Determine authentication method for video streams
   • Document GeViScope streaming protocols

3. WebSocket Event Architecture

   • Research FastAPI WebSocket best practices for 1000+ connections
   • Design event subscription patterns (by type, by channel, by user)
   • Determine connection lifecycle management (heartbeat, reconnection)
   • Plan message batching strategy for high-frequency events

4. Authentication & Session Management

   • Finalize JWT token structure and claims
   • Design refresh token rotation strategy
   • Plan API key generation and storage (for service accounts)
   • Determine Redis session schema and TTL values

5. Performance Optimization

   • Research async patterns for SDK I/O operations
   • Plan connection pooling strategy for SDK
   • Design caching strategy for camera metadata
   • Evaluate load balancing options (horizontal scaling)

6. Error Handling & Monitoring

   • Map Windows error codes to HTTP status codes
   • Design structured logging format
   • Plan health check implementation (SDK connectivity, Redis, resource usage)
   • Identify metrics to expose (Prometheus format)

7. Testing Strategy

   • Design SDK mock implementation for tests without hardware
   • Plan test data generation (sample cameras, events, recordings)
   • Determine integration test approach (test SDK instance vs mocks)
   • Document E2E test scenarios

Output Location: specs/001-surveillance-api/research.md

Phase 1: Design & Contracts

Status: Pending - To be completed after Phase 0 research

Deliverables

1. Data Model (data-model.md)

   • Entity schemas (User, Camera, Event, Recording, Stream, etc.)
   • Validation rules
   • State transitions (e.g., Recording states: idle → recording → stopped)
   • Relationships and foreign keys

2. API Contracts (contracts/openapi.yaml)

   • Complete OpenAPI 3.0 specification
   • All endpoints with request/response schemas
   • Authentication scheme definitions
   • WebSocket protocol documentation
   • Error response formats

3. Quick Start Guide (quickstart.md)

   • Installation instructions
   • Configuration guide (environment variables)
   • First API call example (authentication)
   • Common use cases with curl/Python examples

4. Agent Context Update

   • Run .specify/scripts/powershell/update-agent-context.ps1 -AgentType claude
   • Add project-specific context to Claude agent file

API Endpoint Overview (Design Phase)

Authentication (/api/v1/auth/):

• POST /login - Obtain JWT token
• POST /refresh - Refresh access token
• POST /logout - Invalidate session

Cameras (/api/v1/cameras/):

• GET / - List all cameras (filtered by permissions)
• GET /{id} - Get camera details
• GET /{id}/stream - Get live video stream URL/connection
• POST /{id}/ptz - Send PTZ command
• GET /{id}/presets - Get PTZ presets
• POST /{id}/presets - Save PTZ preset

Events (/api/v1/events/):

• WS /stream - WebSocket endpoint for event subscriptions
• GET / - Query event history (paginated)
• GET /{id} - Get event details

Recordings (/api/v1/recordings/):

• GET / - Query recordings by channel/time range
• POST /{channel}/start - Start recording
• POST /{channel}/stop - Stop recording
• GET /{id} - Get recording details
• POST /{id}/export - Request video export
• GET /capacity - Get recording capacity metrics

Analytics (/api/v1/analytics/):

• GET /{channel}/config - Get analytics configuration
• PUT /{channel}/config - Update analytics configuration
• POST /{channel}/vmd - Configure motion detection
• POST /{channel}/npr - Configure license plate recognition
• POST /{channel}/obtrack - Configure object tracking

System (/api/v1/system/):

• GET /health - Health check (no auth required)
• GET /status - Detailed system status
• GET /metrics - Prometheus metrics

Output Locations:

• specs/001-surveillance-api/data-model.md
• specs/001-surveillance-api/contracts/openapi.yaml
• specs/001-surveillance-api/quickstart.md

Phase 2: Task Breakdown

Not created by /speckit.plan - This phase is handled by /speckit.tasks command

The tasks phase will break down the implementation into concrete work items organized by:

• Setup phase (project scaffolding, dependencies)
• Foundational phase (SDK bridge, authentication, database)
• User story phases (P1, P2, P3 stories as separate task groups)
• Polish phase (documentation, optimization, security hardening)

Deployment Considerations

Development Environment

• Python 3.11+ installed
• GeViScope SDK installed and configured
• Redis running locally or via Docker (Windows containers)
• Environment variables configured (.env file)

Production Environment

• Windows Server 2016+ or Windows 10/11
• GeViScope SDK with active license
• Redis cluster or managed instance
• TLS certificates configured
• Reverse proxy (nginx/IIS) for HTTPS termination
• Environment variables via system config or key vault

Configuration Management

All configuration via environment variables:

• SDK_CONNECTION_STRING - GeViScope SDK connection details
• JWT_SECRET_KEY - JWT signing key
• JWT_ALGORITHM - Default: HS256
• JWT_EXPIRATION_MINUTES - Default: 60
• REDIS_URL - Redis connection URL
• LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)
• CORS_ORIGINS - Allowed CORS origins for web clients
• MAX_CONCURRENT_STREAMS - Concurrent stream limit
• RATE_LIMIT_AUTH - Auth endpoint rate limit

Docker Deployment

# Windows Server Core base image
FROM mcr.microsoft.com/windows/servercore:ltsc2022

# Install Python 3.11
# Install GeViScope SDK
# Copy application code
# Install Python dependencies
# Expose ports 8000 (HTTP), 8001 (WebSocket)
# Run uvicorn server

Next Steps

1. ✅ Constitution defined and validated
2. ✅ Specification created with user stories and requirements
3. ✅ Implementation plan created (this document)
4. ⏭️ Execute /speckit.plan Phase 0: Generate research.md
5. ⏭️ Execute /speckit.plan Phase 1: Generate data-model.md, contracts/, quickstart.md
6. ⏭️ Execute /speckit.tasks: Break down into actionable task list
7. ⏭️ Execute /speckit.implement: Begin TDD implementation

---

Plan Status: ✅ Technical plan complete, ready for Phase 0 research Constitution Compliance: ✅ All gates passed Next Command: Continue with research phase to resolve implementation details