geutebruck-api/specs/001-surveillance-api/spec.md

Feature Specification: Geutebruck Unified Video Surveillance API

Feature Branch: 001-surveillance-api Created: 2025-11-13 Updated: 2025-12-16 (Configuration Management + Critical Bug Fixes) Status: In Progress Input: "Complete RESTful API for Geutebruck GeViSoft/GeViScope unified video surveillance system control with multi-instance support"

Architecture Overview

This API provides a unified interface to control both GeViSoft (management platform) and multiple GeViScope instances (video servers):

Geutebruck Unified API
│
├── GeViSoft Layer (Management)
│   └── GeViServer Connection
│       ├── System-wide alarm management
│       ├── Event coordination across GeViScope instances
│       ├── Action mapping and automation
│       └── Cross-system orchestration
│
└── GeViScope Layer (Video Operations)
    ├── GeViScope Instance "main" (GSCServer - localhost)
    │   ├── Cameras: 101027-101041
    │   └── Monitors: 1-256
    ├── GeViScope Instance "parking" (GSCServer - 192.168.1.100)
    │   ├── Cameras: 201001-201020
    │   └── Monitors: 1-64
    └── GeViScope Instance "warehouse" (GSCServer - 192.168.1.101)
        ├── Cameras: 301001-301050
        └── Monitors: 1-128

Key Concepts:

• GeViSoft = Management platform controlling multiple GeViScope instances (1 per system)
• GeViScope = Video server instances handling cameras, monitors, video routing (N per system)
• Monitors (Video Outputs) = Logical display channels (NOT physical displays, require viewer apps)
• CrossSwitch = Video routing command (camera → monitor at server level)
• GSCView = Viewer application that displays video outputs

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 - Multi-Instance GeViScope Management (Priority: P1)

As a system administrator, I need to manage multiple GeViScope instances through a single API so that I can control video operations across different locations and servers.

Why this priority: Multi-instance support is core to the unified architecture. Without it, the API can only control one GeViScope server, limiting scalability.

Independent Test: Can be fully tested by configuring multiple GeViScope instances, querying available instances, and executing operations on specific instances.

Acceptance Scenarios:

1. Given three GeViScope instances configured (main, parking, warehouse), When a user requests /api/v1/geviscope/instances, Then they receive a list of all instances with status, camera count, and connection state
2. Given operations targeting a specific instance, When a user calls /api/v1/geviscope/parking/cameras, Then they receive only cameras from the parking instance
3. Given a default instance configured, When a user calls /api/v1/cameras without instance ID, Then the request routes to the default instance
4. Given one GeViScope instance is offline, When operations target that instance, Then the API returns clear error messages while other instances remain operational

---

User Story 3 - Video CrossSwitch and Monitor Control (Priority: P1)

As a security operator, I need to route camera video feeds to specific monitors via CrossSwitch commands so that I can dynamically control what video appears on display systems.

Why this priority: CrossSwitch is the core video routing mechanism in GeViScope systems. Without it, operators cannot control video distribution to displays.

Independent Test: Can be fully tested by executing CrossSwitch commands to route cameras to monitors, verifying routes in the routing table, and clearing monitor assignments.

Acceptance Scenarios:

1. Given camera 101038 and monitor 1 exist, When an operator sends POST /api/v1/crossswitch with {camera_id: 101038, monitor_id: 1}, Then the camera video is routed to monitor 1 at the server level and a route record is created
2. Given an active route exists, When an operator queries /api/v1/crossswitch/routing, Then they receive a list of all active camera→monitor routes with timestamps and user who created them
3. Given a monitor displaying video, When an operator sends DELETE /api/v1/crossswitch/{monitor_id}, Then the monitor is cleared and the route is marked inactive
4. Given multiple monitors in a monitor group, When an alarm triggers CrossSwitch actions, Then all designated cameras are routed to their assigned monitors automatically

---

User Story 4 - 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 101038, Then they receive a stream URL 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 5 - 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 101038, 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 6 - 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 /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 101038, When a subscribed user is listening for video analytics events, Then they receive a notification within 100ms containing event type, camera ID, GeViScope instance, timestamp, and relevant data
3. Given a network disconnection, When the WebSocket reconnects, Then the user automatically re-subscribes and receives any missed critical events
4. Given events from multiple GeViScope instances, When subscribed users receive notifications, Then each event clearly indicates which instance it originated from

