Complete Phase 0 and Phase 1 design documentation
- Add comprehensive research.md with SDK integration decisions - Add complete data-model.md with 7 entities and relationships - Add OpenAPI 3.0 specification (contracts/openapi.yaml) - Add developer quickstart.md guide - Add comprehensive tasks.md with 215 tasks organized by user story - Update plan.md with complete technical context - Add SDK_INTEGRATION_LESSONS.md capturing critical knowledge - Add .gitignore for Python and C# projects - Include GeViScopeConfigReader and GeViSoftConfigReader tools Phase 1 Design Complete: ✅ Architecture: Python FastAPI + C# gRPC Bridge + GeViScope SDK ✅ 10 user stories mapped to tasks (MVP = US1-4) ✅ Complete API contract with 17 endpoints ✅ Data model with User, Camera, Stream, Event, Recording, Analytics ✅ TDD approach enforced with 80+ test tasks Ready for Phase 2: Implementation 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Geutebruck API Developer
@@ -1,450 +1,403 @@
|
||||
# Implementation Plan: Geutebruck Video Surveillance API
|
||||
# Implementation Plan: Geutebruck Surveillance API
|
||||
|
||||
**Branch**: `001-surveillance-api` | **Date**: 2025-11-13 | **Spec**: [spec.md](./spec.md)
|
||||
**Branch**: `001-surveillance-api` | **Date**: 2025-12-08 | **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.
|
||||
Build a production-ready REST API for Geutebruck GeViScope/GeViSoft video surveillance systems, enabling developers to integrate surveillance capabilities into custom applications without direct SDK complexity. The system uses a C# gRPC bridge to interface with the GeViScope SDK, exposing clean REST/WebSocket endpoints through Python FastAPI.
|
||||
|
||||
**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 Approach**: Python FastAPI + C# gRPC SDK Bridge + GeViScope SDK → delivers <200ms API responses, supports 100+ concurrent video streams, and handles 1000+ WebSocket event subscribers.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Python 3.11+
|
||||
**Language/Version**: Python 3.11+, C# .NET Framework 4.8 (SDK bridge), C# .NET 8.0 (gRPC service)
|
||||
**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)
|
||||
|
||||
- **Python**: FastAPI, Uvicorn, SQLAlchemy, Redis (aioredis), protobuf, grpcio, PyJWT, asyncio
|
||||
- **C#**: GeViScope SDK (GeViProcAPINET_4_0.dll), Grpc.Core, Google.Protobuf
|
||||
**Storage**: PostgreSQL 14+ (user management, session storage, audit logs), Redis 6.0+ (session cache, pub/sub for WebSocket events)
|
||||
**Testing**: pytest (Python), xUnit (.NET), 80% minimum coverage, TDD enforced
|
||||
**Target Platform**: Windows Server 2016+ (SDK bridge + GeViServer), Linux (FastAPI server - optional)
|
||||
**Project Type**: Web (backend API + SDK bridge service)
|
||||
**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
|
||||
|
||||
- <200ms p95 for metadata queries (camera lists, status)
|
||||
- <2s stream initialization
|
||||
- <100ms event notification delivery
|
||||
- 100+ concurrent video streams
|
||||
- 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
|
||||
|
||||
- SDK requires Windows x86 (32-bit) runtime
|
||||
- Visual C++ 2010 Redistributable (x86) mandatory
|
||||
- Full GeViSoft installation required (not just SDK)
|
||||
- GeViServer must be running on network-accessible host
|
||||
- All SDK operations must use Channel-based architecture
|
||||
**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.)
|
||||
- Support 50+ cameras per installation
|
||||
- Handle 10k+ events/hour during peak activity
|
||||
- Store 90 days audit logs (configurable)
|
||||
- Support 100+ concurrent operators
|
||||
|
||||
## 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)
|
||||
### Constitution Alignment
|
||||
|
||||
**Status**: ✅ **PASS** - Security requirements addressed in architecture
|
||||
✅ **Single Source of Truth**: OpenAPI spec serves as the contract, auto-generated from code
|
||||
✅ **Test-First Development**: TDD enforced with pytest/xUnit, 80% minimum coverage
|
||||
✅ **Simplicity**: REST over custom protocols, JWT over session cookies, direct stream URLs over proxying
|
||||
✅ **Clear Abstractions**: SDK Bridge isolates SDK complexity from Python API layer
|
||||
✅ **Error Handling**: SDK errors translated to HTTP status codes with user-friendly messages
|
||||
✅ **Documentation**: Auto-generated OpenAPI docs at `/docs`, quickstart guide provided
|
||||
✅ **Security First**: JWT authentication, RBAC, rate limiting, audit logging, TLS enforcement
|
||||
|
||||
### ✅ 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
|
||||
### Exceptions to Constitution
|
||||
|
||||
**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
|
||||
None. All design decisions align with constitution principles.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```
|
||||
```text
|
||||
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)
|
||||
├── plan.md # This file (implementation plan)
|
||||
├── spec.md # Feature specification (user stories, requirements)
|
||||
├── research.md # Phase 0 output (technical research, architectural decisions)
|
||||
├── data-model.md # Phase 1 output (entity schemas, relationships, validation)
|
||||
├── quickstart.md # Phase 1 output (developer quick start guide)
|
||||
├── contracts/ # Phase 1 output (API contracts)
|
||||
│ └── openapi.yaml # Complete OpenAPI 3.0 specification
|
||||
└── tasks.md # Phase 2 output (will be generated by /speckit.tasks)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```
|
||||
```text
|
||||
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
|
||||
│ ├── api/ # Python FastAPI application
|
||||
│ │ ├── main.py # FastAPI app entry point
|
||||
│ │ ├── config.py # Configuration management (env vars)
|
||||
│ │ ├── models/ # SQLAlchemy ORM models
|
||||
│ │ │ ├── user.py
|
||||
│ │ │ ├── camera.py
|
||||
│ │ │ ├── event.py
|
||||
│ │ │ └── audit_log.py
|
||||
│ │ ├── schemas/ # Pydantic request/response models
|
||||
│ │ │ ├── auth.py
|
||||
│ │ │ ├── camera.py
|
||||
│ │ │ ├── stream.py
|
||||
│ │ │ ├── event.py
|
||||
│ │ │ └── recording.py
|
||||
│ │ ├── routers/ # FastAPI route handlers
|
||||
│ │ │ ├── auth.py # /api/v1/auth/*
|
||||
│ │ │ ├── cameras.py # /api/v1/cameras/*
|
||||
│ │ │ ├── events.py # /api/v1/events/*
|
||||
│ │ │ ├── recordings.py # /api/v1/recordings/*
|
||||
│ │ │ ├── analytics.py # /api/v1/analytics/*
|
||||
│ │ │ └── system.py # /api/v1/health, /status
|
||||
│ │ ├── services/ # Business logic layer
|
||||
│ │ │ ├── auth_service.py
|
||||
│ │ │ ├── camera_service.py
|
||||
│ │ │ ├── stream_service.py
|
||||
│ │ │ ├── event_service.py
|
||||
│ │ │ └── recording_service.py
|
||||
│ │ ├── clients/ # External service clients
|
||||
│ │ │ ├── sdk_bridge_client.py # gRPC client for SDK bridge
|
||||
│ │ │ └── redis_client.py # Redis connection pooling
|
||||
│ │ ├── middleware/ # FastAPI middleware
|
||||
│ │ │ ├── auth_middleware.py
|
||||
│ │ │ ├── rate_limiter.py
|
||||
│ │ │ └── error_handler.py
|
||||
│ │ ├── websocket/ # WebSocket event streaming
|
||||
│ │ │ ├── connection_manager.py
|
||||
│ │ │ └── event_broadcaster.py
|
||||
│ │ ├── utils/ # Utility functions
|
||||
│ │ │ ├── jwt_utils.py
|
||||
│ │ │ └── error_translation.py
|
||||
│ │ └── migrations/ # Alembic database migrations
|
||||
│ │ └── versions/
|
||||
│ │
|
||||
│ └── sdk-bridge/ # C# gRPC service (SDK wrapper)
|
||||
│ ├── GeViScopeBridge.sln
|
||||
│ ├── GeViScopeBridge/
|
||||
│ │ ├── Program.cs # gRPC server entry point
|
||||
│ │ ├── Services/
|
||||
│ │ │ ├── CameraService.cs # Camera operations
|
||||
│ │ │ ├── StreamService.cs # Stream management
|
||||
│ │ │ ├── EventService.cs # Event subscriptions
|
||||
│ │ │ ├── RecordingService.cs # Recording management
|
||||
│ │ │ └── AnalyticsService.cs # Analytics configuration
|
||||
│ │ ├── SDK/
|
||||
│ │ │ ├── GeViDatabaseWrapper.cs
|
||||
│ │ │ ├── StateQueryHandler.cs
|
||||
│ │ │ ├── DatabaseQueryHandler.cs
|
||||
│ │ │ └── ActionDispatcher.cs
|
||||
│ │ ├── Models/ # Internal data models
|
||||
│ │ └── Utils/
|
||||
│ └── Protos/ # gRPC protocol definitions
|
||||
│ ├── camera.proto
|
||||
│ ├── stream.proto
|
||||
│ ├── event.proto
|
||||
│ ├── recording.proto
|
||||
│ └── analytics.proto
|
||||
│
|
||||
├── 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
|
||||
│ ├── api/
|
||||
│ │ ├── unit/ # Unit tests for Python services
|
||||
│ │ │ ├── test_auth_service.py
|
||||
│ │ │ ├── test_camera_service.py
|
||||
│ │ │ └── test_event_service.py
|
||||
│ │ ├── integration/ # Integration tests with SDK bridge
|
||||
│ │ │ ├── test_camera_operations.py
|
||||
│ │ │ ├── test_stream_lifecycle.py
|
||||
│ │ │ └── test_event_notifications.py
|
||||
│ │ └── contract/ # OpenAPI contract validation
|
||||
│ │ └── test_openapi_compliance.py
|
||||
│ │
|
||||
│ └── sdk-bridge/
|
||||
│ ├── Unit/ # C# unit tests
|
||||
│ │ ├── CameraServiceTests.cs
|
||||
│ │ └── StateQueryTests.cs
|
||||
│ └── Integration/ # Tests with actual SDK
|
||||
│ └── SdkIntegrationTests.cs
|
||||
│
|
||||
├── 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
|
||||
│ ├── architecture.md # System architecture diagram
|
||||
│ ├── sdk-integration.md # SDK integration patterns
|
||||
│ └── deployment.md # Production deployment guide
|
||||
│
|
||||
├── scripts/
|
||||
│ ├── setup_dev_environment.ps1 # Development environment setup
|
||||
│ ├── start_services.ps1 # Start all services (Redis, SDK Bridge, API)
|
||||
│ └── run_tests.sh # Test execution script
|
||||
│
|
||||
├── .env.example # Environment variable template
|
||||
├── requirements.txt # Python dependencies
|
||||
├── pyproject.toml # Python project configuration
|
||||
├── alembic.ini # Database migration configuration
|
||||
└── README.md # Project overview
|
||||
```
|
||||
|
||||
**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
|
||||
**Structure Decision**: Web application structure selected (backend API + SDK bridge service) because:
|
||||
1. SDK requires Windows runtime → isolated C# bridge service
|
||||
2. API layer can run on Linux → flexibility for deployment
|
||||
3. Clear separation between SDK complexity and API logic
|
||||
4. gRPC provides high-performance, typed communication between layers
|
||||
5. Python layer handles web concerns (HTTP, WebSocket, auth, validation)
|
||||
|
||||
## Phase 0 - Research ✅ COMPLETED
|
||||
|
||||
**Deliverable**: [research.md](./research.md)
|
||||
|
||||
**Key Decisions**:
|
||||
1. **SDK Integration Method**: C# gRPC bridge service (not pythonnet, subprocess, or COM)
|
||||
- Rationale: Isolates SDK crashes, maintains type safety, enables independent scaling
|
||||
2. **Stream Architecture**: Direct RTSP URLs with token authentication (not API proxy)
|
||||
- Rationale: Reduces API latency, leverages existing streaming infrastructure
|
||||
3. **Event Distribution**: FastAPI WebSocket + Redis Pub/Sub
|
||||
- Rationale: Supports 1000+ concurrent connections, horizontal scaling capability
|
||||
4. **Authentication**: JWT with Redis session storage
|
||||
- Rationale: Stateless validation, flexible permissions, Redis for quick invalidation
|
||||
5. **Performance Strategy**: Async Python + gRPC connection pooling
|
||||
- Rationale: Non-blocking I/O for concurrent operations, <200ms response targets
|
||||
|
||||
**Critical Discoveries**:
|
||||
- Visual C++ 2010 Redistributable (x86) mandatory for SDK DLL loading
|
||||
- Full GeViSoft installation required (not just SDK)
|
||||
- Windows Forms context needed for mixed-mode C++/CLI assemblies
|
||||
- GeViServer ports: 7700, 7701, 7703 (NOT 7707 as initially assumed)
|
||||
- SDK connection pattern: Create → RegisterCallback → Connect (order matters!)
|
||||
- State Queries use GetFirst/GetNext iteration for enumerating entities
|
||||
|
||||
See [SDK_INTEGRATION_LESSONS.md](../../SDK_INTEGRATION_LESSONS.md) for complete details.
|
||||
|
||||
## Phase 1 - Design ✅ COMPLETED
|
||||
|
||||
**Deliverables**:
|
||||
- [data-model.md](./data-model.md) - Entity schemas, relationships, validation rules
|
||||
- [contracts/openapi.yaml](./contracts/openapi.yaml) - Complete REST API specification
|
||||
- [quickstart.md](./quickstart.md) - Developer quick start guide
|
||||
|
||||
**Key Components**:
|
||||
|
||||
### Data Model
|
||||
- **User**: Authentication, RBAC (viewer/operator/administrator), permissions
|
||||
- **Camera**: Channel-based, capabilities (PTZ, analytics), status tracking
|
||||
- **Stream**: Active sessions with token-authenticated URLs
|
||||
- **Event**: Surveillance occurrences (motion, alarms, analytics)
|
||||
- **Recording**: Video segments with ring buffer management
|
||||
- **AnalyticsConfig**: VMD, NPR, OBTRACK configuration per camera
|
||||
|
||||
### API Endpoints (RESTful)
|
||||
- `POST /api/v1/auth/login` - Authenticate and get JWT tokens
|
||||
- `POST /api/v1/auth/refresh` - Refresh access token
|
||||
- `POST /api/v1/auth/logout` - Invalidate tokens
|
||||
- `GET /api/v1/cameras` - List cameras with filtering
|
||||
- `GET /api/v1/cameras/{id}` - Get camera details
|
||||
- `POST /api/v1/cameras/{id}/stream` - Start video stream
|
||||
- `DELETE /api/v1/cameras/{id}/stream/{stream_id}` - Stop stream
|
||||
- `POST /api/v1/cameras/{id}/ptz` - PTZ control commands
|
||||
- `WS /api/v1/events/stream` - WebSocket event notifications
|
||||
- `GET /api/v1/events` - Query event history
|
||||
- `GET /api/v1/recordings` - Query recordings
|
||||
- `POST /api/v1/recordings/{id}/export` - Export video segment
|
||||
- `GET /api/v1/analytics/{camera_id}` - Get analytics configuration
|
||||
- `POST /api/v1/analytics/{camera_id}` - Configure analytics
|
||||
- `GET /api/v1/health` - System health check
|
||||
- `GET /api/v1/status` - Detailed system status
|
||||
|
||||
### gRPC Service Definitions
|
||||
- **CameraService**: ListCameras, GetCameraDetails, GetCameraStatus
|
||||
- **StreamService**: StartStream, StopStream, GetStreamStatus
|
||||
- **PTZService**: MoveCamera, SetPreset, GotoPreset
|
||||
- **EventService**: SubscribeEvents, UnsubscribeEvents (server streaming)
|
||||
- **RecordingService**: QueryRecordings, StartRecording, StopRecording
|
||||
- **AnalyticsService**: ConfigureAnalytics, GetAnalyticsConfig
|
||||
|
||||
## Phase 2 - Tasks ⏭️ NEXT
|
||||
|
||||
**Command**: `/speckit.tasks`
|
||||
|
||||
Will generate:
|
||||
- Task breakdown with dependencies
|
||||
- Implementation order (TDD-first)
|
||||
- Test plan for each task
|
||||
- Acceptance criteria per task
|
||||
- Time estimates
|
||||
|
||||
**Expected Task Categories**:
|
||||
1. **Infrastructure Setup**: Repository structure, development environment, CI/CD
|
||||
2. **SDK Bridge Foundation**: gRPC server, SDK wrapper, basic camera queries
|
||||
3. **API Foundation**: FastAPI app, authentication, middleware
|
||||
4. **Core Features**: Camera management, stream lifecycle, event notifications
|
||||
5. **Extended Features**: Recording management, analytics configuration
|
||||
6. **Testing & Documentation**: Contract tests, integration tests, deployment docs
|
||||
|
||||
## Phase 3 - Implementation ⏭️ FUTURE
|
||||
|
||||
**Command**: `/speckit.implement`
|
||||
|
||||
Will execute TDD implementation:
|
||||
- Red: Write failing test
|
||||
- Green: Minimal code to pass test
|
||||
- Refactor: Clean up while maintaining passing tests
|
||||
- Repeat for each task
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
**No constitution violations requiring justification.**
|
||||
No constitution violations. All design decisions follow simplicity and clarity principles:
|
||||
- ✅ REST over custom protocols
|
||||
- ✅ JWT over session management
|
||||
- ✅ Direct streaming over proxying
|
||||
- ✅ Clear layer separation (API ↔ Bridge ↔ SDK)
|
||||
- ✅ Standard patterns (FastAPI, gRPC, SQLAlchemy)
|
||||
|
||||
All technical choices align with constitution principles. The selected technology stack (Python + FastAPI + Redis) directly implements the decisions made in the constitution.
|
||||
## Technology Stack Summary
|
||||
|
||||
## Phase 0: Research & Technical Decisions
|
||||
### Python API Layer
|
||||
- **Web Framework**: FastAPI 0.104+
|
||||
- **ASGI Server**: Uvicorn with uvloop
|
||||
- **ORM**: SQLAlchemy 2.0+
|
||||
- **Database**: PostgreSQL 14+
|
||||
- **Cache/PubSub**: Redis 6.0+ (aioredis)
|
||||
- **Authentication**: PyJWT, passlib (bcrypt)
|
||||
- **gRPC Client**: grpcio, protobuf
|
||||
- **Validation**: Pydantic v2
|
||||
- **Testing**: pytest, pytest-asyncio, httpx
|
||||
- **Code Quality**: ruff (linting), black (formatting), mypy (type checking)
|
||||
|
||||
**Status**: Pending - To be completed in research.md
|
||||
### C# SDK Bridge
|
||||
- **Framework**: .NET Framework 4.8 (SDK runtime), .NET 8.0 (gRPC service)
|
||||
- **gRPC**: Grpc.Core, Grpc.Tools
|
||||
- **SDK**: GeViScope SDK 7.9.975.68+ (GeViProcAPINET_4_0.dll)
|
||||
- **Testing**: xUnit, Moq
|
||||
- **Logging**: Serilog
|
||||
|
||||
### Research Topics
|
||||
### Infrastructure
|
||||
- **Database**: PostgreSQL 14+ (user data, audit logs)
|
||||
- **Cache**: Redis 6.0+ (sessions, pub/sub)
|
||||
- **Deployment**: Docker (API layer), Windows Service (SDK bridge)
|
||||
- **CI/CD**: GitHub Actions
|
||||
- **Monitoring**: Prometheus metrics, Grafana dashboards
|
||||
|
||||
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
|
||||
## Commands Reference
|
||||
|
||||
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
|
||||
### Development
|
||||
```bash
|
||||
# Setup environment
|
||||
.\scripts\setup_dev_environment.ps1
|
||||
|
||||
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
|
||||
# Start all services
|
||||
.\scripts\start_services.ps1
|
||||
|
||||
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
|
||||
# Run API server (development)
|
||||
cd src/api
|
||||
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||||
|
||||
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)
|
||||
# Run SDK bridge (development)
|
||||
cd src/sdk-bridge
|
||||
dotnet run --configuration Debug
|
||||
|
||||
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)
|
||||
# Run tests
|
||||
pytest tests/api -v --cov=src/api --cov-report=html # Python
|
||||
dotnet test tests/sdk-bridge/ # C#
|
||||
|
||||
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
|
||||
# Format code
|
||||
ruff check src/api --fix # Python linting
|
||||
black src/api # Python formatting
|
||||
|
||||
**Output Location**: `specs/001-surveillance-api/research.md`
|
||||
# Database migrations
|
||||
alembic upgrade head # Apply migrations
|
||||
alembic revision --autogenerate -m "description" # Create migration
|
||||
```
|
||||
|
||||
## Phase 1: Design & Contracts
|
||||
### API Usage
|
||||
```bash
|
||||
# Authenticate
|
||||
curl -X POST http://localhost:8000/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "sysadmin", "password": "masterkey"}'
|
||||
|
||||
**Status**: Pending - To be completed after Phase 0 research
|
||||
# List cameras
|
||||
curl -X GET http://localhost:8000/api/v1/cameras \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
|
||||
### Deliverables
|
||||
# Start stream
|
||||
curl -X POST http://localhost:8000/api/v1/cameras/{id}/stream \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"resolution": {"width": 1920, "height": 1080, "fps": 30}, "format": "h264"}'
|
||||
|
||||
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
|
||||
# WebSocket events (Python)
|
||||
import websockets
|
||||
uri = f"ws://localhost:8000/api/v1/events/stream?token={TOKEN}"
|
||||
async with websockets.connect(uri) as ws:
|
||||
await ws.send('{"action": "subscribe", "filters": {"event_types": ["motion_detected"]}}')
|
||||
while True:
|
||||
event = await ws.recv()
|
||||
print(event)
|
||||
```
|
||||
|
||||
## 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
|
||||
1. **Run `/speckit.tasks`** to generate Phase 2 task breakdown
|
||||
2. **Review tasks** for sequencing and dependencies
|
||||
3. **Execute `/speckit.implement`** to begin TDD implementation
|
||||
4. **Iterate** through tasks following Red-Green-Refactor cycle
|
||||
|
||||
## References
|
||||
|
||||
- **Specification**: [spec.md](./spec.md) - User stories, requirements, success criteria
|
||||
- **Research**: [research.md](./research.md) - Technical decisions and architectural analysis
|
||||
- **Data Model**: [data-model.md](./data-model.md) - Entity schemas and relationships
|
||||
- **API Contract**: [contracts/openapi.yaml](./contracts/openapi.yaml) - Complete REST API spec
|
||||
- **Quick Start**: [quickstart.md](./quickstart.md) - Developer onboarding guide
|
||||
- **SDK Lessons**: [../../SDK_INTEGRATION_LESSONS.md](../../SDK_INTEGRATION_LESSONS.md) - Critical SDK integration knowledge
|
||||
- **Constitution**: [../../.specify/memory/constitution.md](../../.specify/memory/constitution.md) - Development principles
|
||||
|
||||
---
|
||||
|
||||
**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
|
||||
**Plan Status**: Phase 0 ✅ | Phase 1 ✅ | Phase 2 ⏭️ | Phase 3 ⏭️
|
||||
**Last Updated**: 2025-12-08
|
||||
|
||||
Reference in New Issue
Block a user