# v1zd0n/safetycar architecture

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

- Interactive diagram: https://gitdiagram.com/v1zd0n/safetycar
- Repository: https://github.com/v1zd0n/safetycar

## Overview

SafetyCar is a prototype for assessing risk on Bulgaria’s national-road routes. Visitors can explore a scroll-driven 3D landing story and sample hotspot heatmap, then open the route demo to choose places and a vehicle, view a route and its risk segments, and use location/navigation features. With the supplied backend configured, route requests use Mapbox Directions and return baseline risk estimates with recent road reports where available; otherwise the demo uses sample routes. Backend and analysis links are limited to the README and SOURCE INDEX evidence shown.

Main entry points: [`src/App.tsx`](https://github.com/v1zd0n/safetycar/blob/main/src/App.tsx) (App routing), [`backend/src/route.mjs`](https://github.com/v1zd0n/safetycar/blob/main/backend/src/route.mjs) (Route API), [`src/MapDashboard.tsx`](https://github.com/v1zd0n/safetycar/blob/main/src/MapDashboard.tsx) (Route dashboard), [`src/data/demoRoute.ts`](https://github.com/v1zd0n/safetycar/blob/main/src/data/demoRoute.ts) (Route data client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_story["Landing story"]
  node_app["App routing<br/>[App.tsx]"]
  node_storytimeline["Story timeline<br/>[useStory.ts]"]
  node_storystate["Story state<br/>[store.ts]"]
  node_scene["3D scene<br/>[Experience.tsx]"]
  node_cockpit["Cockpit display<br/>[Cockpit.tsx]"]
  node_landingmap["Landing heatmap<br/>[MapView.tsx]"]
  node_language["Language context<br/>[LangContext.tsx]"]
end

subgraph group_demo["Route demo"]
  node_dashboard["Route dashboard<br/>[MapDashboard.tsx]"]
  node_routeclient["Route data client<br/>[demoRoute.ts]"]
  node_routemap["Route map<br/>[RouteMap.tsx]"]
  node_stationlayer["Live stations layer<br/>[stationsLayer.ts]"]
  node_geolocation["Geolocation<br/>[useGeolocation.ts]"]
end

subgraph group_api["Route services"]
  node_backend["API server<br/>[server.mjs]"]
  node_routeapi["Route API<br/>[route.mjs]"]
  node_livedata["Live feed polling<br/>[poll.mjs]"]
  node_database[("PostgreSQL / PostGIS<br/>[db.mjs]")]
end

subgraph group_assessment["Risk assessment"]
  node_analysisdb["Assessment data access<br/>[db.py]"]
  node_baseline["Baseline assessment<br/>[explain.py]"]
  node_reactive["Reactive risk<br/>[reactive.py]"]
  node_weights["Risk weights<br/>[weights.py]"]
  node_proactive["Proactive risk<br/>[proactive.py]"]
end

node_visitor(("Visitor"))
node_directions{{"Mapbox Directions"}}

node_visitor -->|"opens app"| node_app
node_app -->|"starts story"| node_storytimeline
node_app -->|"loads scene"| node_scene
node_app -->|"renders cockpit"| node_cockpit
node_app -->|"loads map"| node_landingmap
node_app -->|"routes demo"| node_dashboard
node_storytimeline -->|"updates state"| node_storystate
node_scene -->|"reads rig"| node_storystate
node_app -->|"provides language"| node_language
node_dashboard -->|"loads routes"| node_routeclient
node_dashboard -->|"renders route"| node_routemap
node_dashboard -->|"gets position"| node_geolocation
node_routemap -->|"uses station layer"| node_stationlayer
node_routeclient -->|"requests directions"| node_directions
node_routeclient -->|"requests route"| node_backend
node_backend -->|"routes requests"| node_routeapi
node_backend -->|"polls live data"| node_livedata
node_routeapi -->|"queries risk data"| node_database
node_routeapi -->|"gets route geometry"| node_directions
node_routeapi -->|"evaluates route risk"| node_baseline
node_routeapi -->|"uses road reports"| node_reactive
node_livedata -->|"stores feed data"| node_database
node_baseline -->|"uses data access"| node_analysisdb
node_reactive -->|"uses data access"| node_analysisdb
node_weights -->|"uses data access"| node_analysisdb
node_weights -->|"imports assessment"| node_proactive

click node_app "https://github.com/v1zd0n/safetycar/blob/main/src/App.tsx"
click node_storytimeline "https://github.com/v1zd0n/safetycar/blob/main/src/scroll/useStory.ts"
click node_storystate "https://github.com/v1zd0n/safetycar/blob/main/src/scroll/store.ts"
click node_scene "https://github.com/v1zd0n/safetycar/blob/main/src/three/Experience.tsx"
click node_cockpit "https://github.com/v1zd0n/safetycar/blob/main/src/cockpit/Cockpit.tsx"
click node_landingmap "https://github.com/v1zd0n/safetycar/blob/main/src/map/MapView.tsx"
click node_language "https://github.com/v1zd0n/safetycar/blob/main/src/i18n/LangContext.tsx"
click node_dashboard "https://github.com/v1zd0n/safetycar/blob/main/src/MapDashboard.tsx"
click node_routeclient "https://github.com/v1zd0n/safetycar/blob/main/src/data/demoRoute.ts"
click node_routemap "https://github.com/v1zd0n/safetycar/blob/main/src/map/RouteMap.tsx"
click node_stationlayer "https://github.com/v1zd0n/safetycar/blob/main/src/map/stationsLayer.ts"
click node_geolocation "https://github.com/v1zd0n/safetycar/blob/main/src/demo/useGeolocation.ts"
click node_backend "https://github.com/v1zd0n/safetycar/blob/main/backend/src/server.mjs"
click node_routeapi "https://github.com/v1zd0n/safetycar/blob/main/backend/src/route.mjs"
click node_livedata "https://github.com/v1zd0n/safetycar/blob/main/backend/src/live/poll.mjs"
click node_database "https://github.com/v1zd0n/safetycar/blob/main/backend/src/db.mjs"
click node_analysisdb "https://github.com/v1zd0n/safetycar/blob/main/analysis/db.py"
click node_baseline "https://github.com/v1zd0n/safetycar/blob/main/analysis/explain.py"
click node_reactive "https://github.com/v1zd0n/safetycar/blob/main/analysis/reactive.py"
click node_weights "https://github.com/v1zd0n/safetycar/blob/main/analysis/weights.py"
click node_proactive "https://github.com/v1zd0n/safetycar/blob/main/analysis/proactive.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_app,node_storytimeline,node_storystate,node_scene,node_cockpit,node_landingmap,node_language toneBlue
class node_dashboard,node_routeclient,node_routemap,node_stationlayer,node_geolocation toneAmber
class node_backend,node_routeapi,node_livedata,node_database toneMint
class node_analysisdb,node_baseline,node_reactive,node_weights,node_proactive toneRose
class node_visitor,node_directions toneIndigo
```

## Components

### Landing story

- [App routing](https://github.com/v1zd0n/safetycar/blob/main/src/App.tsx): `src/App.tsx`
- [Story timeline](https://github.com/v1zd0n/safetycar/blob/main/src/scroll/useStory.ts): `src/scroll/useStory.ts`
- [Story state](https://github.com/v1zd0n/safetycar/blob/main/src/scroll/store.ts): `src/scroll/store.ts`
- [3D scene](https://github.com/v1zd0n/safetycar/blob/main/src/three/Experience.tsx): `src/three/Experience.tsx`
- [Cockpit display](https://github.com/v1zd0n/safetycar/blob/main/src/cockpit/Cockpit.tsx): `src/cockpit/Cockpit.tsx`
- [Landing heatmap](https://github.com/v1zd0n/safetycar/blob/main/src/map/MapView.tsx): `src/map/MapView.tsx`
- [Language context](https://github.com/v1zd0n/safetycar/blob/main/src/i18n/LangContext.tsx): `src/i18n/LangContext.tsx`

### Route demo

- [Route dashboard](https://github.com/v1zd0n/safetycar/blob/main/src/MapDashboard.tsx): `src/MapDashboard.tsx`
- [Route data client](https://github.com/v1zd0n/safetycar/blob/main/src/data/demoRoute.ts): `src/data/demoRoute.ts`
- [Route map](https://github.com/v1zd0n/safetycar/blob/main/src/map/RouteMap.tsx): `src/map/RouteMap.tsx`
- [Live stations layer](https://github.com/v1zd0n/safetycar/blob/main/src/map/stationsLayer.ts): `src/map/stationsLayer.ts`
- [Geolocation](https://github.com/v1zd0n/safetycar/blob/main/src/demo/useGeolocation.ts): `src/demo/useGeolocation.ts`

### Route services

- [API server](https://github.com/v1zd0n/safetycar/blob/main/backend/src/server.mjs): `backend/src/server.mjs`
- [Route API](https://github.com/v1zd0n/safetycar/blob/main/backend/src/route.mjs): `backend/src/route.mjs`
- [Live feed polling](https://github.com/v1zd0n/safetycar/blob/main/backend/src/live/poll.mjs): `backend/src/live/poll.mjs`
- [PostgreSQL / PostGIS](https://github.com/v1zd0n/safetycar/blob/main/backend/src/db.mjs): `backend/src/db.mjs`

### Risk assessment

- [Assessment data access](https://github.com/v1zd0n/safetycar/blob/main/analysis/db.py): `analysis/db.py`
- [Baseline assessment](https://github.com/v1zd0n/safetycar/blob/main/analysis/explain.py): `analysis/explain.py`
- [Reactive risk](https://github.com/v1zd0n/safetycar/blob/main/analysis/reactive.py): `analysis/reactive.py`
- [Risk weights](https://github.com/v1zd0n/safetycar/blob/main/analysis/weights.py): `analysis/weights.py`
- [Proactive risk](https://github.com/v1zd0n/safetycar/blob/main/analysis/proactive.py): `analysis/proactive.py`

### Other components

- **Visitor**
- **Mapbox Directions**

## Connections

- Visitor → App routing: opens app (evidence: `src/App.tsx`)
- App routing → Story timeline: starts story (evidence: `src/App.tsx`)
- App routing → 3D scene: loads scene (evidence: `src/App.tsx`)
- App routing → Cockpit display: renders cockpit (evidence: `src/App.tsx`)
- App routing → Landing heatmap: loads map (evidence: `src/App.tsx`)
- App routing → Route dashboard: routes demo (evidence: `src/App.tsx`)
- Story timeline → Story state: updates state (evidence: `src/scroll/useStory.ts`)
- 3D scene → Story state: reads rig (evidence: `src/three/Experience.tsx`)
- App routing → Language context: provides language (evidence: `src/App.tsx`)
- Route dashboard → Route data client: loads routes (evidence: `src/MapDashboard.tsx`)
- Route dashboard → Route map: renders route (evidence: `src/MapDashboard.tsx`)
- Route dashboard → Geolocation: gets position (evidence: `src/MapDashboard.tsx`)
- Route map → Live stations layer: uses station layer (evidence: `src/map/RouteMap.tsx`)
- Route data client → Mapbox Directions: requests directions (evidence: `README.md`)
- Route data client → API server: requests route (evidence: `src/data/demoRoute.ts`)
- API server → Route API: routes requests (evidence: `backend/src/server.mjs`)
- API server → Live feed polling: polls live data (evidence: `backend/src/server.mjs`)
- Route API → PostgreSQL / PostGIS: queries risk data (evidence: `backend/src/route.mjs`)
- Route API → Mapbox Directions: gets route geometry (evidence: `README.md`)
- Route API → Baseline assessment: evaluates route risk (evidence: `README.md`)
- Route API → Reactive risk: uses road reports (evidence: `README.md`)
- Live feed polling → PostgreSQL / PostGIS: stores feed data (evidence: `backend/src/live/poll.mjs`)
- Baseline assessment → Assessment data access: uses data access (evidence: `analysis/explain.py`)
- Reactive risk → Assessment data access: uses data access (evidence: `analysis/reactive.py`)
- Risk weights → Assessment data access: uses data access (evidence: `analysis/weights.py`)
- Risk weights → Proactive risk: imports assessment (evidence: `analysis/weights.py`)
