How jubjones/spoton_backend works
Project Type and Purpose
• This is a backend-only analytics service (FastAPI) for retrospective multi-camera person tracking.
• It exposes REST endpoints to control tasks and WebSocket endpoints to stream real-time metadata.
• It orchestrates AI pipelines (detection, tracking, re-ID, homography), uses background tasks, stores results in a time-series database, and interacts with S3-compatible object storage.
Main Components
a. Clients
– REST clients (e.g., curl, Postman)
– WebSocket clients (e.g., frontend, scripts/websocket_client_test.py)
b. API Layer (app/api)
– REST routers:
• /api/v1/processing-tasks
• /api/v1/analytics_data
– WebSocket router: /ws/tracking/{task_id}
c. Core & Configuration (app/core)
– Load config (S3, DB, Redis)
– Startup/shutdown events
d. Services Layer (app/services)
– PipelineOrchestrator (entry to processing pipeline)
– MultiCameraFrameProcessor & FrameProcessor tasks
– CameraTrackerFactory, Detector, Tracker, ReID components
– HomographyService (map-projection)
– StorageService (S3 interactions)
– VideoDataManagerService (fetch sub-videos, frames)
– NotificationService (push status & tracking updates)
e. Models & Utilities
– AI model wrappers (app/models)
– Utility modules for downloading assets, video processing, homography utils
f. Background Tasks (app/tasks/frame_processor.py)
g. External Systems
– S3-compatible Object Storage (video inputs)
– Redis (broker for background jobs / pub-sub)
– TimescaleDB/Postgres (metadata/time-series storage)
h. Deployment / Infrastructure
– Dockerfile (build container with weights, homography_data)
– docker-compose.yml (services: backend, redis, timescaledb)
Relationships & Data Flow
1. Client → HTTP POST /api/v1/processing-tasks/start → FastAPI Router
2. Router → PipelineOrchestrator: reads VIDEO_SETS config → VideoDataManagerService retrieves sub-video list from S3
3. Orchestrator → dispatches FrameProcessor tasks (via Redis broker or async queue)
4. FrameProcessor → for each frame batch:
• uses Detector (Faster R-CNN)
• uses Tracker (BotSort + CLIP Re-ID)
• uses HomographyService to project to map coords
• writes metadata to TimescaleDB via StorageService
• calls NotificationService to emit WebSocket messages
5. NotificationService → pushes status_update & tracking_update messages over WebSocket to clients
6. Clients render overlays on video or store data for analysis.
Architectural Patterns & Principles
• Layered Architecture: HTTP layer → business logic (services) → data-access layers (models, storage).
• Event-driven pipeline: orchestrator dispatches tasks, tasks emit events (status/tracking).
• Asynchronous processing: HTTP triggers background work, clients consume via WebSockets.
• Separation of concerns:
– app/api only handles I/O
– app/services contains business logic
– app/models wraps AI libraries
– app/utils for shared helpers
• Containerized deployment (Docker Compose).
Detailed Element Checklist
– Labels: component names exactly as in the code (e.g., PipelineOrchestrator).
– Boundaries: highlight the Docker container boundary around all internal components.
– External services: place Redis, TimescaleDB, S3 outside the container.
– Include config loader (app/core/config.py) feeding S3/DB connection parameters.