geutebruck-api/docs/architecture.md

Geutebruck Cross-Switching API - Architecture

Version: 1.0.0 (MVP) Last Updated: 2025-12-08 Status: In Development

---

Overview

The Geutebruck Cross-Switching API provides a modern REST API for controlling video routing between cameras (video inputs) and monitors/viewers (video outputs) in Geutebruck surveillance systems. The system acts as a bridge between the native GeViScope/GeViSoft SDK and modern web/mobile applications.

Core Functionality:

• 🔐 User authentication with JWT tokens
• 📹 Camera discovery and management
• 🖥️ Monitor/viewer discovery and status
• 🔀 Cross-switching operations (route camera to monitor)
• 📊 Routing state tracking and audit logging

---

System Architecture

High-Level Architecture

┌─────────────────┐
│   Client Apps   │  (Postman, curl, custom apps)
└────────┬────────┘
         │ HTTP/REST
         ▼
┌─────────────────┐
│  FastAPI Server │  (Python 3.11)
│  Port: 8000     │
└────────┬────────┘
         │
    ┌────┴────┬───────────┬──────────┐
    │         │           │          │
    ▼         ▼           ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌─────────┐
│ PostgreSQL│ │ Redis  │ │SDK Bridge│ │Auth/JWT │
│ Port:5432│ │Port:6379│ │Port:50051│ │ Service │
└─────────┘ └────────┘ └────┬───┘ └─────────┘
                             │ gRPC
                             ▼
                      ┌──────────────┐
                      │  GeViScope   │
                      │  SDK (.NET)  │
                      └──────┬───────┘
                             │ TCP/IP
                             ▼
                      ┌──────────────┐
                      │  GeViServer  │
                      │  Port: 7700+ │
                      └──────┬───────┘
                             │
                    ┌────────┴────────┐
                    ▼                 ▼
              ┌──────────┐      ┌──────────┐
              │ Cameras  │      │ GSCView  │
              │ (Inputs) │      │ Viewers  │
              └──────────┘      └──────────┘

---

Component Details

1. FastAPI Server (Python)

Purpose: REST API layer handling HTTP requests, authentication, and business logic

Technology Stack:

• Python 3.11+
• FastAPI (web framework)
• SQLAlchemy (ORM)
• Pydantic (validation)
• PyJWT (authentication)

Key Responsibilities:

• Accept HTTP REST requests from clients
• Authenticate users and generate JWT tokens
• Validate request data
• Communicate with SDK Bridge via gRPC
• Store routing state in PostgreSQL
• Cache camera/monitor lists in Redis
• Audit log all operations
• Return HTTP responses to clients

Port: 8000

---

