From edf22b09c29668a2ce584a692f04a0422044f9b7 Mon Sep 17 00:00:00 2001 From: Geutebruck API Developer Date: Thu, 13 Nov 2025 03:25:05 -0800 Subject: [PATCH] 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 --- specs/001-surveillance-api/plan.md | 450 +++++++++++++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 specs/001-surveillance-api/plan.md diff --git a/specs/001-surveillance-api/plan.md b/specs/001-surveillance-api/plan.md new file mode 100644 index 0000000..90c8f7f --- /dev/null +++ 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