# vikasgupta37/project-swarma architecture

> Architecture diagram of the GitHub repository vikasgupta37/project-swarma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikasgupta37/project-swarma
- Repository: https://github.com/vikasgupta37/project-swarma

## Overview

SWARMA is a real-time crowd-operations platform: video and footfall signals become zone metrics, forecasts and risk assessments that support incidents, alerts and diversion plans for venue operators. The FastAPI backend exposes these capabilities to a React dashboard, which also receives live events. Major documented branches include video/CV, zone mapping, prediction, risk, routing, incident and alert workflows, audit, and grounded AI assistance. The graph emphasizes relationships shown in excerpts, the source index, or README; unsampled subsystem internals and some integrations are represented only where documented.

Main entry points: [`backend/app/services/metrics_service.py`](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/metrics_service.py) (Zone metrics), [`backend/app/services/assistant_service.py`](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/assistant_service.py) (Grounded assistant), [`backend/app/api/routes/routing.py`](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/api/routes/routing.py) (Route planning endpoint), [`frontend/src/App.tsx`](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/App.tsx) (Dashboard application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Operator dashboard"]
  node_webapp["Dashboard application<br/>[App.tsx]"]
  node_livehook["Live state hook<br/>[useLiveState.ts]"]
  node_frontendapi["API client<br/>[api.ts]"]
  node_livews["Live events client<br/>[websocket.ts]"]
  node_livestore["Live state store<br/>[liveStateStore.ts]"]
  node_adminui["Venue administration<br/>[AdminPage.tsx]"]
  node_incidentui["Incident views<br/>[IncidentList.tsx]"]
end

subgraph group_api["API and operations"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_router["API router<br/>[router.py]"]
  node_routingapi["Route planning endpoint<br/>[routing.py]"]
  node_incidentflow["Incident lifecycle"]
  node_events["Live event service"]
  node_assistant["Grounded assistant"]
end

subgraph group_intelligence["Crowd intelligence"]
  node_metrics["Zone metrics<br/>[metrics_service.py]"]
  node_prediction["Occupancy forecasts"]
  node_risk["Risk assessment<br/>[risk_service.py]"]
  node_riskengine["Risk engine<br/>[engine.py]"]
  node_routing["Diversion planning<br/>[routing_service.py]"]
end

subgraph group_media["Video and mapping"]
  node_cv["Video analysis pipeline<br/>[pipeline.py]"]
  node_zonecalc["Zone occupancy mapping<br/>[occupancy.py]"]
end

subgraph group_state["State and integrations"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_openai["OpenAI services"]
end

node_operator(("Venue operator"))

node_operator -->|"uses"| node_webapp
node_webapp -->|"loads live state"| node_livehook
node_webapp -->|"renders"| node_adminui
node_webapp -->|"renders"| node_incidentui
node_livehook -->|"fetches data"| node_frontendapi
node_livehook -->|"connects events"| node_livews
node_livehook -->|"updates state"| node_livestore
node_frontendapi -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_router
node_router -->|"registers"| node_routingapi
node_routingapi -->|"loads metrics"| node_metrics
node_routingapi -->|"forecasts zones"| node_prediction
node_routingapi -->|"assesses zones"| node_risk
node_routingapi -->|"plans route"| node_routing
node_risk -->|"assesses risk"| node_riskengine
node_metrics -->|"analyzes video"| node_cv
node_metrics -->|"calculates occupancy"| node_zonecalc
node_cv -->|"maps detections"| node_zonecalc
node_incidentflow -->|"broadcasts updates"| node_events
node_assistant -->|"requests completions"| node_openai
node_assistant -->|"loads context"| node_metrics
node_assistant -->|"loads context"| node_prediction
node_assistant -->|"loads context"| node_risk
node_metrics -->|"caches live metrics"| node_redis
node_metrics -.->|"persists metrics"| node_postgres
node_prediction -.->|"persists forecasts"| node_postgres
node_incidentflow -.->|"stores incidents"| node_postgres
node_assistant -.->|"stores query logs"| node_postgres

click node_webapp "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/App.tsx"
click node_livehook "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/hooks/useLiveState.ts"
click node_frontendapi "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/services/api.ts"
click node_livews "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/services/websocket.ts"
click node_livestore "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/store/liveStateStore.ts"
click node_adminui "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/pages/AdminPage.tsx"
click node_incidentui "https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/components/dashboard/IncidentList.tsx"
click node_backend "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/main.py"
click node_router "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/api/router.py"
click node_routingapi "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/api/routes/routing.py"
click node_incidentflow "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/incident_service.py"
click node_events "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/live_event_service.py"
click node_assistant "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/assistant_service.py"
click node_metrics "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/metrics_service.py"
click node_prediction "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/prediction_service.py"
click node_risk "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/risk_service.py"
click node_riskengine "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/risk/engine.py"
click node_routing "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/routing_service.py"
click node_cv "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/cv/pipeline.py"
click node_zonecalc "https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/zone/occupancy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_livehook,node_frontendapi,node_livews,node_livestore,node_adminui,node_incidentui toneBlue
class node_backend,node_router,node_routingapi,node_incidentflow,node_events,node_assistant toneAmber
class node_metrics,node_prediction,node_risk,node_riskengine,node_routing toneMint
class node_cv,node_zonecalc toneRose
class node_postgres,node_redis,node_openai,node_operator toneIndigo
```

## Components

### Operator dashboard

- [Dashboard application](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Live state hook](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/hooks/useLiveState.ts): `frontend/src/hooks/useLiveState.ts`
- [API client](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Live events client](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/services/websocket.ts): `frontend/src/services/websocket.ts`
- [Live state store](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/store/liveStateStore.ts): `frontend/src/store/liveStateStore.ts`
- [Venue administration](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/pages/AdminPage.tsx): `frontend/src/pages/AdminPage.tsx`
- [Incident views](https://github.com/vikasgupta37/project-swarma/blob/main/frontend/src/components/dashboard/IncidentList.tsx): `frontend/src/components/dashboard/IncidentList.tsx`

### API and operations

- [FastAPI application](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Route planning endpoint](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/api/routes/routing.py): `backend/app/api/routes/routing.py`
- [Incident lifecycle](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/incident_service.py): `backend/app/services/incident_service.py`
- [Live event service](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/live_event_service.py): `backend/app/services/live_event_service.py`
- [Grounded assistant](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/assistant_service.py): `backend/app/services/assistant_service.py`

### Crowd intelligence

- [Zone metrics](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/metrics_service.py): `backend/app/services/metrics_service.py`
- [Occupancy forecasts](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`
- [Risk assessment](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/risk_service.py): `backend/app/services/risk_service.py`
- [Risk engine](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/risk/engine.py): `backend/app/risk/engine.py`
- [Diversion planning](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/services/routing_service.py): `backend/app/services/routing_service.py`

### Video and mapping

- [Video analysis pipeline](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/cv/pipeline.py): `backend/app/cv/pipeline.py`
- [Zone occupancy mapping](https://github.com/vikasgupta37/project-swarma/blob/main/backend/app/zone/occupancy.py): `backend/app/zone/occupancy.py`

### State and integrations

- **PostgreSQL**
- **Redis**
- **OpenAI services**

### Other components

- **Venue operator**

## Connections

- Venue operator → Dashboard application: uses (evidence: `README.md`)
- Dashboard application → Live state hook: loads live state (evidence: `frontend/src/App.tsx`)
- Dashboard application → Venue administration: renders (evidence: `frontend/src/App.tsx`)
- Dashboard application → Incident views: renders (evidence: `frontend/src/App.tsx`)
- Live state hook → API client: fetches data (evidence: `frontend/src/hooks/useLiveState.ts`)
- Live state hook → Live events client: connects events (evidence: `frontend/src/hooks/useLiveState.ts`)
- Live state hook → Live state store: updates state (evidence: `frontend/src/hooks/useLiveState.ts`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → API router: mounts routes (evidence: `backend/app/main.py`)
- API router → Route planning endpoint: registers (evidence: `backend/app/api/router.py`)
- Route planning endpoint → Zone metrics: loads metrics (evidence: `backend/app/api/routes/routing.py`)
- Route planning endpoint → Occupancy forecasts: forecasts zones (evidence: `backend/app/api/routes/routing.py`)
- Route planning endpoint → Risk assessment: assesses zones (evidence: `backend/app/api/routes/routing.py`)
- Route planning endpoint → Diversion planning: plans route (evidence: `backend/app/api/routes/routing.py`)
- Risk assessment → Risk engine: assesses risk (evidence: `backend/app/services/risk_service.py`)
- Zone metrics → Video analysis pipeline: analyzes video (evidence: `backend/app/services/metrics_service.py`)
- Zone metrics → Zone occupancy mapping: calculates occupancy (evidence: `backend/app/services/metrics_service.py`)
- Video analysis pipeline → Zone occupancy mapping: maps detections (evidence: `README.md`)
- Incident lifecycle → Live event service: broadcasts updates (evidence: `backend/app/services/incident_service.py`)
- Grounded assistant → OpenAI services: requests completions (evidence: `backend/app/services/assistant_service.py`)
- Grounded assistant → Zone metrics: loads context (evidence: `backend/app/services/assistant_service.py`)
- Grounded assistant → Occupancy forecasts: loads context (evidence: `backend/app/services/assistant_service.py`)
- Grounded assistant → Risk assessment: loads context (evidence: `backend/app/services/assistant_service.py`)
- Zone metrics → Redis: caches live metrics (evidence: `backend/app/services/metrics_service.py`)
- Zone metrics → PostgreSQL: persists metrics
- Occupancy forecasts → PostgreSQL: persists forecasts
- Incident lifecycle → PostgreSQL: stores incidents
- Grounded assistant → PostgreSQL: stores query logs