---

User Story 7 - GeViSoft Alarm Management (Priority: P2)

As a security administrator, I need to configure and manage alarms in GeViSoft so that I can automate responses to security events across multiple GeViScope instances.

Why this priority: Important for advanced automation but basic video operations must work first. Alarms coordinate actions across the system.

Independent Test: Can be fully tested by creating an alarm configuration, triggering the alarm via an event, and verifying that configured actions (CrossSwitch, notifications) execute correctly.

Acceptance Scenarios:

1. Given an authenticated administrator, When they create an alarm with start/stop/acknowledge actions, Then the alarm is saved in GeViSoft and can be triggered by configured events
2. Given an alarm configured to route cameras 101038 and 101039 to monitors 1-2, When the alarm triggers, Then CrossSwitch actions execute and cameras appear on designated monitors
3. Given an active alarm, When an operator acknowledges it via /api/v1/gevisoft/alarms/{alarm_id}/acknowledge, Then acknowledge actions execute and alarm state updates
4. Given multiple GeViScope instances, When an alarm spans instances (e.g., camera from instance A to monitor in instance B), Then the API coordinates cross-instance operations

---

User Story 8 - Monitor and Viewer Management (Priority: P2)

As a system administrator, I need to query and manage video output monitors so that I can understand system topology and configure video routing.

Why this priority: Enhances system visibility and configuration but video operations can work without detailed monitor management initially.

Independent Test: Can be fully tested by querying monitor lists, checking monitor status, and understanding which cameras are currently routed to which monitors.

Acceptance Scenarios:

1. Given 256 monitors configured in a GeViScope instance, When an administrator queries /api/v1/geviscope/main/monitors, Then they receive a list of all monitors with IDs, names, status, and current camera assignments
2. Given a monitor displaying video, When queried for current assignment, Then the API returns which camera is currently routed to that monitor
3. Given multiple GeViScope instances, When listing monitors, Then each instance's monitors are clearly identified by instance ID
4. Given GSCView viewers connected to monitors, When administrators query viewer status, Then they can see which viewers are active and what they're displaying

---

User Story 9 - 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 101038, 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 101038, When an investigator searches for recordings, Then they receive a list of available recording segments with playback 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 10 - 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 101038, 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 101038, 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 11 - Action Mapping and Automation (Priority: P3)

As a security administrator, I need to configure action mappings in GeViSoft so that specific events automatically trigger corresponding actions across the system.

Why this priority: Valuable for automation but requires basic event and action functionality to be working first.

Independent Test: Can be fully tested by creating an action mapping (e.g., motion detected → CrossSwitch), triggering the input action, and verifying the mapped actions execute.

Acceptance Scenarios:

1. Given an action mapping configured (InputContact closed → CrossSwitch cameras to monitors), When the input contact event occurs, Then the mapped CrossSwitch actions execute automatically
2. Given multiple output actions mapped to one input, When the input event triggers, Then all output actions execute in sequence
3. Given action mappings spanning GeViScope instances, When triggered, Then the API coordinates actions across instances correctly
4. Given an action mapping fails (e.g., target camera offline), When execution occurs, Then errors are logged and administrators are notified without blocking other actions

---

User Story 12 - GeViSoft Configuration Management (Priority: P1) ✅ IMPLEMENTED

As a system administrator, I need to manage GeViSoft configuration (G-Core servers, action mappings) via the API so that I can programmatically configure and maintain the surveillance system without manual GeViSet operations.

Why this priority: Configuration management is essential for automation, infrastructure-as-code, and maintaining consistent configurations across environments.

Independent Test: Can be fully tested by creating/reading/updating/deleting servers and action mappings, verifying changes persist in GeViSoft, and confirming no data loss occurs.

Acceptance Scenarios:

1. Given an authenticated administrator, When they create a new G-Core server via POST /api/v1/configuration/servers, Then the server is added to GeViSoft configuration with correct bool types and appears in GeViSet
2. Given existing servers in configuration, When an administrator queries /api/v1/configuration/servers, Then they receive a list of all servers with IDs, aliases, hosts, and connection settings
3. Given multiple action mappings to delete, When deletion occurs in reverse order (highest ID first), Then only intended mappings are deleted without cascade deletion
4. Given a server ID auto-increment requirement, When creating servers, Then the system automatically assigns the next available numeric ID based on existing servers

