# Implementation Plan: Geutebruck Video Surveillance API

**Branch**: `001-surveillance-api` | **Date**: 2025-11-13 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-surveillance-api/spec.md`

## Summary

Build a complete RESTful API for Geutebruck GeViScope/GeViSoft video surveillance system control, enabling developers to create custom surveillance applications without direct SDK integration. The API will provide authentication, live video streaming, PTZ camera control, real-time event notifications, recording management, and video analytics configuration through a secure, well-documented REST/WebSocket interface.

**Technical Approach**: Python FastAPI service running on Windows, translating REST/WebSocket requests to GeViScope SDK actions through an abstraction layer, with JWT authentication, Redis caching, and auto-generated OpenAPI documentation.

## Technical Context

**Language/Version**: Python 3.11+
**Primary Dependencies**:
- FastAPI 0.104+ (async web framework with auto OpenAPI docs)
- Pydantic 2.5+ (data validation and settings management)
- python-jose 3.3+ (JWT token generation and validation)
- passlib 1.7+ (password hashing with bcrypt)
- Redis-py 5.0+ (session storage and caching)
- python-multipart (file upload support for video exports)
- uvicorn 0.24+ (ASGI server)
- websockets 12.0+ (WebSocket support built into FastAPI)
- pywin32 or comtypes (GeViScope SDK COM interface)

**Storage**:
- Redis 7.2+ for session management, API key caching, rate limiting counters
- Optional: SQLite for development / PostgreSQL for production audit logs
- GeViScope SDK manages video storage (ring buffer architecture)

**Testing**:
- pytest 7.4+ (test framework)
- pytest-asyncio (async test support)
- httpx (async HTTP client for API testing)
- pytest-cov (coverage reporting, target 80%+)
- pytest-mock (mocking for SDK bridge testing)

**Target Platform**: Windows Server 2016+ or Windows 10/11 (required for GeViScope SDK)

**Project Type**: Single project (API-only service, clients consume REST/WebSocket)

**Performance Goals**:
- 500 requests/second throughput under normal load
- < 200ms response time for metadata queries (p95)
- < 500ms for PTZ commands
- < 100ms event notification delivery
- Support 100+ concurrent video streams
- Support 1000+ concurrent WebSocket connections

**Constraints**:
- Must run on Windows (GeViScope SDK requirement)
- Must interface with GeViScope SDK COM/DLL objects
- Channel-based operations (Channel ID parameter required)
- Video streaming limited by GeViScope SDK license and hardware
- Ring buffer architecture bounds recording capabilities
- TLS 1.2+ required in production

**Scale/Scope**:
- 10-100 concurrent operators
- 50-500 cameras per deployment
- 30 API endpoints across 6 resource types
- 10 WebSocket event types
- 8 video analytics types (VMD, NPR, OBTRACK, etc.)

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

### ✅ Principle I: Security-First (NON-NEGOTIABLE)
- [x] JWT authentication implemented for all protected endpoints
- [x] TLS 1.2+ enforced (configured in deployment, not code)
- [x] RBAC with 3 roles (viewer, operator, administrator)
- [x] Granular per-camera permissions
- [x] Audit logging for privileged operations
- [x] Rate limiting on authentication endpoints
- [x] No credentials in source code (environment variables)

**Status**: ✅ **PASS** - Security requirements addressed in architecture

### ✅ Principle II: RESTful API Design
- [x] Resources represent surveillance entities (cameras, events, recordings)
- [x] Standard HTTP methods (GET, POST, PUT, DELETE)
- [x] URL structure `/api/v1/{resource}/{id}/{action}`
- [x] JSON data exchange
- [x] Proper HTTP status codes
- [x] Stateless JWT authentication
- [x] API versioning in URL path

**Status**: ✅ **PASS** - REST principles followed

### ✅ Principle III: Test-Driven Development (NON-NEGOTIABLE)
- [x] Tests written before implementation (TDD enforced)
- [x] 80% coverage target for SDK bridge layer
- [x] Unit, integration, and E2E tests planned
- [x] pytest framework selected
- [x] CI/CD blocks on test failures

**Status**: ✅ **PASS** - TDD workflow defined

### ✅ Principle IV: SDK Abstraction Layer
- [x] SDK Bridge isolates GeViScope SDK from API layer
- [x] Translates REST → SDK Actions, SDK Events → WebSocket
- [x] Error code translation (Windows → HTTP)
- [x] Mockable for testing without hardware
- [x] No direct SDK calls from route handlers

**Status**: ✅ **PASS** - Abstraction layer designed

### ✅ Principle V: Performance & Reliability
- [x] Performance targets defined and measurable
- [x] Retry logic with exponential backoff (3 attempts)
- [x] Circuit breaker pattern for SDK communication
- [x] Graceful degradation under load (503 vs crash)
- [x] Health check endpoint planned

**Status**: ✅ **PASS** - Performance and reliability addressed

### ✅ Technical Constraints Satisfied
- [x] Windows platform acknowledged
- [x] Python 3.11+ selected
- [x] FastAPI framework chosen
- [x] Redis for caching
- [x] Pytest for testing
- [x] SDK integration strategy defined

**Status**: ✅ **PASS** - All technical constraints satisfied

### ✅ Quality Standards Met
- [x] 80% test coverage enforced
- [x] Code review via PR required
- [x] Black formatter + ruff linter
- [x] Type hints mandatory (mypy)
- [x] OpenAPI auto-generated

**Status**: ✅ **PASS** - Quality standards defined

**Overall Gate Status**: ✅ **PASS** - Proceed to Phase 0 Research

## Project Structure

### Documentation (this feature)

```
specs/001-surveillance-api/
├── spec.md              # Feature specification (complete)
├── plan.md              # This file (in progress)
├── research.md          # Phase 0 output (pending)
├── data-model.md        # Phase 1 output (pending)
├── quickstart.md        # Phase 1 output (pending)
├── contracts/           # Phase 1 output (pending)
│   └── openapi.yaml     # OpenAPI 3.0 specification
└── tasks.md             # Phase 2 output (via /speckit.tasks)
```

### Source Code (repository root)

```
geutebruck-api/
├── src/
│   ├── api/
│   │   ├── v1/
│   │   │   ├── routes/
│   │   │   │   ├── auth.py          # Authentication endpoints
│   │   │   │   ├── cameras.py       # Camera management & streaming
│   │   │   │   ├── events.py        # Event subscriptions
│   │   │   │   ├── recordings.py    # Recording management
│   │   │   │   ├── analytics.py     # Video analytics config
│   │   │   │   └── system.py        # Health, status endpoints
│   │   │   ├── dependencies.py      # Route dependencies (auth, etc.)
│   │   │   ├── schemas.py           # Pydantic request/response models
│   │   │   └── __init__.py
│   │   ├── middleware/
│   │   │   ├── auth.py              # JWT validation middleware
│   │   │   ├── error_handler.py     # Global exception handling
│   │   │   ├── rate_limit.py        # Rate limiting middleware
│   │   │   └── logging.py           # Request/response logging
│   │   ├── websocket.py             # WebSocket connection manager
│   │   └── main.py                  # FastAPI app initialization
│   ├── sdk/
│   │   ├── bridge.py                # Main SDK abstraction interface
│   │   ├── actions/
│   │   │   ├── system.py            # SystemActions wrapper
│   │   │   ├── video.py             # VideoActions wrapper
│   │   │   ├── camera.py            # CameraControlActions wrapper
│   │   │   ├── events.py            # Event management wrapper
│   │   │   └── analytics.py         # Analytics actions wrapper
│   │   ├── events/
│   │   │   ├── dispatcher.py        # Event listener and dispatcher
│   │   │   └── translator.py        # SDK Event → JSON translator
│   │   ├── errors.py                # SDK exception types
│   │   └── connection.py            # SDK connection management
│   ├── services/
│   │   ├── auth.py                  # Authentication service (JWT, passwords)
│   │   ├── permissions.py           # RBAC and authorization logic
│   │   ├── camera.py                # Camera business logic
│   │   ├── recording.py             # Recording management logic
│   │   ├── analytics.py             # Analytics configuration logic
│   │   └── notifications.py         # Event notification service
│   ├── models/
│   │   ├── user.py                  # User entity
│   │   ├── camera.py                # Camera entity
│   │   ├── event.py                 # Event entity
│   │   ├── recording.py             # Recording entity
│   │   └── session.py               # Session entity
│   ├── database/
│   │   ├── redis.py                 # Redis connection and helpers
│   │   └── audit.py                 # Audit log persistence (optional DB)
│   ├── core/
│   │   ├── config.py                # Settings management (Pydantic Settings)
│   │   ├── security.py              # Password hashing, JWT utilities
│   │   └── logging.py               # Logging configuration
│   └── utils/
│       ├── errors.py                # Custom exception classes
│       └── validators.py            # Custom validation functions
├── tests/
│   ├── unit/
│   │   ├── test_auth_service.py
│   │   ├── test_sdk_bridge.py
│   │   ├── test_camera_service.py
│   │   └── test_permissions.py
│   ├── integration/
│   │   ├── test_auth_endpoints.py
│   │   ├── test_camera_endpoints.py
│   │   ├── test_event_endpoints.py
│   │   ├── test_recording_endpoints.py
│   │   └── test_websocket.py
│   ├── e2e/
│   │   └── test_user_workflows.py   # End-to-end scenarios
│   ├── conftest.py                  # Pytest fixtures
│   └── mocks/
│       └── sdk_mock.py              # Mock SDK for testing
├── docs/
│   ├── api/                         # API documentation
│   ├── deployment/                  # Deployment guides
│   └── sdk-mapping.md               # GeViScope action → endpoint mapping
├── docker/
│   ├── Dockerfile                   # Windows container
│   └── docker-compose.yml           # Development environment
├── .env.example                     # Environment variable template
├── requirements.txt                 # Python dependencies
├── pyproject.toml                   # Project metadata, tool config
├── README.md                        # Project overview
└── .gitignore
```

**Structure Decision**: Single project structure selected because this is an API-only service. Frontend/mobile clients will be separate projects that consume this API. The structure separates concerns into:
- `api/` - FastAPI routes, middleware, WebSocket
- `sdk/` - GeViScope SDK abstraction and translation
- `services/` - Business logic layer
- `models/` - Domain entities
- `database/` - Data access layer
- `core/` - Cross-cutting concerns (config, security, logging)
- `utils/` - Shared utilities

## Complexity Tracking

**No constitution violations requiring justification.**

All technical choices align with constitution principles. The selected technology stack (Python + FastAPI + Redis) directly implements the decisions made in the constitution.

## Phase 0: Research & Technical Decisions

**Status**: Pending - To be completed in research.md

### Research Topics

1. **GeViScope SDK Integration**
   - Research COM/DLL interface patterns for Python (pywin32 vs comtypes)
   - Document GeViScope SDK action categories and parameters
   - Identify SDK event notification mechanisms
   - Determine video stream URL/protocol format

2. **Video Streaming Strategy**
   - Research options: Direct URLs vs API proxy vs WebRTC signaling
   - Evaluate bandwidth implications for 100+ concurrent streams
   - Determine authentication method for video streams
   - Document GeViScope streaming protocols

3. **WebSocket Event Architecture**
   - Research FastAPI WebSocket best practices for 1000+ connections
   - Design event subscription patterns (by type, by channel, by user)
   - Determine connection lifecycle management (heartbeat, reconnection)
   - Plan message batching strategy for high-frequency events

4. **Authentication & Session Management**
   - Finalize JWT token structure and claims
   - Design refresh token rotation strategy
   - Plan API key generation and storage (for service accounts)
   - Determine Redis session schema and TTL values

5. **Performance Optimization**
   - Research async patterns for SDK I/O operations
   - Plan connection pooling strategy for SDK
   - Design caching strategy for camera metadata
   - Evaluate load balancing options (horizontal scaling)

6. **Error Handling & Monitoring**
   - Map Windows error codes to HTTP status codes
   - Design structured logging format
   - Plan health check implementation (SDK connectivity, Redis, resource usage)
   - Identify metrics to expose (Prometheus format)

7. **Testing Strategy**
   - Design SDK mock implementation for tests without hardware
   - Plan test data generation (sample cameras, events, recordings)
   - Determine integration test approach (test SDK instance vs mocks)
   - Document E2E test scenarios

**Output Location**: `specs/001-surveillance-api/research.md`

## Phase 1: Design & Contracts

**Status**: Pending - To be completed after Phase 0 research

### Deliverables

1. **Data Model** (`data-model.md`)
   - Entity schemas (User, Camera, Event, Recording, Stream, etc.)
   - Validation rules
   - State transitions (e.g., Recording states: idle → recording → stopped)
   - Relationships and foreign keys

2. **API Contracts** (`contracts/openapi.yaml`)
   - Complete OpenAPI 3.0 specification
   - All endpoints with request/response schemas
   - Authentication scheme definitions
   - WebSocket protocol documentation
   - Error response formats

3. **Quick Start Guide** (`quickstart.md`)
   - Installation instructions
   - Configuration guide (environment variables)
   - First API call example (authentication)
   - Common use cases with curl/Python examples

4. **Agent Context Update**
   - Run `.specify/scripts/powershell/update-agent-context.ps1 -AgentType claude`
   - Add project-specific context to Claude agent file

### API Endpoint Overview (Design Phase)

**Authentication** (`/api/v1/auth/`):
- `POST /login` - Obtain JWT token
- `POST /refresh` - Refresh access token
- `POST /logout` - Invalidate session

**Cameras** (`/api/v1/cameras/`):
- `GET /` - List all cameras (filtered by permissions)
- `GET /{id}` - Get camera details
- `GET /{id}/stream` - Get live video stream URL/connection
- `POST /{id}/ptz` - Send PTZ command
- `GET /{id}/presets` - Get PTZ presets
- `POST /{id}/presets` - Save PTZ preset

**Events** (`/api/v1/events/`):
- `WS /stream` - WebSocket endpoint for event subscriptions
- `GET /` - Query event history (paginated)
- `GET /{id}` - Get event details

**Recordings** (`/api/v1/recordings/`):
- `GET /` - Query recordings by channel/time range
- `POST /{channel}/start` - Start recording
- `POST /{channel}/stop` - Stop recording
- `GET /{id}` - Get recording details
- `POST /{id}/export` - Request video export
- `GET /capacity` - Get recording capacity metrics

**Analytics** (`/api/v1/analytics/`):
- `GET /{channel}/config` - Get analytics configuration
- `PUT /{channel}/config` - Update analytics configuration
- `POST /{channel}/vmd` - Configure motion detection
- `POST /{channel}/npr` - Configure license plate recognition
- `POST /{channel}/obtrack` - Configure object tracking

**System** (`/api/v1/system/`):
- `GET /health` - Health check (no auth required)
- `GET /status` - Detailed system status
- `GET /metrics` - Prometheus metrics

**Output Locations**:
- `specs/001-surveillance-api/data-model.md`
- `specs/001-surveillance-api/contracts/openapi.yaml`
- `specs/001-surveillance-api/quickstart.md`

## Phase 2: Task Breakdown

**Not created by `/speckit.plan`** - This phase is handled by `/speckit.tasks` command

The tasks phase will break down the implementation into concrete work items organized by:
- Setup phase (project scaffolding, dependencies)
- Foundational phase (SDK bridge, authentication, database)
- User story phases (P1, P2, P3 stories as separate task groups)
- Polish phase (documentation, optimization, security hardening)

## Deployment Considerations

### Development Environment
- Python 3.11+ installed
- GeViScope SDK installed and configured
- Redis running locally or via Docker (Windows containers)
- Environment variables configured (.env file)

### Production Environment
- Windows Server 2016+ or Windows 10/11
- GeViScope SDK with active license
- Redis cluster or managed instance
- TLS certificates configured
- Reverse proxy (nginx/IIS) for HTTPS termination
- Environment variables via system config or key vault

### Configuration Management
All configuration via environment variables:
- `SDK_CONNECTION_STRING` - GeViScope SDK connection details
- `JWT_SECRET_KEY` - JWT signing key
- `JWT_ALGORITHM` - Default: HS256
- `JWT_EXPIRATION_MINUTES` - Default: 60
- `REDIS_URL` - Redis connection URL
- `LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR)
- `CORS_ORIGINS` - Allowed CORS origins for web clients
- `MAX_CONCURRENT_STREAMS` - Concurrent stream limit
- `RATE_LIMIT_AUTH` - Auth endpoint rate limit

### Docker Deployment
```dockerfile
# Windows Server Core base image
FROM mcr.microsoft.com/windows/servercore:ltsc2022

# Install Python 3.11
# Install GeViScope SDK
# Copy application code
# Install Python dependencies
# Expose ports 8000 (HTTP), 8001 (WebSocket)
# Run uvicorn server
```

## Next Steps

1. ✅ Constitution defined and validated
2. ✅ Specification created with user stories and requirements
3. ✅ Implementation plan created (this document)
4. ⏭️ **Execute `/speckit.plan` Phase 0**: Generate research.md
5. ⏭️ **Execute `/speckit.plan` Phase 1**: Generate data-model.md, contracts/, quickstart.md
6. ⏭️ **Execute `/speckit.tasks`**: Break down into actionable task list
7. ⏭️ **Execute `/speckit.implement`**: Begin TDD implementation

---

**Plan Status**: ✅ Technical plan complete, ready for Phase 0 research
**Constitution Compliance**: ✅ All gates passed
**Next Command**: Continue with research phase to resolve implementation details