geutebruck-api/.specify/memory/constitution.md

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