# 42andbeyond/traffic-ai-system architecture

> Architecture diagram of the GitHub repository 42andbeyond/traffic-ai-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/42andbeyond/traffic-ai-system
- Repository: https://github.com/42andbeyond/traffic-ai-system

## Overview

PathWise helps commuters compare fastest and safer routes and lets traffic authorities analyze station-isolated incident data and run risk predictions. Users interact through a role-based React dashboard; FastAPI handles authentication and domain requests, using SQLite for accounts, road data, and incidents and the ML engine for scoring and route optimization. The README documents capabilities beyond the sampled excerpts; those are represented without asserting unsampled internal call paths.

Main entry points: [`frontend/src/App.jsx`](https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx) (Role-based dashboard), [`backend/database.py`](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/database.py) (Traffic system database), [`backend/main.py`](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py) (Route optimization endpoint), [`backend/ml_engine.py`](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/ml_engine.py) (Risk and route models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_dashboard["Role-based dashboard<br/>[App.jsx]"]
  node_route_view["Route comparison<br/>[App.jsx]"]
  node_analytics_view["Analytics views<br/>[App.jsx]"]
  node_map["Interactive map<br/>[App.jsx]"]
end

subgraph group_api["Traffic API"]
  node_auth["JWT authentication<br/>[main.py]"]
  node_dataset["Station dataset upload<br/>[main.py]"]
  node_analytics["Incident analytics<br/>[main.py]"]
  node_junctions["Junction directory<br/>[main.py]"]
  node_prediction["Risk prediction endpoint<br/>[main.py]"]
  node_route_api["Route optimization endpoint<br/>[main.py]"]
end

subgraph group_domain["Traffic intelligence"]
  node_ml["Risk and route models<br/>[ml_engine.py]"]
end

subgraph group_state["Persistent data"]
  node_store[("Traffic system database<br/>[database.py]")]
end

node_commuter(("Commuter"))
node_authority(("Police authority"))
node_osm["OpenStreetMap tiles"]

node_commuter -->|"uses"| node_dashboard
node_authority -->|"uses"| node_dashboard
node_dashboard -->|"registers / logs in"| node_auth
node_dashboard -->|"requests prediction"| node_prediction
node_dashboard -->|"requests routes"| node_route_api
node_dashboard -->|"loads overview"| node_analytics
node_dashboard -->|"uploads dataset"| node_dataset
node_dashboard -->|"renders"| node_route_view
node_dashboard -->|"renders"| node_analytics_view
node_dashboard -->|"renders"| node_map
node_map -->|"loads map tiles"| node_osm
node_prediction -->|"scores conditions"| node_ml
node_route_api -->|"computes routes"| node_ml
node_auth -->|"reads / writes accounts"| node_store
node_dataset -->|"replaces station records"| node_store
node_analytics -->|"reads incident records"| node_store
node_junctions -->|"reads road edges"| node_store
node_route_api -->|"reads road edges"| node_store

click node_dashboard "https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx"
click node_route_view "https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx"
click node_analytics_view "https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx"
click node_map "https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx"
click node_auth "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_dataset "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_analytics "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_junctions "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_prediction "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_route_api "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py"
click node_ml "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/ml_engine.py"
click node_store "https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/database.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_dashboard,node_route_view,node_analytics_view,node_map toneBlue
class node_auth,node_dataset,node_analytics,node_junctions,node_prediction,node_route_api toneAmber
class node_ml toneMint
class node_store toneRose
class node_commuter,node_authority,node_osm toneIndigo
```

## Components

### Web experience

- [Role-based dashboard](https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Route comparison](https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Analytics views](https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Interactive map](https://github.com/42andbeyond/traffic-ai-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Traffic API

- [JWT authentication](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`
- [Station dataset upload](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`
- [Incident analytics](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`
- [Junction directory](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`
- [Risk prediction endpoint](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`
- [Route optimization endpoint](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/main.py): `backend/main.py`

### Traffic intelligence

- [Risk and route models](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/ml_engine.py): `backend/ml_engine.py`

### Persistent data

- [Traffic system database](https://github.com/42andbeyond/traffic-ai-system/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Commuter**
- **Police authority**
- **OpenStreetMap tiles**

## Connections

- Commuter → Role-based dashboard: uses (evidence: `README.md`)
- Police authority → Role-based dashboard: uses (evidence: `README.md`)
- Role-based dashboard → JWT authentication: registers / logs in (evidence: `frontend/src/App.jsx`)
- Role-based dashboard → Risk prediction endpoint: requests prediction (evidence: `frontend/src/App.jsx`)
- Role-based dashboard → Route optimization endpoint: requests routes (evidence: `frontend/src/App.jsx`)
- Role-based dashboard → Incident analytics: loads overview (evidence: `README.md`)
- Role-based dashboard → Station dataset upload: uploads dataset (evidence: `README.md`)
- Role-based dashboard → Route comparison: renders (evidence: `frontend/src/App.jsx`)
- Role-based dashboard → Analytics views: renders (evidence: `README.md`)
- Role-based dashboard → Interactive map: renders (evidence: `frontend/src/App.jsx`)
- Interactive map → OpenStreetMap tiles: loads map tiles (evidence: `frontend/src/App.jsx`)
- Risk prediction endpoint → Risk and route models: scores conditions (evidence: `backend/main.py`)
- Route optimization endpoint → Risk and route models: computes routes (evidence: `backend/main.py`)
- JWT authentication → Traffic system database: reads / writes accounts (evidence: `backend/main.py`)
- Station dataset upload → Traffic system database: replaces station records (evidence: `backend/main.py`)
- Incident analytics → Traffic system database: reads incident records (evidence: `backend/main.py`)
- Junction directory → Traffic system database: reads road edges (evidence: `backend/main.py`)
- Route optimization endpoint → Traffic system database: reads road edges (evidence: `backend/main.py`)
