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