Implementation Status (2025-12-16):

• ✅ Server CRUD: CREATE, READ, DELETE working; UPDATE has known bug
• ✅ Action Mapping CRUD: CREATE, READ, UPDATE, DELETE all working
• ✅ Critical Fix: Cascade deletion bug fixed (delete in reverse order)
• ✅ Configuration tree navigation and parsing
• ✅ SetupClient integration for configuration download/upload
• ✅ Bool type handling for server fields (Enabled, DeactivateEcho, DeactivateLiveCheck)
• ⚠️ Known Issue: Server UpdateServer method requires bug fix for "Server ID is required" error

Documentation:

• SERVER_CRUD_IMPLEMENTATION.md
• CRITICAL_BUG_FIX_DELETE.md

---

User Story 13 - 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 for all instances, and verifying alerts when components fail.

Acceptance Scenarios:

1. Given the API is running, When an unauthenticated user requests /api/v1/health, Then they receive system status including API uptime, GeViSoft connectivity, all GeViScope instance statuses, and overall health score
2. Given one GeViScope instance fails, When health is checked, Then the health endpoint returns degraded status with specific instance error details while other instances show healthy
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, active streams per instance, and connection status for all instances

---

Edge Cases

• What happens when a GeViScope instance disconnects while operators are viewing cameras from that instance?
• How does CrossSwitch behave when routing a camera from one GeViScope instance to a monitor on a different instance (if supported)?
• What occurs when GeViSoft connection fails but GeViScope instances remain online?
• How does the API handle monitor IDs that overlap across different GeViScope instances?
• What happens when a GSCView viewer is configured to display a monitor that has no active camera route?
• How does the system respond when CrossSwitch commands execute successfully at the server but no viewer is displaying the monitor?
• What occurs when an alarm in GeViSoft references cameras or monitors from a GeViScope instance that is offline?
• How does the API handle time synchronization issues between GeViSoft, multiple GeViScope instances, and the API server?
• What happens when monitor enumeration returns different results than expected (e.g., 256 monitors vs 16 actual video outputs)?
• How does the system handle authentication when GeViSoft credentials differ from GeViScope credentials?

Requirements (mandatory)

Functional Requirements

Architecture & Multi-Instance:

• FR-001: System MUST support connecting to one GeViSoft instance (GeViServer) for management operations
• FR-002: System MUST support connecting to multiple GeViScope instances (GSCServer) with configurable instance IDs, hostnames, and credentials
• FR-003: System MUST provide instance discovery endpoint listing all configured GeViScope instances with connection status
• FR-004: System MUST support default instance configuration for convenience endpoints without instance ID
• FR-005: System MUST clearly identify which GeViScope instance each resource (camera, monitor, event) belongs to

Authentication & Authorization:

• FR-006: System MUST authenticate all API requests using JWT tokens with configurable expiration (default 1 hour for access, 7 days for refresh)
• FR-007: System MUST implement role-based access control with roles: viewer (read-only), operator (control), administrator (full configuration)
• FR-008: System MUST provide granular permissions allowing access restriction per camera, monitor, and GeViScope instance
• FR-009: System MUST audit log all authentication attempts and privileged operations

CrossSwitch & Monitor Management:

• FR-010: System MUST provide CrossSwitch endpoint to route cameras to monitors: POST /api/v1/crossswitch and instance-specific variant
• FR-011: System MUST track active CrossSwitch routes in database with camera ID, monitor ID, mode, timestamp, and user
• FR-012: System MUST provide endpoint to clear monitor assignments: DELETE /api/v1/crossswitch/{monitor_id}
• FR-013: System MUST provide routing status endpoint showing all active camera→monitor routes
• FR-014: System MUST use typed SDK actions (GeViAct_CrossSwitch) instead of string-based commands for reliable execution
• FR-015: System MUST enumerate and expose all video output monitors with IDs, names, status, and current assignments
• FR-016: System MUST support monitor grouping and bulk operations on monitor groups

Video Operations:

