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

<!--
Sync Impact Report
- Version change: [INITIAL] → 1.0.0
- Initial constitution created for Geutebruck Video Surveillance API
- Principles defined: Security-First, RESTful API Design, Test-Driven Development, SDK Abstraction, Performance & Reliability
- Sections added: Technical Constraints, Quality Standards
- Templates requiring updates: ✅ All templates aligned with principles
- Follow-up TODOs: None
-->

# 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