geutebruck-api/specs/001-surveillance-api/tasks-revised-mvp.md

Tasks: Geutebruck Cross-Switching API (Revised MVP)

Scope: Cross-switching REST API with authentication, focusing on GeViSet-compatible configuration MVP Goal: Control GSCView viewers via cross-switching, no UI needed Future Expansion: GeViSet configuration management, action mapping, CSV import/export

---

MVP User Stories

US1: Authentication & Connection

Connect to GeViServer, authenticate users, maintain sessions

US2: Camera Discovery

List all video inputs (cameras) with metadata

US3: Monitor Discovery

List all video outputs (GSCView viewers/monitors) with status

US4: Cross-Switching Operations

Route cameras to viewers, clear viewers, query routing state

---

Revised Data Model (Simplified)

User:
  - id, username, password_hash, role (viewer/operator/admin)

Camera:
  - id (channel), name, description, has_ptz, has_video_sensor, status

Monitor:
  - id (output channel), name, is_active, current_camera_id

CrossSwitchRoute:
  - id, camera_id, monitor_id, switched_at, switched_by_user_id

AuditLog:
  - id, user_id, action, target, timestamp, details

---

Phase 1: Foundation (Setup & Core Infrastructure)

Purpose: Project structure, dependencies, SDK bridge foundation

• T001 Create project structure (src/api, src/sdk-bridge, tests, docs, scripts)
• T002 Create .gitignore for Python and C#
• T003 Create requirements.txt with FastAPI, SQLAlchemy, Redis, grpcio, PyJWT, pytest
• T004 Create SDK Bridge .csproj with .NET 8.0, Grpc.AspNetCore, GeViScope SDK reference
• T005 Create .env.example with config variables (DB, Redis, JWT secret, GeViServer host/credentials)
• T006 Create alembic.ini for database migrations
• T007 [P] Create pyproject.toml with ruff, black, mypy configuration
• T008 [P] Create scripts/setup_dev_environment.ps1 (install dependencies, setup DB, start services)
• T009 [P] Create scripts/start_services.ps1 (start Redis, SDK Bridge, FastAPI)
• T010 [P] Create docs/architecture.md documenting system design

Checkpoint: Project structure complete, dependencies defined

---