• FR-017: System MUST expose live video streams for all cameras with initialization time under 2 seconds
• FR-018: System MUST support PTZ control operations with command response time under 500ms
• FR-019: System MUST handle concurrent video stream requests from minimum 100 simultaneous users
• FR-020: System MUST gracefully handle camera offline scenarios with appropriate error codes

Event Management:

• FR-021: System MUST provide WebSocket endpoint for real-time event notifications with delivery latency under 100ms
• FR-022: System MUST support event subscriptions by type, camera, and GeViScope instance
• FR-023: System MUST handle events from multiple GeViScope instances with clear instance identification
• FR-024: System MUST support WebSocket connections from minimum 1000 concurrent clients

GeViSoft Integration:

• FR-025: System MUST provide alarm management endpoints for GeViSoft alarm configuration and triggering
• FR-026: System MUST support action mapping configuration and execution
• FR-027: System MUST coordinate cross-instance operations when alarms or actions span multiple GeViScope instances
• FR-028: System MUST provide endpoints for querying and managing GeViSoft system configuration

Configuration Management: ✅ IMPLEMENTED (2025-12-16)

• FR-039: System MUST provide CRUD operations for G-Core server management with proper bool type handling
• FR-040: System MUST provide CRUD operations for action mapping management
• FR-041: System MUST delete multiple action mappings in reverse order (highest ID first) to prevent cascade deletion
• FR-042: System MUST auto-increment server IDs based on highest existing numeric ID
• FR-043: System MUST persist configuration changes to GeViSoft and verify changes are visible in GeViSet
• FR-044: System MUST parse and navigate GeViSoft configuration tree structure (.set file format)
• FR-045: System MUST use SetupClient for reliable configuration download/upload operations

Recording & Analytics:

• FR-029: System MUST provide recording management including start/stop, queries, and capacity metrics
• FR-030: System MUST support video analytics configuration (VMD, OBTRACK, NPR, G-Tect) where hardware supports
• FR-031: System MUST provide query capabilities for recorded footage by channel, time range, and event association
• FR-032: System MUST export video segments in standard formats (MP4/AVI) with metadata

System Management:

• FR-033: System MUST provide health check endpoint returning status for GeViSoft, all GeViScope instances, database, and SDK bridges
• FR-034: System MUST implement retry logic for transient SDK communication failures (3 attempts with exponential backoff)
• FR-035: System MUST serve auto-generated OpenAPI/Swagger documentation at /docs
• FR-036: System MUST support API versioning in URL path (v1, v2) for backward compatibility
• FR-037: System MUST rate limit authentication attempts (max 5/minute per IP)
• FR-038: System MUST enforce TLS 1.2+ for all API communication in production

Key Entities

• GeViScope Instance: Configuration for a GSCServer connection with ID, hostname, credentials, status, camera count, monitor count
• Camera: Video input channel with ID, global ID, name, GeViScope instance, capabilities, status, stream URL
• Monitor (Video Output): Logical display channel with ID, name, GeViScope instance, status, current camera assignment
• CrossSwitch Route: Video routing record with camera ID, monitor ID, mode, GeViScope instance, created timestamp, created by user, active status
• User: Authentication entity with username, password hash, role, permissions, JWT tokens, audit trail
• Event: Surveillance occurrence with type, event ID, camera, GeViScope instance, timestamp, severity, data, foreign key
• Alarm (GeViSoft): System-wide alarm with ID, name, priority, monitor group, cameras, trigger actions, active status
• Action Mapping: Automation rule with input action, output actions, GeViScope instance scope
• Recording: Video footage segment with camera, GeViScope instance, start/end time, file size, trigger type
• Audit Log Entry: Security record with timestamp, user, action, target resource, GeViScope instance, outcome

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Developers can authenticate and make their first successful API call within 10 minutes
• SC-002: Operators can execute CrossSwitch to route cameras to monitors with routes visible in system within 1 second
• SC-003: Multi-instance operations work correctly with 3+ GeViScope instances configured
• SC-004: Security operators can view live video from any authorized camera with video appearing within 2 seconds
• SC-005: PTZ camera movements respond to commands within 500ms
• SC-006: Real-time event notifications delivered within 100ms across all GeViScope instances
• SC-007: System supports 100 concurrent video streams across all instances without degradation
• SC-008: System handles 1000+ concurrent WebSocket connections with 99.9% message delivery
• SC-009: CrossSwitch routes created via API are visible in GeViAPI Test Client and affect GSCView displays
• SC-010: API maintains 99.9% uptime with automatic failover if one GeViScope instance fails

