# jubjones/spoton_backend architecture

> Architecture diagram of the GitHub repository jubjones/spoton_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jubjones/spoton_backend
- Repository: https://github.com/jubjones/spoton_backend

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container"
        %% Client Lane
        ClientRest["REST Client"]:::client
        ClientWS["WebSocket Client"]:::client

        %% API Layer
        subgraph "API Layer"
            ProcessingTasks["processing_tasks.py"]:::api
            AnalyticsData["analytics_data.py"]:::api
            WebsocketRouter["websockets.py"]:::api
        end

        %% Core & Config
        subgraph "Core & Config"
            Config["config.py"]:::core
            Events["event_handlers.py"]:::core
        end

        %% Services Lane
        subgraph "Services"
            Orchestrator["pipeline_orchestrator.py"]:::service
            MultiFrame["multi_camera_frame_processor.py"]:::service
            FrameTask["frame_processor.py"]:::service
            TrackerFactory["camera_tracker_factory.py"]:::service
            Detector["detectors.py"]:::service
            TrackerReID["reid_components.py"]:::service
            TrackerModel["trackers.py"]:::service
            FeatureExt["feature_extractors.py"]:::service
            Homography["homography_service.py"]:::service
            StorageS["storage_service.py"]:::service
            VideoDM["video_data_manager_service.py"]:::service
            Notification["notification_service.py"]:::service
        end

        %% Utilities Lane
        subgraph "Utilities"
            AssetDL["asset_downloader.py"]:::util
            VideoUtils["video_processing.py"]:::util
            HomoUtils["homography_utils.py"]:::util
            DeviceUtils["device_utils.py"]:::util
        end

        %% Container Definition
        subgraph "Container Definition"
            DockerfileF["Dockerfile"]:::infra
            Compose["docker-compose.yml"]:::infra
            HomData["homography_data/"]:::infra
        end
    end

    %% External Systems
    S3["S3 Storage"]:::s3
    Redis["Redis"]:::redis
    Timescale["TimescaleDB"]:::db

    %% Flows
    ClientRest -->|"HTTP POST /api/v1/processing-tasks/start"| ProcessingTasks
    ProcessingTasks -->|"calls PipelineOrchestrator"| Orchestrator
    Config -->|provide params| ProcessingTasks
    Events -->|startup/shutdown| ProcessingTasks
    Orchestrator -->|"Read VIDEO_SETS"| VideoDM
    VideoDM -->|"S3 GetObject"| S3
    Orchestrator -->|"dispatch tasks\nRedis queue"| Redis
    Redis -->|"pop task"| FrameTask
    FrameTask -->|"batch frames"| MultiFrame
    MultiFrame -->|"detect"| Detector
    MultiFrame -->|"track"| TrackerFactory
    TrackerFactory -->|"init"| TrackerReID
    TrackerFactory -->|"load model"| TrackerModel
    Detector -->|"feature ext"| FeatureExt
    MultiFrame -->|"project coords"| Homography
    MultiFrame -->|"write metadata"| StorageS
    StorageS -->|"INSERT"| Timescale
    MultiFrame -->|"notify"| Notification
    Notification -->|"PUBLISH WS"| WebsocketRouter
    WebsocketRouter -->|"WS JSON"| ClientWS

    %% Click Events
    click ProcessingTasks "https://github.com/jubjones/spoton_backend/blob/main/app/api/v1/endpoints/processing_tasks.py"
    click AnalyticsData "https://github.com/jubjones/spoton_backend/blob/main/app/api/v1/endpoints/analytics_data.py"
    click WebsocketRouter "https://github.com/jubjones/spoton_backend/blob/main/app/api/websockets.py"
    click Config "https://github.com/jubjones/spoton_backend/blob/main/app/core/config.py"
    click Events "https://github.com/jubjones/spoton_backend/blob/main/app/core/event_handlers.py"
    click Orchestrator "https://github.com/jubjones/spoton_backend/blob/main/app/services/pipeline_orchestrator.py"
    click MultiFrame "https://github.com/jubjones/spoton_backend/blob/main/app/services/multi_camera_frame_processor.py"
    click FrameTask "https://github.com/jubjones/spoton_backend/blob/main/app/tasks/frame_processor.py"
    click TrackerFactory "https://github.com/jubjones/spoton_backend/blob/main/app/services/camera_tracker_factory.py"
    click Detector "https://github.com/jubjones/spoton_backend/blob/main/app/models/detectors.py"
    click TrackerReID "https://github.com/jubjones/spoton_backend/blob/main/app/services/reid_components.py"
    click TrackerModel "https://github.com/jubjones/spoton_backend/blob/main/app/models/trackers.py"
    click FeatureExt "https://github.com/jubjones/spoton_backend/blob/main/app/models/feature_extractors.py"
    click Homography "https://github.com/jubjones/spoton_backend/blob/main/app/services/homography_service.py"
    click StorageS "https://github.com/jubjones/spoton_backend/blob/main/app/services/storage_service.py"
    click VideoDM "https://github.com/jubjones/spoton_backend/blob/main/app/services/video_data_manager_service.py"
    click Notification "https://github.com/jubjones/spoton_backend/blob/main/app/services/notification_service.py"
    click AssetDL "https://github.com/jubjones/spoton_backend/blob/main/app/utils/asset_downloader.py"
    click VideoUtils "https://github.com/jubjones/spoton_backend/blob/main/app/utils/video_processing.py"
    click HomoUtils "https://github.com/jubjones/spoton_backend/blob/main/app/utils/homography_utlis.py"
    click DeviceUtils "https://github.com/jubjones/spoton_backend/blob/main/app/utils/device_utils.py"
    click ClientWS "https://github.com/jubjones/spoton_backend/blob/main/scripts/websocket_client_test.py"
    click DockerfileF "https://github.com/jubjones/spoton_backend/tree/main/Dockerfile"
    click Compose "https://github.com/jubjones/spoton_backend/blob/main/docker-compose.yml"
    click HomData "https://github.com/jubjones/spoton_backend/tree/main/homography_data/"

    %% Styles
    classDef client fill:#f9f,stroke:#333,shape:parallelogram
    classDef api fill:#ccf,stroke:#333
    classDef core fill:#cfc,stroke:#333
    classDef service fill:#acf,stroke:#333
    classDef util fill:#eee,stroke:#333
    classDef infra fill:#ddd,stroke:#333
    classDef db fill:#afa,stroke:#333,shape:cylinder
    classDef s3 fill:#afa,stroke:#333,shape:cylinder
    classDef redis fill:#fec,stroke:#333,shape:cylinderLightning
```