2. SDK Bridge (C# .NET 8.0)

Purpose: gRPC service that wraps the GeViScope SDK, translating between modern gRPC and legacy SDK

Technology Stack:

• C# .NET 8.0
• Grpc.AspNetCore
• GeViScope SDK (.NET Framework 4.8 DLL)
• Serilog (logging)

Key Responsibilities:

• Connect to GeViServer using GeViScope SDK
• Enumerate cameras (GetFirstVideoInput / GetNextVideoInput)
• Enumerate monitors (GetFirstVideoOutput / GetNextVideoOutput)
• Execute cross-switching (CrossSwitch action)
• Clear monitors (ClearVideoOutput action)
• Translate SDK errors to gRPC status codes
• Maintain connection health with retry logic

Why Separate Service?:

• ✅ Isolates SDK crashes from Python API
• ✅ Enables independent scaling
• ✅ Clear separation of concerns (SDK complexity vs API logic)
• ✅ Type-safe gRPC communication
• ✅ Can run on different machines if needed

Port: 50051 (gRPC)

---

3. PostgreSQL Database

Purpose: Persistent storage for users, routing state, and audit logs

Schema:

users:
  - id (UUID, primary key)
  - username (unique)
  - password_hash (bcrypt)
  - role (viewer, operator, administrator)
  - created_at, updated_at

crossswitch_routes:
  - id (UUID, primary key)
  - camera_id (int)
  - monitor_id (int)
  - switched_at (timestamp)
  - switched_by_user_id (UUID, FK to users)

audit_logs:
  - id (UUID, primary key)
  - user_id (UUID, FK to users)
  - action (string)
  - target (string)
  - timestamp (timestamp)
  - details (JSON)

Port: 5432

---

4. Redis

Purpose: Session storage, caching, and future pub/sub for events

Usage:

• Session Storage: JWT tokens and user sessions
• Caching: Camera list (60s TTL), monitor list (60s TTL)
• Future: Pub/sub for real-time routing updates

Port: 6379

---

5. GeViScope SDK & GeViServer

GeViServer:

• Backend service managing surveillance system
• Handles actual video routing
• Controls GSCView viewers
• Manages camera inputs and outputs

GeViScope SDK:

• .NET Framework 4.8 DLL (GeViProcAPINET_4_0.dll)
• Provides C# wrapper for GeViServer communication
• Uses action-based message passing
• State query pattern for enumeration

Ports: 7700, 7701, 7703

---

Data Flow

1. Authentication Flow

Client → POST /api/v1/auth/login
         { username: "admin", password: "secret" }
           ↓
         FastAPI validates credentials
           ↓
         Hash password with bcrypt
           ↓
         Query PostgreSQL for user
           ↓
         Generate JWT token (1hr expiry)
           ↓
         Store session in Redis
           ↓
Client ← { access_token: "eyJ...", token_type: "bearer" }

2. Camera Discovery Flow

Client → GET /api/v1/cameras
         Header: Authorization: Bearer eyJ...
           ↓
         FastAPI validates JWT
           ↓
         Check Redis cache for camera list
           ↓ (cache miss)
         gRPC call to SDK Bridge: ListCameras()
           ↓
         SDK Bridge → GeViScope SDK
                    → CSQGetFirstVideoInput()
                    → CSQGetNextVideoInput() (loop)
           ↓
         SDK Bridge ← Camera list
           ↓
         FastAPI ← gRPC response
           ↓
         Store in Redis (60s TTL)
           ↓
Client ← { cameras: [
           { id: 1, name: "Camera 1", has_ptz: false },
           { id: 2, name: "Front Gate", has_ptz: true }
         ]}

3. Cross-Switching Flow

Client → POST /api/v1/crossswitch
         { camera_id: 7, monitor_id: 3, mode: 0 }
           ↓
         FastAPI validates JWT (requires operator role)
           ↓
         Validate camera_id and monitor_id exist
           ↓
         gRPC call to SDK Bridge: ExecuteCrossSwitch(7, 3, 0)
           ↓
         SDK Bridge → GeViScope SDK
                    → SendMessage("CrossSwitch(7, 3, 0)")
           ↓
         GeViServer executes cross-switch
           ↓
         SDK Bridge ← Success confirmation
           ↓
         FastAPI stores route in PostgreSQL
           ↓
         FastAPI logs to audit_logs table
           ↓
Client ← { success: true, message: "Camera 7 routed to monitor 3" }

---

Security Architecture

Authentication & Authorization

Authentication: JWT (JSON Web Tokens)

• Access tokens: 1 hour lifetime
• Refresh tokens: 7 days lifetime (future)
• Tokens stored in Redis for quick invalidation
• Bcrypt password hashing (cost factor: 12)

Authorization: Role-Based Access Control (RBAC)

Role	Permissions
Viewer	Read cameras, Read monitors, Read routing state
Operator	Viewer + Execute cross-switch, Clear monitors
Administrator	Operator + User management, Configuration

API Security

• ✅ HTTPS enforced in production (TLS 1.2+)
• ✅ CORS configured for allowed origins
• ✅ Rate limiting (60 requests/minute per IP)
• ✅ JWT secret key from environment (not hardcoded)
• ✅ Database credentials in environment variables
• ✅ No stack traces exposed to clients
• ✅ Audit logging for all operations

---

Scalability Considerations

Current Architecture (MVP)

• Single FastAPI instance
• Single SDK Bridge instance
• Single GeViServer connection

Future Horizontal Scaling

FastAPI Layer:

• ✅ Stateless design enables multiple instances
• ✅ Load balancer in front (nginx/HAProxy)
• ✅ Shared PostgreSQL and Redis

SDK Bridge Layer:

• ⚠️ Limited by GeViServer connection capacity
• Consider: Connection pooling pattern
• Consider: Multiple SDK Bridge instances if needed

Database Layer:

• PostgreSQL read replicas for camera/monitor queries
• Redis Cluster for high availability

---

Error Handling

SDK Bridge Error Translation

SDK Error	gRPC Status	HTTP Status
Connection Failed	UNAVAILABLE	503 Service Unavailable
Invalid Channel	INVALID_ARGUMENT	400 Bad Request
Permission Denied	PERMISSION_DENIED	403 Forbidden
Timeout	DEADLINE_EXCEEDED	504 Gateway Timeout
Unknown	INTERNAL	500 Internal Server Error

Retry Logic

• SDK Bridge connection: 3 attempts with exponential backoff
• gRPC calls from FastAPI: 2 attempts with 1s delay
• Transient errors logged but not exposed to client

---

Monitoring & Observability

Logging

FastAPI:

• Structured JSON logs (Structlog)
• Log levels: DEBUG, INFO, WARNING, ERROR
• Correlation IDs for request tracing

SDK Bridge:

• Serilog with file and console sinks
• Separate logs for SDK communication

Metrics (Future)

Prometheus Endpoint: /metrics

• Request count by endpoint
• Request latency (p50, p95, p99)
• Active cross-switch operations
• gRPC call success/failure rates
• Cache hit/miss rates

Health Checks

Endpoint: GET /api/v1/health

Returns:

{
  "status": "healthy",
  "components": {
    "database": "up",
    "redis": "up",
    "sdk_bridge": "up"
  },
  "timestamp": "2025-12-08T15:30:00Z"
}

---

Deployment Architecture

Development Environment

Localhost:
  - PostgreSQL (Docker or native)
  - Redis (Docker or native)
  - SDK Bridge (.NET)
  - FastAPI (uvicorn --reload)
  - GeViServer (C:\GEVISOFT\GeViServer.exe)

Production Environment (Windows Server)

Windows Server 2016+:
  - GeViServer (native Windows service)
  - SDK Bridge (Windows service via NSSM)
  - PostgreSQL (Docker or native)
  - Redis (Docker or native)
  - FastAPI (Docker or uvicorn behind nginx)
  - Nginx (reverse proxy with SSL termination)

Network Requirements

• Port 8000: FastAPI (HTTPS in production)
• Port 50051: SDK Bridge gRPC (internal only)
• Port 5432: PostgreSQL (internal only)
• Port 6379: Redis (internal only)
• Port 7700-7703: GeViServer (internal only)

---

Technology Choices Rationale

Why Python FastAPI?

• ✅ Modern async Python framework
• ✅ Automatic OpenAPI documentation
• ✅ Fast development cycle
• ✅ Rich ecosystem (SQLAlchemy, Pydantic)
• ✅ Easy to expand with new features

Why C# SDK Bridge?

• ✅ GeViScope SDK is .NET Framework 4.8
• ✅ gRPC provides type-safe communication
• ✅ Isolates SDK complexity
• ✅ Can run on separate machine if needed

Why PostgreSQL?

• ✅ Mature, reliable, ACID compliant
• ✅ JSON support for flexible audit logs
• ✅ Good performance for relational data

Why Redis?

• ✅ Fast in-memory caching
• ✅ Session storage
• ✅ Future: pub/sub for events

Why gRPC (not REST for SDK Bridge)?

• ✅ Type-safe protocol buffers
• ✅ Efficient binary protocol
• ✅ Streaming support (future)
• ✅ Language-agnostic

---

Future Enhancements (Phase 2)

1. GeViSet Configuration Management

   • Retrieve action mappings from GeViServer
   • Modify configurations via API
   • Export/import to CSV
   • Push configurations back to server

2. Real-Time Event Stream

   • WebSocket endpoint for routing changes
   • Redis pub/sub for event distribution
   • Monitor status change notifications

3. PTZ Camera Control

   • Pan/tilt/zoom commands
   • Preset positions
   • Tour sequences

4. Multi-Tenancy

   • Organization/tenant isolation
   • Per-tenant GeViServer connections

5. Advanced Analytics

   • Routing history reports
   • Usage patterns
   • Performance metrics

---

Development Workflow

1. Setup: .\scripts\setup_dev_environment.ps1
2. Start Services: .\scripts\start_services.ps1
3. Database Migrations: alembic upgrade head
4. Run Tests: pytest tests/ -v
5. Code Quality: ruff check src/api + black src/api
6. API Docs: http://localhost:8000/docs

---

References

• FastAPI Documentation: https://fastapi.tiangolo.com
• gRPC .NET: https://grpc.io/docs/languages/csharp/
• GeViScope SDK: See docs/SDK_INTEGRATION_LESSONS.md
• SQLAlchemy: https://docs.sqlalchemy.org
• Pydantic: https://docs.pydantic.dev

---

Document Version: 1.0 Architecture Status: ✅ Defined, 🔄 In Development Last Review: 2025-12-08