Business Impact

• BI-001: Custom surveillance applications can be developed in under 1 week using the API
• BI-002: Support for multiple GeViScope instances enables scalable multi-site deployments
• BI-003: Unified API reduces integration complexity by 70% compared to separate GeViSoft/GeViScope integrations
• BI-004: CrossSwitch automation reduces operator workload for video routing by 80%

Dependencies (mandatory)

External Dependencies

• GeViScope SDK 7.9.975.68+: Core SDK for video operations
• GeViSoft SDK 6.0.1.5+: Management platform SDK
• Windows Server 2016+ or Windows 10/11: Required for both SDKs
• Active GeViSoft System: Configured with GeViScope instances
• Active GeViScope Instances: One or more GSCServer instances with cameras and monitors

Assumptions

• GeViSoft and GeViScope instances are installed, configured, and operational
• Network connectivity exists between API server and all GeViScope/GeViSoft instances
• Authentication credentials available for all instances
• Sufficient storage for ring buffer recording
• CrossSwitch commands execute at server level, viewer applications (GSCView) required for actual video display
• Monitor IDs may not be unique across instances (scoped by instance ID in API)

Out of Scope

• Direct camera hardware management (firmware, network config)
• GSCView configuration and deployment
• Custom video codec development
• Mobile native SDKs (REST API only)
• Video wall display management UI
• Bi-directional audio communication
• Custom analytics algorithm development

Constraints

Technical Constraints

• API must run on Windows platform due to SDK dependencies
• All video operations use GeViScope's channel-based architecture
• Event notifications limited to SDK-supported events
• Recording capabilities bounded by ring buffer architecture
• CrossSwitch routes video at server level, does NOT control physical displays (requires viewers)
• Monitor enumeration may return more monitors than physically exist (SDK implementation detail)

Performance Constraints

• Maximum concurrent streams limited by GeViScope SDK licenses and hardware
• WebSocket connection limits determined by OS socket limits
• Multi-instance operations may have higher latency than single-instance
• CrossSwitch execution time depends on SDK response (typically <100ms)

Security Constraints

• All API communication must use TLS 1.2+ in production
• JWT tokens must have configurable expiration
• Audit logging must be tamper-evident
• Credentials for GeViSoft and GeViScope instances must be stored securely

Risk Analysis

High Impact Risks

1. Multi-Instance Complexity: Managing connections to multiple GeViScope instances increases failure modes

   • Mitigation: Circuit breaker per instance, independent health monitoring, graceful degradation

2. CrossSwitch Verification: Confirming routes are active requires viewer applications

   • Mitigation: Document viewer requirements, provide route tracking in database, API-level route verification

3. GeViSoft/GeViScope Coordination: Cross-system operations may have complex failure scenarios

   • Mitigation: Transaction-like patterns, compensating actions, clear error reporting

Medium Impact Risks

4. Instance Configuration Management: Adding/removing instances requires careful config management

   • Mitigation: Configuration validation, instance health checks, hot-reload support

5. SDK Version Compatibility: Different GeViScope instances may run different SDK versions

   • Mitigation: Version detection, compatibility matrix, graceful feature detection

6. Monitor ID Confusion: Monitor IDs overlap across instances

   • Mitigation: Always scope monitors by instance ID in API, clear documentation

Notes

This updated specification reflects the unified architecture supporting both GeViSoft management and multiple GeViScope instances. The API serves as a central control plane for the entire Geutebruck surveillance ecosystem.

Key Architectural Decisions:

• Single API with two layers: GeViSoft (management) and GeViScope (operations)
• Instance-based routing for GeViScope operations
• CrossSwitch implemented with typed SDK actions for reliability
• Monitor management reflects SDK's video output concept (logical channels, not physical displays)
• Database tracks routes and provides audit trail

Priority Sequencing:

• P1 (Stories 1-6): MVP with auth, multi-instance, CrossSwitch, live video, PTZ, events
• P2 (Stories 7-10): GeViSoft integration, monitor management, recording, analytics
• P3 (Stories 11-12): Automation, advanced monitoring