edf22b09c2
- 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
451 lines
19 KiB
Markdown
451 lines
19 KiB
Markdown
# 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
|