Phase 2: SDK Bridge Foundation (C# gRPC Service)

Purpose: Wrap GeViScope SDK with gRPC for Python consumption

gRPC Protocol Definitions

• T011 Define common.proto (Status, Error, Timestamp, Empty messages)
• T012 Define camera.proto (ListCamerasRequest/Response, CameraInfo with channel, name, has_ptz)
• T013 Define monitor.proto (ListMonitorsRequest/Response, MonitorInfo with channel, name, current_camera)
• T014 Define crossswitch.proto (CrossSwitchRequest, ClearMonitorRequest, GetRoutingStateRequest/Response)

SDK Wrapper Implementation

• T015 Create GeViDatabaseWrapper.cs (Create, RegisterCallback, Connect, Disconnect, error handling)
• T016 Implement connection lifecycle with retry logic (3 attempts, exponential backoff)
• T017 Create StateQueryHandler.cs for GetFirst/GetNext enumeration pattern
• T018 Implement EnumerateCameras() using CSQGetFirstVideoInput / CSQGetNextVideoInput
• T019 Implement EnumerateMonitors() using CSQGetFirstVideoOutput / CSQGetNextVideoOutput
• T020 Create ErrorTranslator.cs to map Windows error codes to gRPC status codes
• T021 Create ActionDispatcher.cs for sending SDK actions (CrossSwitch, ClearVideoOutput)

gRPC Service Implementation

• T022 Create CameraService.cs implementing camera.proto with ListCameras RPC
• T023 Create MonitorService.cs implementing monitor.proto with ListMonitors RPC
• T024 Create CrossSwitchService.cs with ExecuteCrossSwitch, ClearMonitor, GetRoutingState RPCs
• T025 Create Program.cs gRPC server with Serilog logging, service registration
• T026 Add configuration loading from appsettings.json (GeViServer host, port, credentials)

Checkpoint: SDK Bridge can connect to GeViServer, enumerate resources, execute cross-switch

---

Phase 3: Python API Foundation

Purpose: FastAPI application structure, configuration, database setup

Core Setup

• T027 Create main.py with FastAPI app, CORS middleware, exception handlers
• T028 Create config.py loading settings from environment (Pydantic BaseSettings)
• T029 Setup PostgreSQL connection with SQLAlchemy async engine in models/init.py
• T030 Create initial Alembic migration for users and audit_logs tables
• T031 Setup Redis client with connection pooling in clients/redis_client.py
• T032 Create gRPC SDK Bridge client in clients/sdk_bridge_client.py with connection pooling
• T033 [P] Create JWT utilities in utils/jwt_utils.py (encode, decode, verify)
• T034 [P] Create error translation utilities in utils/error_translation.py (gRPC → HTTP status)
• T035 Implement global error handler middleware in middleware/error_handler.py

Database Models

• T036 [P] Create User model in models/user.py (id, username, password_hash, role, created_at)
• T037 [P] Create AuditLog model in models/audit_log.py (id, user_id, action, target, timestamp)
• T038 Run alembic upgrade head to create tables

Checkpoint: Python API can start, connect to DB/Redis, communicate with SDK Bridge via gRPC

---

Phase 4: Authentication (User Story 1)

Purpose: JWT-based authentication with role-based access control

Tests (TDD - Write FIRST, Ensure FAIL)

• T039 [P] Write contract test for POST /api/v1/auth/login in tests/api/contract/test_auth.py (should FAIL)
• T040 [P] Write contract test for POST /api/v1/auth/logout in tests/api/contract/test_auth.py (should FAIL)
• T041 [P] Write unit test for AuthService in tests/api/unit/test_auth_service.py (should FAIL)

Implementation

• T042 [P] Create auth schemas in schemas/auth.py (LoginRequest, TokenResponse, UserInfo)
• T043 Implement AuthService in services/auth_service.py (login, logout, validate_token, hash_password)
• T044 Implement JWT token generation (access: 1hr, refresh: 7 days) with Redis session storage
• T045 Implement authentication middleware in middleware/auth_middleware.py (verify JWT, extract user)
• T046 Implement role checking decorator in utils/permissions.py (@require_role("operator"))
• T047 Create auth router in routers/auth.py with POST /auth/login, POST /auth/logout
• T048 Add audit logging for authentication attempts (success and failures)

Verify: Run tests T039-T041 - should now PASS

Checkpoint: Can login with credentials, receive JWT token, use token for authenticated requests

---

Phase 5: Camera Discovery (User Story 2)

Purpose: List all cameras (video inputs) from GeViServer

Tests (TDD - Write FIRST, Ensure FAIL)

• T049 [P] Write contract test for GET /api/v1/cameras in tests/api/contract/test_cameras.py (should FAIL)
• T050 [P] Write unit test for CameraService in tests/api/unit/test_camera_service.py (should FAIL)

Implementation

• T051 [P] Create camera schemas in schemas/camera.py (CameraInfo, CameraList)
• T052 Implement CameraService in services/camera_service.py (list_cameras via gRPC to SDK Bridge)
• T053 Create cameras router in routers/cameras.py with GET /cameras
• T054 Add permission check: authenticated users only
• T055 Add caching in Redis (cache camera list for 60 seconds to reduce SDK Bridge load)

Verify: Run tests T049-T050 - should now PASS

Checkpoint: GET /api/v1/cameras returns list of all cameras from GeViServer

---

Phase 6: Monitor Discovery (User Story 3)

Purpose: List all monitors/viewers (video outputs) from GeViServer

Tests (TDD - Write FIRST, Ensure FAIL)

• T056 [P] Write contract test for GET /api/v1/monitors in tests/api/contract/test_monitors.py (should FAIL)
• T057 [P] Write unit test for MonitorService in tests/api/unit/test_monitor_service.py (should FAIL)

Implementation

• T058 [P] Create monitor schemas in schemas/monitor.py (MonitorInfo, MonitorList)
• T059 Implement MonitorService in services/monitor_service.py (list_monitors via gRPC to SDK Bridge)
• T060 Create monitors router in routers/monitors.py with GET /monitors
• T061 Add permission check: authenticated users only
• T062 Add caching in Redis (cache monitor list for 60 seconds)

Verify: Run tests T056-T057 - should now PASS

Checkpoint: GET /api/v1/monitors returns list of all monitors/viewers from GeViServer

---

Phase 7: Cross-Switching Operations (User Story 4)

Purpose: Execute cross-switch, clear monitors, query routing state

Tests (TDD - Write FIRST, Ensure FAIL)

• T063 [P] Write contract test for POST /api/v1/crossswitch in tests/api/contract/test_crossswitch.py (should FAIL)
• T064 [P] Write contract test for DELETE /api/v1/monitors/{id} in tests/api/contract/test_crossswitch.py (should FAIL)
• T065 [P] Write contract test for GET /api/v1/routing/state in tests/api/contract/test_crossswitch.py (should FAIL)
• T066 [P] Write integration test for cross-switch workflow in tests/api/integration/test_crossswitch.py (should FAIL)

Implementation

• T067 [P] Create crossswitch schemas in schemas/crossswitch.py (CrossSwitchRequest, RoutingState, ClearMonitorRequest)
• T068 Create CrossSwitchRoute model in models/crossswitch_route.py (id, camera_id, monitor_id, switched_at, user_id)
• T069 Create Alembic migration for crossswitch_routes table
• T070 Implement CrossSwitchService in services/crossswitch_service.py:
  • execute_crossswitch(camera_id, monitor_id, mode=0) → gRPC to SDK Bridge
  • clear_monitor(monitor_id) → gRPC ClearVideoOutput
  • get_routing_state() → query current routes
• T071 Create crossswitch router in routers/crossswitch.py:
  • POST /crossswitch (requires operator or admin role)
  • DELETE /monitors/{id} (requires operator or admin role)
  • GET /routing/state (all authenticated users)
• T072 Add audit logging for all cross-switch operations
• T073 Add validation: camera_id and monitor_id must exist
• T074 Store routing state in database for history/tracking

Verify: Run tests T063-T066 - should now PASS

Checkpoint: Can execute cross-switch via API, clear monitors, query current routing

---

Phase 8: MVP Polish & Documentation

Purpose: Complete MVP with documentation and deployment readiness

• T075 [P] Create API documentation in docs/api-usage.md with curl examples
• T076 [P] Create deployment guide in docs/deployment.md (Windows Server setup, service installation)
• T077 [P] Add Prometheus metrics endpoint at /metrics (request count, latency, active connections)
• T078 [P] Create health check endpoint GET /health (SDK Bridge connectivity, DB, Redis status)
• T079 [P] Add request logging with correlation IDs
• T080 Create README.md with project overview, quick start, architecture diagram
• T081 Update OpenAPI specification to include only MVP endpoints
• T082 Create Postman collection for API testing
• T083 Run full integration tests with actual GeViServer connection
• T084 Security audit: Remove stack traces in production, sanitize logs

Checkpoint: MVP complete - REST API for cross-switching with authentication

---

Phase 9: Future - GeViSet Configuration Management (Phase 2)

Purpose: GeViSet-like functionality via API (action mapping configuration)

Note: These tasks will be detailed after MVP is complete and working

High-Level Tasks:

• T085 Research GeViSet configuration file format and action mapping structure
• T086 Implement GET /api/v1/config/actions to retrieve action mappings from GeViServer
• T087 Implement PUT /api/v1/config/actions to push action mappings to GeViServer
• T088 Implement POST /api/v1/config/actions/export to export configuration to CSV
• T089 Implement POST /api/v1/config/actions/import to import configuration from CSV
• T090 Add validation for action mapping syntax and constraints
• T091 Add versioning for configuration changes (track who changed what, when)
• T092 Add backup/restore functionality for configurations

Checkpoint: GeViSet configuration management available via API

---

Dependencies & Execution Order

Phase Dependencies

Phase 1 (Setup)
  ↓
Phase 2 (SDK Bridge Foundation) ← BLOCKS all Python API work
  ↓
Phase 3 (Python API Foundation) ← BLOCKS all feature work
  ↓
Phase 4 (Authentication) ← BLOCKS all protected endpoints
  ↓
Phases 5, 6, 7 can proceed in parallel (after Phase 4)
  ↓
Phase 8 (Polish & Documentation)
  ↓
Phase 9 (Future - GeViSet config) ← After MVP validated

Critical Path (Sequential)

1. Setup → SDK Bridge → Python API → Authentication
2. Then parallel: Camera Discovery + Monitor Discovery + Cross-Switching
3. Then: Polish & Documentation
4. Finally: GeViSet configuration (Phase 2)

Parallel Opportunities

• Phase 2: T020 (ErrorTranslator) parallel with T017-T019 (StateQuery implementation)
• Phase 3: T033-T034, T036-T037 can run in parallel
• Phase 4: T039-T041 tests can run in parallel
• Phase 5-7: These entire phases can run in parallel after Phase 4 completes
• Phase 8: T075-T082 can run in parallel

---

Implementation Strategy

Week 1: Foundation

• Days 1-2: Phase 1 (Setup)
• Days 3-5: Phase 2 (SDK Bridge)

Week 2: API Core

• Days 1-3: Phase 3 (Python API Foundation)
• Days 4-5: Phase 4 (Authentication)

Week 3: Cross-Switching

• Days 1-2: Phase 5 (Camera Discovery)
• Days 2-3: Phase 6 (Monitor Discovery)
• Days 4-5: Phase 7 (Cross-Switching Operations)

Week 4: Polish & Validation

• Days 1-3: Phase 8 (Polish, Documentation)
• Days 4-5: Integration testing with real GeViServer, bug fixes

MVP Delivery: End of Week 4

Week 5+: Phase 2 Features

• GeViSet configuration management
• Action mapping CRUD
• CSV import/export

---

Task Summary

MVP Total: 84 tasks

By Phase:

• Phase 1 (Setup): 10 tasks
• Phase 2 (SDK Bridge): 16 tasks
• Phase 3 (API Foundation): 12 tasks
• Phase 4 (Authentication): 10 tasks
• Phase 5 (Camera Discovery): 7 tasks
• Phase 6 (Monitor Discovery): 7 tasks
• Phase 7 (Cross-Switching): 12 tasks
• Phase 8 (Polish): 10 tasks

Phase 2 (Future): 8+ tasks (detailed after MVP)

Tests: 12 test tasks (TDD approach) Parallel Tasks: 20+ tasks marked [P]

Estimated Timeline:

• MVP: 3-4 weeks (1 developer, focused work)
• Phase 2 (GeViSet config): +1-2 weeks

---

MVP Endpoints Summary

# Authentication
POST   /api/v1/auth/login              # Get JWT token
POST   /api/v1/auth/logout             # Invalidate token

# Cameras
GET    /api/v1/cameras                 # List all cameras

# Monitors
GET    /api/v1/monitors                # List all monitors/viewers

# Cross-Switching
POST   /api/v1/crossswitch             # Execute cross-switch
  Body: { camera_id: 7, monitor_id: 3, mode: 0 }

DELETE /api/v1/monitors/{id}           # Clear monitor (stop video)

GET    /api/v1/routing/state           # Get current routing state

# System
GET    /api/v1/health                  # Health check (SDK Bridge, DB, Redis)
GET    /metrics                        # Prometheus metrics

---

Testing Strategy

TDD Approach

1. Write contract test (should FAIL)
2. Write unit tests (should FAIL)
3. Implement feature
4. Run tests (should PASS)
5. Refactor if needed
6. Commit

Test Coverage Goal

• Minimum 70% coverage for MVP
• 100% coverage for authentication and cross-switching logic

Manual Testing

• Test with Postman collection
• Test with curl commands
• Integration test with actual GeViServer

---

Generated: 2025-12-08 Scope: Cross-switching MVP with authentication, expandable to GeViSet configuration Architecture: Python FastAPI + C# gRPC Bridge + GeViScope SDK