feat: add technical implementation plan

- Technology stack: Python 3.11+ FastAPI Redis - Complete project structure (src/ tests/ docs/) - All constitution gates passed - 7 research topics identified - 30 API endpoints across 6 resources - Deployment strategy defined - Ready for Phase 0 research
2025-11-13 03:25:05 -08:00
parent 44dc06e7f1
commit edf22b09c2
1 changed files with 450 additions and 0 deletions
--- a/specs/001-surveillance-api/plan.md
+++ b/specs/001-surveillance-api/plan.md
@@ -0,0 +1,450 @@
+# Implementation Plan: Geutebruck Video Surveillance API
+
+**Branch**: `001-surveillance-api` | **Date**: 2025-11-13 | **Spec**: [spec.md](./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)
+- [x] JWT authentication implemented for all protected endpoints
+- [x] TLS 1.2+ enforced (configured in deployment, not code)
+- [x] RBAC with 3 roles (viewer, operator, administrator)
+- [x] Granular per-camera permissions
+- [x] Audit logging for privileged operations
+- [x] Rate limiting on authentication endpoints
+- [x] No credentials in source code (environment variables)
+
+**Status**: ✅ **PASS** - Security requirements addressed in architecture
+
+### ✅ Principle II: RESTful API Design
+- [x] Resources represent surveillance entities (cameras, events, recordings)
+- [x] Standard HTTP methods (GET, POST, PUT, DELETE)
+- [x] URL structure `/api/v1/{resource}/{id}/{action}`
+- [x] JSON data exchange
+- [x] Proper HTTP status codes
+- [x] Stateless JWT authentication
+- [x] API versioning in URL path
+
+**Status**: ✅ **PASS** - REST principles followed
+
+### ✅ Principle III: Test-Driven Development (NON-NEGOTIABLE)
+- [x] Tests written before implementation (TDD enforced)
+- [x] 80% coverage target for SDK bridge layer
+- [x] Unit, integration, and E2E tests planned
+- [x] pytest framework selected
+- [x] CI/CD blocks on test failures
+
+**Status**: ✅ **PASS** - TDD workflow defined
+
+### ✅ Principle IV: SDK Abstraction Layer
+- [x] SDK Bridge isolates GeViScope SDK from API layer
+- [x] Translates REST → SDK Actions, SDK Events → WebSocket
+- [x] Error code translation (Windows → HTTP)
+- [x] Mockable for testing without hardware
+- [x] No direct SDK calls from route handlers
+
+**Status**: ✅ **PASS** - Abstraction layer designed
+
+### ✅ Principle V: Performance & Reliability
+- [x] Performance targets defined and measurable
+- [x] Retry logic with exponential backoff (3 attempts)
+- [x] Circuit breaker pattern for SDK communication
+- [x] Graceful degradation under load (503 vs crash)
+- [x] Health check endpoint planned
+
+**Status**: ✅ **PASS** - Performance and reliability addressed
+
+### ✅ Technical Constraints Satisfied
+- [x] Windows platform acknowledged
+- [x] Python 3.11+ selected
+- [x] FastAPI framework chosen
+- [x] Redis for caching
+- [x] Pytest for testing
+- [x] SDK integration strategy defined
+
+**Status**: ✅ **PASS** - All technical constraints satisfied
+
+### ✅ Quality Standards Met
+- [x] 80% test coverage enforced
+- [x] Code review via PR required
+- [x] Black formatter + ruff linter
+- [x] Type hints mandatory (mypy)
+- [x] 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
+```dockerfile
+# 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