# niconielsen32/vision-system architecture

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

- Interactive diagram: https://gitdiagram.com/niconielsen32/vision-system
- Repository: https://github.com/niconielsen32/vision-system

## Overview

##### Project type and purpose
- This is a full-stack real-time AI vision processing system.
- Frontend: React + Vite SPA for camera management, live/recorded video analysis, dashboards, and settings.
- Backend: FastAPI server providing REST and WebSocket (real-time) endpoints, orchestrating AI model inference, and persisting data to PostgreSQL.
- Monitoring: Prometheus scrapes metrics exposed by the backend.
- Deployment: Docker-Compose orchestrates PostgreSQL, FastAPI, Prometheus, and the frontend.

##### File structure
- Top-level:
- docker-compose.yml + Dockerfile + .env.example – container definitions and env templates.
- prometheus/ – Prometheus server config, alert/rules, and console templates.
- backend/ – FastAPI application:
– main.py – application entrypoint (Uvicorn server, routes).
– db_settings.py – DB connection setup (PostgreSQL).
– models.py / schemas.py – ORM & Pydantic models.
– monitoring/metrics.py – Prometheus client exporter.
- frontend/ – React application scaffolded by Vite:
– src/pages, src/components – UI modules for Home, Dashboard, LiveAnalysis, Settings, etc.
– src/services/api.js – HTTP client to backend endpoints.
– vite.config.js, package.json – build config.
- requirements.txt – Python dependencies.
- package.json – Root-level (if any tooling at root).
- Notice stray src/App.jsx at root – likely can be ignored or consolidated under frontend.

##### Key architectural patterns & technologies
- Client-Server (SPA + REST/WebSocket).
- MVC-style separation: Pydantic schemas (input/output), SQLAlchemy/ORM models, and API routers.
- Real-time data flow: WebSocket or Server-Sent Events for live video.
- Observer/Exporter for metrics (Prometheus).
- Containerized micro-services via Docker Compose.

##### Main components & their relationships
a. Frontend (browser SPA)
– Hosts UI, consumes REST APIs for configuration, metadata, dashboards.
– Opens WebSocket or SSE connection to backend for live video analysis frames.
b. Backend (FastAPI)
– REST endpoints: camera CRUD, model selection, analytics data.
– Real-time stream endpoints: receives video frames (or URLs) from client or reads camera streams, forwards to AI inference module.
– Data Layer: communicates with PostgreSQL for persisting camera configs, historical analytics.
– Monitoring Exporter: collects internal metrics and exposes HTTP /metrics for Prometheus.
c. Database (PostgreSQL)
– Stores user/camera metadata, analytics results, and model configuration.
d. Monitoring (Prometheus + Console)
– Scrapes backend /metrics.
– Rules generate alerts; consoles present custom HTML dashboards.
e. External Camera Streams
– IP or USB cameras feeding RTSP/HLS streams that backend ingests.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Docker Compose"
        subgraph "Frontend"
            SPA["SPA (React + Vite)"]:::frontend
            Pages["UI Pages"]:::frontend
            ComponentsNode["Components"]:::frontend
            APIService["API Service Module"]:::frontend
            Entry["Entrypoint (main.jsx)"]:::frontend
        end
        subgraph "Backend"
            BackApp["FastAPI Application"]:::backend
            DBSettings["DB Connection Settings"]:::backend
            ORM["ORM Models"]:::backend
            Schemas["Pydantic Schemas"]:::backend
            Inference["AI Inference Service"]:::backend
            MetricsNode["Metrics Exporter"]:::backend
        end
        DB["PostgreSQL Database"]:::database
        subgraph "Monitoring"
            PromServer["Prometheus Server"]:::monitoring
            Rules["Alerting/Recording Rules"]:::monitoring
            Consoles["Console Templates"]:::monitoring
        end
    end
    Cameras["External Camera Streams"]:::external

    Cameras -->|RTSP/HLS| BackApp
    SPA -->|HTTP/JSON| BackApp
    SPA -->|WebSocket/SSE| BackApp
    BackApp -->|SQL| DB
    MetricsNode -->|"/metrics"| PromServer
    PromServer -->|evaluates| Rules
    PromServer -->|serves| Consoles

    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef database fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef monitoring fill:#e2d6f9,stroke:#333,stroke-width:1px;
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px;
    classDef docker fill:#ffffff,stroke:#666,stroke-width:2px,stroke-dasharray: 5 5;

    click SPA "https://github.com/niconielsen32/vision-system/tree/main/frontend/src"
    click Pages "https://github.com/niconielsen32/vision-system/tree/main/frontend/src/pages"
    click ComponentsNode "https://github.com/niconielsen32/vision-system/tree/main/frontend/src/components"
    click APIService "https://github.com/niconielsen32/vision-system/blob/main/frontend/src/services/api.js"
    click Entry "https://github.com/niconielsen32/vision-system/blob/main/frontend/src/main.jsx"
    click BackApp "https://github.com/niconielsen32/vision-system/blob/main/backend/main.py"
    click DBSettings "https://github.com/niconielsen32/vision-system/blob/main/backend/db_settings.py"
    click ORM "https://github.com/niconielsen32/vision-system/blob/main/backend/models.py"
    click Schemas "https://github.com/niconielsen32/vision-system/blob/main/backend/schemas.py"
    click MetricsNode "https://github.com/niconielsen32/vision-system/blob/main/backend/monitoring/metrics.py"
    click DockerCompose "https://github.com/niconielsen32/vision-system/blob/main/docker-compose.yml"
    click DockerfileNode "https://github.com/niconielsen32/vision-system/tree/main/Dockerfile"
    click Env "https://github.com/niconielsen32/vision-system/blob/main/.env.example"
    click PromServer "https://github.com/niconielsen32/vision-system/blob/main/prometheus/prometheus.yml"
    click Rules "https://github.com/niconielsen32/vision-system/blob/main/prometheus/rules.yml"
    click Consoles "https://github.com/niconielsen32/vision-system/tree/main/prometheus/consoles"
    click Requirements "https://github.com/niconielsen32/vision-system/blob/main/requirements.txt"
    click ViteConfig "https://github.com/niconielsen32/vision-system/blob/main/frontend/vite.config.js"
    click FEpackage "https://github.com/niconielsen32/vision-system/blob/main/frontend/package.json"
    click RootPackage "https://github.com/niconielsen32/vision-system/blob/main/package.json"
```
