# Geutebruck Video Surveillance API Constitution ## Core Principles ### I. Security-First (NON-NEGOTIABLE) Security is paramount in surveillance systems. Every feature MUST be designed with security as the primary concern, not an afterthought. **Mandatory Requirements:** - JWT-based authentication required for all endpoints (except `/health` and `/docs`) - TLS 1.2+ encryption for all API communication in production - Role-based access control (RBAC) with granular permissions per camera/channel - API keys managed securely via environment variables or secret management services - All privileged operations (PTZ control, recording management, configuration changes) MUST be audit logged with user, timestamp, and action details - No credentials or secrets in source code or version control - Failed authentication attempts rate-limited and logged **Rationale:** Video surveillance systems handle sensitive security footage and critical infrastructure. A breach could compromise physical security, violate privacy regulations, and expose organization to legal liability. ### II. RESTful API Design The API MUST follow RESTful principles to ensure consistency, predictability, and developer-friendly integration. **Mandatory Requirements:** - Resources represent surveillance entities (cameras, events, recordings, channels) - Standard HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE (remove) - Consistent URL structure: `/api/v{version}/{resource}/{id}/{action}` - JSON as primary data exchange format - HTTP status codes accurately reflect operation results (200, 201, 400, 401, 403, 404, 500, 503) - Stateless operations (authentication via JWT tokens, not server-side sessions) - API versioning in URL path (v1, v2, etc.) - major version for breaking changes only - Hypermedia links (HATEOAS) for navigation where beneficial **Rationale:** REST conventions reduce cognitive load for API consumers, enable caching and scalability, and integrate seamlessly with modern web development tools and frameworks. ### III. Test-Driven Development (NON-NEGOTIABLE) Tests MUST be written before implementation code. No production code without corresponding tests. **Mandatory Requirements:** - Red-Green-Refactor cycle strictly enforced: 1. Write failing test that defines expected behavior 2. Implement minimal code to make test pass 3. Refactor while keeping tests green - Minimum 80% code coverage for SDK bridge layer (critical integration point) - Unit tests for all business logic and utility functions - Integration tests for all API endpoints - End-to-end tests with GeViScope SDK simulator or test instance - All tests MUST pass before merge to main branch - Test failures block CI/CD pipeline **Rationale:** TDD ensures code correctness, prevents regressions, documents expected behavior, and enables confident refactoring. Critical for reliability in security-critical surveillance systems. ### IV. SDK Abstraction Layer The GeViScope SDK integration MUST be isolated behind a clean abstraction layer to maintain flexibility and testability. **Mandatory Requirements:** - SDK Bridge Layer acts as adapter between REST API and GeViScope Action system - Bridge layer MUST translate: - REST endpoints → GeViScope Actions (VideoActions, SystemActions, etc.) - GeViScope Events → WebSocket event notifications - Windows error codes → HTTP status codes with meaningful messages - Channel-based operations to API resource model - Bridge layer MUST be mockable for testing without actual SDK - No direct SDK calls from API route handlers - Bridge interface designed for potential future multi-SDK support **Rationale:** Abstraction enables testing without hardware, allows SDK version upgrades without API changes, and provides potential path to support multiple surveillance SDKs in future. ### V. Performance & Reliability The API MUST meet performance targets and handle failures gracefully to ensure operational reliability. **Mandatory Performance Targets:** - Metadata queries (camera lists, status): < 200ms (p95) - PTZ control commands: < 500ms from request to camera movement initiation - Event notifications: < 100ms from SDK event to WebSocket delivery - Video stream initialization: < 2 seconds from request to first frame - Support minimum 100 concurrent video streams - Handle 1000+ concurrent WebSocket connections - API throughput: 500 requests/second under normal load **Mandatory Reliability Requirements:** - All exceptions caught and translated to appropriate HTTP status codes - Meaningful error messages with error codes (no stack traces to clients) - Graceful degradation under load (return 503 Service Unavailable vs crashing) - Retry logic for transient SDK failures (3 attempts, exponential backoff) - Circuit breaker pattern for SDK communication to prevent cascade failures - API remains operational when individual cameras offline - Health check endpoint (`/api/v1/health`) returns system status including SDK connectivity **Rationale:** Surveillance systems require high availability and low latency for effective security operations. Performance degradation or system failures could result in missed security incidents. ## Technical Constraints ### Platform Requirements **Windows Environment:** - GeViScope SDK is Windows-native (DLL/COM based) - API service MUST run on Windows Server 2016+ or Windows 10/11 - Docker deployment requires Windows containers (or Linux host with Windows VM bridge) - Architecture designed to potentially support Linux deployment via SDK proxy service in future **SDK Dependencies:** - GeViScope SDK version 7.9.975.68 or higher required - GeViSoft 6.0.1.5+ optional for extended integration - Compatibility testing required before upgrading to new SDK versions ### GeViScope SDK Architecture Integration **Action-Based Event System:** - All SDK operations are "Actions" with typed parameters and specific invocation patterns - Actions categorized: System, Video, Camera, Audio, Device, Viewer, Events - API endpoints MUST map to appropriate SDK actions - Event listeners MUST be registered for real-time notification support **Channel-Based Operations:** - Video sources identified by Channel ID (integer) - Most video operations require Channel parameter - Channel enumeration performed at API startup - Dynamic channel addition/removal handled via SDK event notifications **Event Management:** - Events have TypeID (event type) and EventID (specific instance) - Support Start/Stop/Kill operations on events - ForeignKey parameter enables external system correlation - Multiple simultaneous events of same type possible **Database Ring Buffer:** - GeViScope uses ring buffer architecture for recording storage - Recording depth measured in hours - API MUST expose recording capacity metrics - Handle ring buffer wrap-around and oldest data eviction ### Technology Stack **Selected Technologies:** - **Language:** Python 3.11+ - **Framework:** FastAPI (async support, auto OpenAPI docs, type safety) - **Database:** Redis (sessions, API key caching, rate limiting) - **WebSocket:** FastAPI native WebSocket support - **Documentation:** Auto-generated OpenAPI/Swagger at `/docs` - **Testing:** Pytest for unit and integration tests - **Container:** Docker with Windows base images **Rationale:** Python FastAPI provides optimal balance of developer productivity, performance, and built-in API documentation. Redis offers high-performance in-memory operations for real-time requirements. ## Quality Standards ### Code Quality Requirements **Testing:** - Minimum 80% code coverage enforced in CI/CD - Unit tests for all business logic (services, utilities) - Integration tests for all API endpoints - End-to-end tests with SDK simulator - Performance tests for concurrency and latency targets - Security tests for authentication and authorization **Code Review:** - All changes via pull request - Minimum one reviewer approval required - Automated checks MUST pass: linting (ruff/black), type checking (mypy), tests - Constitution compliance verified during review - Security review for authentication/authorization changes **Code Style:** - Python PEP 8 with Black formatter (line length 100) - Type hints mandatory for all function signatures - Docstrings for public APIs (Google style) - Meaningful variable names (descriptive, no cryptic abbreviations) ### Documentation Requirements **API Documentation:** - OpenAPI/Swagger specification auto-generated and served at `/docs` - All endpoints documented with descriptions, parameters, response schemas - Example requests and responses for each endpoint - Authentication/authorization requirements clearly stated - Error response formats documented **Code Documentation:** - README.md with quick start guide (< 10 minutes to first API call) - Architecture Decision Records (ADRs) for significant technical decisions - SDK action mapping documented in bridge layer - Inline comments for complex SDK integration logic **Deployment Documentation:** - Installation instructions for Windows Server environment - Configuration guide with environment variable reference - Troubleshooting guide for common issues - Security hardening checklist for production deployment ### API Versioning & Backward Compatibility **Versioning Policy:** - Semantic versioning: MAJOR.MINOR.PATCH - Major version (v1 → v2): Breaking changes to API contract - Minor version: New endpoints or optional parameters added - Patch version: Bug fixes, no API contract changes **Backward Compatibility Rules:** - Within major version: - ✅ CAN add new endpoints - ✅ CAN add optional parameters - ✅ CAN add new fields to responses - ❌ CANNOT remove endpoints - ❌ CANNOT remove required parameters - ❌ CANNOT remove response fields - ❌ CANNOT change parameter types - Support minimum 2 concurrent major versions during transition - Deprecation warnings via HTTP header for 6 months before removal - Breaking changes documented in CHANGELOG with migration guide ## Governance ### Constitution Authority This constitution supersedes all other development practices and guidelines. When conflicts arise, constitution principles take precedence. ### Amendment Process **Proposing Amendments:** 1. Create Architecture Decision Record (ADR) documenting proposed change 2. Include rationale, impact analysis, and alternatives considered 3. Identify affected code and migration requirements 4. Present to project stakeholders for discussion **Approval Requirements:** - Consensus from project stakeholders - Impact assessment on existing implementations - Migration plan for affected code if applicable **Version Increment Rules:** - MAJOR: Principle removal or fundamental redefinition (breaking governance changes) - MINOR: New principle added or material expansion of existing guidance - PATCH: Clarifications, wording improvements, non-semantic refinements ### Compliance & Enforcement **Development Workflow:** - All pull requests MUST verify compliance with constitution principles - Constitution violations require explicit justification and approval - Complexity that contradicts principles MUST be documented in ADR - Regular retrospectives to assess constitution effectiveness **Quality Gates:** - Constitution checklist review before feature implementation - Pre-commit hooks enforce code style and testing requirements - CI/CD pipeline blocks non-compliant changes - Security audits verify security-first principle adherence **Conflict Resolution:** - When technical constraints conflict with principles, document in ADR - Temporary violations require explicit time-bounded exception approval - Permanent conflicts trigger constitution amendment discussion ### Continuous Improvement **Review Cadence:** - Constitution reviewed quarterly for relevance and effectiveness - Major retrospectives after significant project milestones - Performance benchmarking validates targets remain achievable - Security audits confirm security-first principle compliance **Evolution Philosophy:** - Constitution evolves based on project learning and changing requirements - Data-driven amendments preferred over opinion-based changes - Simplicity valued - remove outdated constraints rather than accumulate --- **Version**: 1.0.0 | **Ratified**: 2025-11-13 | **Last Amended**: 2025-11-13