From 44dc06e7f15054ac2591c01d9504947b18922854 Mon Sep 17 00:00:00 2001 From: Geutebruck API Developer Date: Thu, 13 Nov 2025 03:16:03 -0800 Subject: [PATCH] feat: add complete API specification - 10 prioritized user stories (P1-P3) - 30 functional requirements - 15 success criteria with measurable outcomes - Complete edge cases and risk analysis - Technology-agnostic specification ready for planning phase --- specs/001-surveillance-api/spec.md | 360 +++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 specs/001-surveillance-api/spec.md diff --git a/specs/001-surveillance-api/spec.md b/specs/001-surveillance-api/spec.md new file mode 100644 index 0000000..7f11191 --- /dev/null +++ b/specs/001-surveillance-api/spec.md @@ -0,0 +1,360 @@ +# Feature Specification: Geutebruck Video Surveillance API + +**Feature Branch**: `001-surveillance-api` +**Created**: 2025-11-13 +**Status**: Draft +**Input**: User description: "Complete RESTful API for Geutebruck GeViScope/GeViSoft video surveillance system control" + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Secure API Access (Priority: P1) + +As a developer integrating a custom surveillance application, I need to authenticate to the API securely so that only authorized users can access camera feeds and control functions. + +**Why this priority**: Without authentication, the entire system is insecure and unusable. This is the foundation for all other features and must be implemented first. + +**Independent Test**: Can be fully tested by attempting to access protected endpoints without credentials (should fail), then with valid JWT tokens (should succeed), and delivers a working authentication system that all other features depend on. + +**Acceptance Scenarios**: + +1. **Given** a developer with valid credentials, **When** they request a JWT token from `/api/v1/auth/login`, **Then** they receive a token valid for 1 hour with appropriate user claims +2. **Given** an expired JWT token, **When** they attempt to access a protected endpoint, **Then** they receive a 401 Unauthorized response with clear error message +3. **Given** a valid refresh token, **When** they request a new access token, **Then** they receive a fresh JWT token without re-authenticating +4. **Given** invalid credentials, **When** they attempt to login, **Then** they receive a 401 response and the failed attempt is logged for security monitoring + +--- + +### User Story 2 - Live Video Stream Access (Priority: P1) + +As a security operator, I need to view live video streams from surveillance cameras through the API so that I can monitor locations in real-time from a custom dashboard. + +**Why this priority**: Live video viewing is the core function of surveillance systems. Without this, the system cannot fulfill its primary purpose. + +**Independent Test**: Can be fully tested by requesting stream URLs for configured cameras and verifying that video playback works, delivering immediate value as a basic surveillance viewer. + +**Acceptance Scenarios**: + +1. **Given** an authenticated user with camera view permissions, **When** they request a live stream for camera channel 5, **Then** they receive a stream URL or WebSocket connection that delivers live video within 2 seconds +2. **Given** a camera that is offline, **When** a user requests its stream, **Then** they receive a clear error message indicating the camera is unavailable +3. **Given** multiple concurrent users, **When** they request the same camera stream, **Then** all users can view the stream simultaneously without degradation (up to 100 concurrent streams) +4. **Given** a user without permission for a specific camera, **When** they request its stream, **Then** they receive a 403 Forbidden response + +--- + +### User Story 3 - Camera PTZ Control (Priority: P1) + +As a security operator, I need to control pan-tilt-zoom cameras remotely via the API so that I can adjust camera angles to investigate incidents or track movement. + +**Why this priority**: PTZ control is essential for active surveillance operations and incident response, making it critical for operational use. + +**Independent Test**: Can be fully tested by sending PTZ commands (pan left/right, tilt up/down, zoom in/out) to a PTZ-capable camera and verifying movement occurs, delivering functional camera control capabilities. + +**Acceptance Scenarios**: + +1. **Given** an authenticated operator with PTZ permissions, **When** they send a pan-left command to camera 3, **Then** the camera begins moving left within 500ms and they receive confirmation +2. **Given** a camera that doesn't support PTZ, **When** a user attempts PTZ control, **Then** they receive a clear error indicating PTZ is not available for this camera +3. **Given** two operators controlling the same PTZ camera, **When** they send conflicting commands simultaneously, **Then** the system queues commands and notifies operators of the conflict +4. **Given** a PTZ command in progress, **When** the user sends a stop command, **Then** the camera movement stops immediately + +--- + +### User Story 4 - Real-time Event Notifications (Priority: P1) + +As a security operator, I need to receive instant notifications when surveillance events occur (motion detection, alarms, sensor triggers) so that I can respond quickly to security incidents. + +**Why this priority**: Real-time alerts are critical for security effectiveness. Without event notifications, operators must constantly monitor all cameras manually. + +**Independent Test**: Can be fully tested by subscribing to event notifications via WebSocket, triggering a test alarm, and verifying notification delivery within 100ms, providing functional event monitoring. + +**Acceptance Scenarios**: + +1. **Given** an authenticated user with event subscription permissions, **When** they connect to the WebSocket endpoint `/api/v1/events/stream`, **Then** they receive a connection confirmation and can subscribe to specific event types +2. **Given** a motion detection event occurs on camera 7, **When** a subscribed user is listening for video analytics events, **Then** they receive a notification within 100ms containing event type, camera channel, timestamp, and relevant data +3. **Given** a network disconnection, **When** the WebSocket reconnects, **Then** the user automatically re-subscribes to their previous event types and receives any missed critical events +4. **Given** 1000+ concurrent WebSocket connections, **When** an event occurs, **Then** all subscribed users receive notifications without system degradation + +--- + +### User Story 5 - Recording Management (Priority: P2) + +As a security administrator, I need to manage video recording settings and query recorded footage so that I can configure retention policies and retrieve historical video for investigations. + +**Why this priority**: Important for compliance and investigations but not required for basic live monitoring. Can be added after core live viewing is functional. + +**Independent Test**: Can be fully tested by configuring recording schedules, starting/stopping recording on specific cameras, and querying recorded footage by time range, delivering complete recording management. + +**Acceptance Scenarios**: + +1. **Given** an authenticated administrator, **When** they request recording start on camera 2, **Then** the camera begins recording and they receive confirmation with recording ID +2. **Given** a time range query for 2025-11-12 14:00 to 16:00 on camera 5, **When** an investigator searches for recordings, **Then** they receive a list of available recording segments with download URLs +3. **Given** the ring buffer is at 90% capacity, **When** an administrator checks recording capacity, **Then** they receive an alert indicating low storage and oldest recordings that will be overwritten +4. **Given** scheduled recording configured for nighttime hours, **When** the schedule time arrives, **Then** recording automatically starts and stops according to the schedule + +--- + +### User Story 6 - Video Analytics Configuration (Priority: P2) + +As a security administrator, I need to configure video content analysis features (motion detection, object tracking, perimeter protection) so that the system can automatically detect security-relevant events. + +**Why this priority**: Enhances system capabilities but requires basic video viewing to already be working. Analytics configuration is valuable but not essential for day-one operation. + +**Independent Test**: Can be fully tested by configuring motion detection zones on a camera, triggering motion, and verifying analytics events are generated, delivering automated detection capabilities. + +**Acceptance Scenarios**: + +1. **Given** an authenticated administrator, **When** they configure motion detection zones on camera 4, **Then** the configuration is saved and motion detection activates within those zones +2. **Given** motion detection configured with sensitivity level 7, **When** motion occurs in the detection zone, **Then** a motion detection event is generated and sent to event subscribers +3. **Given** object tracking enabled on camera 6, **When** a person enters the frame, **Then** the system assigns a tracking ID and sends position updates for the duration they remain visible +4. **Given** multiple analytics enabled on one camera (VMD + OBTRACK), **When** events occur, **Then** all configured analytics generate appropriate events without interfering with each other + +--- + +### User Story 7 - Multi-Camera Management (Priority: P2) + +As a security operator, I need to view and manage multiple cameras simultaneously via the API so that I can coordinate surveillance across different locations and camera views. + +**Why this priority**: Enhances operational efficiency but single-camera operations must work first. Important for professional surveillance operations managing multiple sites. + +**Independent Test**: Can be fully tested by retrieving a list of all available cameras, requesting multiple streams simultaneously, and grouping cameras by location, delivering multi-camera coordination. + +**Acceptance Scenarios**: + +1. **Given** an authenticated user, **When** they request the camera list from `/api/v1/cameras`, **Then** they receive all cameras they have permission to view with status, channel ID, capabilities, and location metadata +2. **Given** multiple cameras in the same location, **When** a user requests grouped camera data, **Then** cameras are organized by configured location/zone for easy navigation +3. **Given** a user viewing 16 camera streams, **When** they request streams via the API, **Then** all 16 streams initialize and display without individual stream degradation +4. **Given** a camera goes offline while being viewed, **When** the API detects the disconnection, **Then** the camera status updates and subscribers receive a notification + +--- + +### User Story 8 - License Plate Recognition Integration (Priority: P3) + +As a security operator monitoring vehicle access, I need to receive automatic license plate recognition events so that I can track vehicle entry/exit and match against watchlists. + +**Why this priority**: Valuable for specific use cases (parking, access control) but not universal. Only relevant if NPR hardware is available and configured. + +**Independent Test**: Can be fully tested by configuring NPR zones, driving a test vehicle through the zone, and verifying plate recognition events with captured plate numbers, delivering automated vehicle tracking. + +**Acceptance Scenarios**: + +1. **Given** NPR configured on camera 9 with recognition zone defined, **When** a vehicle with readable plate enters the zone, **Then** an NPR event is generated containing plate number, country code, timestamp, confidence score, and image snapshot +2. **Given** a watchlist of plates configured, **When** a matching plate is recognized, **Then** a high-priority alert is sent to subscribers with match details +3. **Given** poor lighting or plate obstruction, **When** recognition fails or confidence is low (<70%), **Then** the event includes the best-guess plate and confidence level so operators can manually verify +4. **Given** continuous vehicle traffic, **When** multiple vehicles pass through rapidly, **Then** each vehicle generates a separate NPR event with unique tracking ID + +--- + +### User Story 9 - Video Export and Backup (Priority: P3) + +As a security investigator, I need to export specific video segments for evidence or sharing so that I can provide footage to law enforcement or use in incident reports. + +**Why this priority**: Useful for investigations but not needed for live monitoring or basic recording. Can be added as an enhancement after core features are stable. + +**Independent Test**: Can be fully tested by requesting export of a 10-minute segment from camera 3, receiving a download URL, and verifying the exported file plays correctly, delivering evidence export capability. + +**Acceptance Scenarios**: + +1. **Given** an authenticated investigator, **When** they request export of camera 8 footage from 10:00-10:15 on 2025-11-12, **Then** they receive an export job ID and can poll for completion status +2. **Given** an export job in progress, **When** the investigator checks job status, **Then** they receive progress percentage and estimated completion time +3. **Given** a completed export, **When** the investigator downloads the file, **Then** they receive a standard video format (MP4/AVI) playable in common media players with embedded timestamps +4. **Given** an export request for a time range with no recordings, **When** processing occurs, **Then** the user receives a clear message indicating no footage available for that timeframe + +--- + +### User Story 10 - System Health Monitoring (Priority: P3) + +As a system administrator, I need to monitor API and surveillance system health status so that I can proactively identify and resolve issues before they impact operations. + +**Why this priority**: Important for production systems but not required for initial deployment. Health monitoring is an operational enhancement that can be added incrementally. + +**Independent Test**: Can be fully tested by querying the health endpoint, checking SDK connectivity status, and verifying alerts when components fail, delivering system observability. + +**Acceptance Scenarios**: + +1. **Given** the API is running, **When** an unauthenticated user requests `/api/v1/health`, **Then** they receive system status including API uptime, SDK connectivity, database status, and overall health score +2. **Given** the GeViScope SDK connection fails, **When** health is checked, **Then** the health endpoint returns degraded status with specific SDK error details +3. **Given** disk space for recordings drops below 10%, **When** monitoring checks run, **Then** a warning is included in health status and administrators receive notification +4. **Given** an administrator monitoring performance, **When** they request detailed metrics, **Then** they receive statistics on request throughput, average response times, active WebSocket connections, and concurrent streams + +--- + +### Edge Cases + +- What happens when a camera is physically disconnected while being actively viewed by 20 users? +- How does the system handle authentication when the GeViScope SDK is temporarily unavailable? +- What occurs when a user requests PTZ control on a camera that another user is already controlling? +- How does recording behave when the ring buffer reaches capacity during an active alarm event? +- What happens when network latency causes event notifications to queue up - does the system batch or drop old events? +- How does the API respond when a user has permission for 50 cameras but only 30 are currently online? +- What occurs when a WebSocket connection drops mid-event notification? +- How does the system handle time zone differences between the API server, GeViScope SDK, and client applications? +- What happens when an export request spans a time range that crosses a recording gap (camera was off)? +- How does analytics configuration respond when applied to a camera that doesn't support the requested analytics type (e.g., NPR on a camera without NPR hardware)? + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: System MUST authenticate all API requests using JWT tokens with configurable expiration (default 1 hour for access tokens, 7 days for refresh tokens) +- **FR-002**: System MUST implement role-based access control with at least three roles: viewer (read-only camera access), operator (camera control + viewing), administrator (full system configuration) +- **FR-003**: System MUST provide granular permissions allowing access restriction per camera channel +- **FR-004**: System MUST expose live video streams for all configured GeViScope channels with initialization time under 2 seconds +- **FR-005**: System MUST support PTZ control operations (pan, tilt, zoom, preset positions) with command response time under 500ms +- **FR-006**: System MUST provide WebSocket endpoint for real-time event notifications with delivery latency under 100ms +- **FR-007**: System MUST support event subscriptions by type (alarms, analytics, system events) and by camera channel +- **FR-008**: System MUST translate all GeViScope SDK actions to RESTful API endpoints following the pattern `/api/v1/{resource}/{id}/{action}` +- **FR-009**: System MUST handle concurrent video stream requests from minimum 100 simultaneous users without degradation +- **FR-010**: System MUST support WebSocket connections from minimum 1000 concurrent clients for event notifications +- **FR-011**: System MUST provide recording management including start/stop recording, schedule configuration, and recording status queries +- **FR-012**: System MUST expose recording capacity metrics including total capacity, free space, recording depth in hours, and oldest recording timestamp +- **FR-013**: System MUST support video analytics configuration for VMD (Video Motion Detection), OBTRACK (object tracking and people counting), NPR (license plate recognition), and G-Tect (perimeter protection) where hardware supports these features +- **FR-014**: System MUST provide query capabilities for recorded footage by channel, time range, and event association +- **FR-015**: System MUST export video segments in standard formats (MP4 or AVI) with embedded timestamps and metadata +- **FR-016**: System MUST log all authentication attempts (successful and failed) with username, source IP, and timestamp +- **FR-017**: System MUST audit log all privileged operations including PTZ control, recording management, configuration changes, and user management with operator ID, action, target, and timestamp +- **FR-018**: System MUST gracefully handle camera offline scenarios by returning appropriate error codes and status information +- **FR-019**: System MUST implement retry logic for transient SDK communication failures (3 attempts with exponential backoff) +- **FR-020**: System MUST provide health check endpoint returning API status, SDK connectivity, database availability, and system resource usage +- **FR-021**: System MUST serve auto-generated OpenAPI/Swagger documentation at `/docs` endpoint +- **FR-022**: System MUST return meaningful error messages with error codes for all failure scenarios without exposing internal stack traces +- **FR-023**: System MUST support API versioning in URL path (v1, v2) to allow backward-compatible evolution +- **FR-024**: System MUST rate limit authentication attempts to prevent brute force attacks (max 5 attempts per IP per minute) +- **FR-025**: System MUST enforce TLS 1.2+ for all API communication in production environments +- **FR-026**: System MUST translate Windows error codes from GeViScope SDK to appropriate HTTP status codes with user-friendly messages +- **FR-027**: System MUST support filtering and pagination for endpoints returning lists (camera lists, recording lists, event histories) +- **FR-028**: System MUST handle GeViScope SDK ring buffer architecture by exposing recording depth and capacity warnings when storage approaches limits +- **FR-029**: System MUST support event correlation using ForeignKey parameter to link events with external system identifiers +- **FR-030**: System MUST allow configuration of pre-alarm and post-alarm recording duration for event-triggered recordings + +### Key Entities + +- **Camera**: Represents a video input channel with properties including channel ID, name, location, capabilities (PTZ support, analytics support), current status (online/offline/recording), stream URL, and permissions +- **User**: Authentication entity with username, hashed password, assigned role, permissions list, JWT tokens, and audit trail of actions +- **Event**: Surveillance occurrence with type ID (motion, alarm, analytics), event ID (instance), channel, timestamp, severity, associated data (e.g., NPR plate number, object tracking ID), and foreign key for external correlation +- **Recording**: Video footage segment with channel, start time, end time, file size, recording trigger (scheduled, event, manual), and retention policy +- **Stream**: Active video stream session with channel, user, start time, format, quality level, and connection status +- **Analytics Configuration**: Video content analysis settings with type (VMD, NPR, OBTRACK, G-Tect, CPA), channel, enabled zones/regions, sensitivity parameters, and alert thresholds +- **PTZ Preset**: Saved camera position with preset ID, channel, name, pan/tilt/zoom values +- **Audit Log Entry**: Security and operations record with timestamp, user, action type, target resource, outcome (success/failure), and detailed parameters + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: Developers can authenticate and make their first successful API call within 10 minutes of reading the quick start documentation +- **SC-002**: Security operators can view live video from any authorized camera with video appearing on screen within 2 seconds of request +- **SC-003**: PTZ camera movements respond to operator commands within 500ms, providing responsive control for incident investigation +- **SC-004**: Real-time event notifications are delivered to subscribed clients within 100ms of event occurrence, enabling rapid incident response +- **SC-005**: System supports 100 concurrent video streams without any individual stream experiencing frame drops or quality degradation +- **SC-006**: System handles 1000+ concurrent WebSocket connections for event notifications with message delivery rates exceeding 99.9% +- **SC-007**: API metadata queries (camera lists, status checks, user info) return results in under 200ms for 95% of requests +- **SC-008**: System maintains 99.9% uptime during production operation, measured as availability of the health check endpoint +- **SC-009**: Operators can successfully complete all primary surveillance tasks (view cameras, control PTZ, receive alerts, query recordings) without requiring technical support +- **SC-010**: API documentation is sufficiently complete that 90% of integration questions can be answered by reading the OpenAPI specification and examples +- **SC-011**: Failed authentication attempts are logged and administrators receive alerts for potential security threats within 5 minutes of detection +- **SC-012**: Video export requests for segments up to 1 hour complete within 5 minutes and produce files playable in standard media players +- **SC-013**: System gracefully handles camera failures, with offline cameras clearly indicated and the API remaining operational for all other cameras +- **SC-014**: Recording capacity warnings are provided when storage reaches 80% capacity, allowing administrators to take action before recordings are lost +- **SC-015**: During peak load (500 requests/second), the system maintains response time targets with no more than 0.1% of requests timing out or failing + +### Business Impact + +- **BI-001**: Custom surveillance applications can be developed and deployed in under 1 week using the API, compared to 4-6 weeks with direct SDK integration +- **BI-002**: Reduction in support requests by 60% compared to direct SDK usage, as API abstracts SDK complexity and provides clear error messages +- **BI-003**: Enable integration with third-party systems (access control, building management, alarm systems) that previously couldn't interface with GeViScope +- **BI-004**: Support mobile and web-based surveillance clients that can't run Windows SDK, expanding platform compatibility + +## Dependencies *(mandatory)* + +### External Dependencies + +- **GeViScope SDK 7.9.975.68+**: Core surveillance system SDK providing video streams, camera control, and event management +- **Windows Server 2016+** or **Windows 10/11**: Required platform for GeViScope SDK operation +- **Active Geutebruck Surveillance System**: Physical cameras, recording servers, and network infrastructure must be configured and operational + +### Assumptions + +- GeViScope SDK is already installed and configured with cameras connected and functional +- Network connectivity exists between API server and GeViScope SDK service +- Sufficient storage capacity available for ring buffer recording as configured in GeViScope +- Client applications can consume RESTful APIs and WebSocket connections +- Authentication credentials for GeViScope SDK are available for API integration +- Standard industry retention and performance expectations apply unless otherwise specified by regulations +- JWT-based authentication is acceptable for client applications (OAuth2 flow not required initially) +- Video streaming will use existing GeViScope streaming protocols (direct URL or stream proxy to be determined during technical planning) +- Redis or similar in-memory database available for session management and caching +- SSL/TLS certificates can be obtained and configured for production deployment + +### Out of Scope + +- Direct camera hardware management (firmware updates, network configuration) - handled by GeViScope +- Video storage architecture changes - API uses existing GeViScope ring buffer +- Custom video codec development - API uses GeViScope's supported formats +- Mobile native SDKs - this specification covers REST API only, client SDKs are separate future work +- Video wall display management - API provides data, UI implementation is client responsibility +- Bi-directional audio communication - audio monitoring may be included but two-way audio is deferred +- Access control system integration - API provides data interfaces but integration logic is external +- Custom analytics algorithm development - API configures existing GeViScope analytics, custom algorithms are separate work + +## Constraints + +### Technical Constraints + +- API must run on Windows platform due to GeViScope SDK dependency +- All video operations must use GeViScope's channel-based architecture (Channel ID parameter required) +- Event notifications limited to events supported by GeViScope SDK action system +- Recording capabilities bounded by GeViScope SDK's ring buffer architecture +- Analytics features only available for cameras with hardware support (cannot enable NPR on camera without NPR hardware) + +### Performance Constraints + +- Maximum concurrent streams limited by GeViScope SDK license and hardware capacity +- WebSocket connection limits determined by operating system socket limits and available memory +- API response times dependent on GeViScope SDK response characteristics +- Video stream initialization time includes SDK processing delay (targeted under 2 seconds total) + +### Security Constraints + +- All API communication must use TLS 1.2+ in production +- JWT tokens must have configurable expiration to balance security and usability +- Audit logging must be tamper-evident (append-only, with checksums or write to immutable storage) +- Credentials for GeViScope SDK must be stored securely (environment variables, key vault) + +## Risk Analysis + +### High Impact Risks + +1. **GeViScope SDK Stability**: If SDK crashes or becomes unresponsive, API loses all functionality + - *Mitigation*: Implement circuit breaker pattern, health monitoring, automatic SDK reconnection logic + +2. **Performance Under Load**: Concurrent stream limits may be lower than target (100 streams) + - *Mitigation*: Load testing early in development, potentially implement stream quality adaptation + +3. **Windows Platform Dependency**: Restricts deployment options and increases operational complexity + - *Mitigation*: Document Windows container approach, design SDK bridge for potential future Linux support via proxy + +### Medium Impact Risks + +4. **SDK Version Compatibility**: Future GeViScope SDK updates may break API integration + - *Mitigation*: Version testing before SDK upgrades, maintain SDK abstraction layer + +5. **WebSocket Scalability**: 1000+ concurrent connections may stress resources + - *Mitigation*: Connection pooling, message batching, load testing, potential horizontal scaling + +6. **Network Latency**: Event notifications and video streams sensitive to network conditions + - *Mitigation*: Document network requirements, implement connection quality monitoring + +### Low Impact Risks + +7. **Documentation Drift**: API changes may outpace documentation updates + - *Mitigation*: Auto-generated OpenAPI specs from code, documentation review in PR process + +## Notes + +This specification focuses on **WHAT** the API enables users to do and **WHY** it's valuable, avoiding **HOW** it will be implemented. Technical decisions about Python/FastAPI, specific database choices, video streaming protocols, and SDK integration mechanisms will be made during the `/speckit.plan` phase. + +The user stories are prioritized for iterative development: +- **P1 stories** (1-4) form the MVP: authentication, live viewing, PTZ control, event notifications +- **P2 stories** (5-7) add operational capabilities: recording management, analytics configuration, multi-camera coordination +- **P3 stories** (8-10) provide enhancements: specialized analytics (NPR), evidence export, system monitoring + +Each story is independently testable and delivers standalone value, enabling flexible development sequencing and incremental delivery to users.