# supratim-2006/traffic-website architecture

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

- Interactive diagram: https://gitdiagram.com/supratim-2006/traffic-website
- Repository: https://github.com/supratim-2006/traffic-website

## Overview

1. **Overall shape**
   This is a **TanStack Start** application: a React 19 UI with **SSR via Nitro**, built and served as a full-stack web app rather than a purely client-side SPA. The main user experience is a traffic operations dashboard for incident management.

2. **Request and render entry points**
   The app boots through `src/start.ts` and `src/server.ts`, which define the client/server execution boundary. `src/router.tsx` plus the generated `src/routeTree.gen.ts` wire up the TanStack Router tree, while `src/routes/__root.tsx` provides the shared layout shell and `src/routes/index.tsx` is the primary dashboard route.

3. **Primary domain surface**
   The core product area lives under `src/components/dashboard/`. These components form the command-center workflow: incident intake, location selection, live detection, congestion analysis, map-based diversion routing, dispatch recommendations, and results summaries. The dashboard is decomposed into many focused panels rather than one monolith.

4. **Data flow through the dashboard**
   A typical flow is: **incident input / location selection** → **analysis modules** (emergency detection, congestion scoring, predictions, detected objects, heatmap) → **recommendations and dispatch** → **route diversion visualization**. Components like `IncidentInput`, `LocationPicker`, `CongestionAnalysis`, `Predictions`, `Recommendations`, `DispatchPanel`, and `RoutingDiversions` suggest the UI is organized around this operational pipeline.

5. **Map and geospatial layer**
   Geospatial rendering is a major subsystem. `TrafficHeatmap`, `DiversionRouteMap`, and `RoutingDiversions` indicate the app uses **Leaflet** and **Leaflet.heat** to show incident locations, congestion intensity, and alternative routes. The custom type declaration in `src/types/leaflet-heat.d.ts` exists to support the heatmap integration cleanly in TypeScript.

6. **API and integration boundary**
   `src/lib/traffic-api.ts` is the likely integration layer for traffic-related data and analysis. The README also calls out **TanStack Query**, so the app probably treats external or server-backed traffic data as queryable resources rather than embedding fetch logic in UI components. This keeps network concerns separated from presentation.

7. **Shared UI system**
   `src/components/ui/` contains the reusable design-system primitives, likely generated from **shadcn/ui** and built on **Radix UI**. These are the low-level building blocks used across the dashboard for dialogs, tabs, sheets, tables, buttons, inputs, etc., while the dashboard-specific components compose those primitives into operational screens.

8. **Layout, navigation, and responsiveness**
   `DashboardLayout`, `TopBar`, `WorkflowSidebar`, `TabContent`, and `SectionHeader` define the app shell and navigation hierarchy. `src/hooks/use-mobile.tsx` suggests responsive behavior is centralized so the dashboard can adapt between desktop control-room layouts and smaller screens.

9. **Error handling and resilience**
   `src/lib/error-capture.ts`, `src/lib/error-page.ts`, and `src/lib/lovable-error-reporting.ts` indicate explicit error boundary/reporting support. This matters because the app likely depends on live data and map rendering, both of which need graceful failure states.

10. **Styling and global assets**
    Global styling is driven by `src/styles.css` with **Tailwind CSS v4**. Static assets live in `public/`, and the `components.json` configuration confirms the shadcn/ui pipeline. The repo is optimized for a design-system-driven UI rather than custom CSS per component.

11. **Type and build-time boundaries**
    `src/types/` holds shared TypeScript definitions, while `src/routeTree.gen.ts` is generated and should be treated as build output, not source of truth. The build setup (`vite.config.ts`, `bunfig.toml`, `package.json`) is oriented around **Bun** for install/run and Vite/TanStack Start for bundling.

12. **Deployment model**
    The README states deployment targets **Vercel** using the TanStack Start preset. In architecture terms, that means the app is shipped as an SSR-capable web service with static asset delivery and server-side rendering managed by the framework/runtime, not a separate backend repository.

Main entry points: [`src/components/dashboard/DashboardLayout.tsx`](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DashboardLayout.tsx) (Dashboard shell), [`src/lib/traffic-api.ts`](https://github.com/supratim-2006/traffic-website/blob/main/src/lib/traffic-api.ts) (Traffic API), [`src/components/dashboard/CongestionAnalysis.tsx`](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/CongestionAnalysis.tsx) (Congestion analysis), [`src/components/ui`](https://github.com/supratim-2006/traffic-website/tree/main/src/components/ui) (UI primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & entry"]
  node_src_start["App start<br/>entry/client bootstrap<br/>[start.ts]"]
  node_src_server["Server entry<br/>entry/ssr server<br/>[server.ts]"]
  node_src_router["Router<br/>routing setup<br/>[router.tsx]"]
  node_src_route_tree["Route tree<br/>generated routes<br/>[routeTree.gen.ts]"]
  node_root_route["Root layout<br/>route shell<br/>[__root.tsx]"]
  node_index_route["Dashboard route<br/>main page<br/>[index.tsx]"]
end

subgraph group_dashboard["Dashboard domain"]
  node_dashboard_layout["Dashboard shell<br/>layout"]
  node_top_bar["Top bar<br/>navigation header<br/>[TopBar.tsx]"]
  node_workflow_sidebar["Sidebar<br/>workflow nav"]
  node_tab_content["Tab content<br/>content switcher<br/>[TabContent.tsx]"]
  node_incident_input["Incident input<br/>intake form<br/>[IncidentInput.tsx]"]
  node_location_picker["Location picker<br/>geo input<br/>[LocationPicker.tsx]"]
  node_congestion_analysis["Congestion analysis<br/>analysis panel"]
  node_emergency_detection["Detection<br/>event analysis"]
  node_predictions["Predictions<br/>forecast panel<br/>[Predictions.tsx]"]
  node_routing_diversions["Diversions<br/>routing workflow"]
  node_dispatch_panel["Dispatch panel<br/>response actions<br/>[DispatchPanel.tsx]"]
  node_recommendations["Recommendations<br/>decision support"]
  node_traffic_heatmap["Heatmap<br/>map overlay<br/>[TrafficHeatmap.tsx]"]
  node_diversion_route_map["Route map<br/>map view"]
end

subgraph group_ui["Shared UI system"]
  node_ui_primitives["UI primitives<br/>design system"]
end

subgraph group_infra["Infra & integration"]
  node_traffic_api["Traffic API<br/>data client<br/>[traffic-api.ts]"]
  node_error_support["Error support<br/>resilience<br/>[error-capture.ts]"]
  node_theme_styles["Global styles<br/>tailwind css<br/>[styles.css]"]
  node_leaflet_heat_type["Leaflet types<br/>type def<br/>[leaflet-heat.d.ts]"]
  node_use_mobile["Mobile hook<br/>responsive hook<br/>[use-mobile.tsx]"]
end

node_src_start -->|"boots"| node_src_router
node_src_server -->|"serves"| node_src_router
node_src_router -->|"uses"| node_src_route_tree
node_src_route_tree -->|"includes"| node_root_route
node_root_route -->|"nests"| node_index_route
node_index_route -->|"renders"| node_dashboard_layout
node_dashboard_layout -->|"contains"| node_top_bar
node_dashboard_layout -->|"contains"| node_workflow_sidebar
node_dashboard_layout -->|"contains"| node_tab_content
node_tab_content -->|"starts"| node_incident_input
node_incident_input -->|"feeds"| node_location_picker
node_location_picker -->|"initiates"| node_emergency_detection
node_emergency_detection -->|"updates"| node_congestion_analysis
node_congestion_analysis -->|"feeds"| node_predictions
node_congestion_analysis -->|"visualizes"| node_traffic_heatmap
node_predictions -->|"drives"| node_recommendations
node_recommendations -->|"prompts"| node_dispatch_panel
node_dispatch_panel -->|"coordinates"| node_routing_diversions
node_routing_diversions -->|"renders"| node_diversion_route_map
node_traffic_api -->|"supplies data"| node_congestion_analysis
node_traffic_api -->|"supplies data"| node_predictions
node_traffic_api -->|"supplies data"| node_routing_diversions
node_error_support -->|"guards"| node_dashboard_layout
node_error_support -->|"reports"| node_traffic_api
node_theme_styles -->|"styles"| node_ui_primitives
node_ui_primitives -->|"builds"| node_dashboard_layout
node_ui_primitives -->|"builds"| node_incident_input
node_use_mobile -->|"adapts"| node_dashboard_layout
node_leaflet_heat_type -->|"supports"| node_traffic_heatmap

click node_src_start "https://github.com/supratim-2006/traffic-website/blob/main/src/start.ts"
click node_src_server "https://github.com/supratim-2006/traffic-website/blob/main/src/server.ts"
click node_src_router "https://github.com/supratim-2006/traffic-website/blob/main/src/router.tsx"
click node_src_route_tree "https://github.com/supratim-2006/traffic-website/blob/main/src/routeTree.gen.ts"
click node_root_route "https://github.com/supratim-2006/traffic-website/blob/main/src/routes/__root.tsx"
click node_index_route "https://github.com/supratim-2006/traffic-website/blob/main/src/routes/index.tsx"
click node_dashboard_layout "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DashboardLayout.tsx"
click node_top_bar "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TopBar.tsx"
click node_workflow_sidebar "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/WorkflowSidebar.tsx"
click node_tab_content "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TabContent.tsx"
click node_incident_input "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/IncidentInput.tsx"
click node_location_picker "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/LocationPicker.tsx"
click node_congestion_analysis "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/CongestionAnalysis.tsx"
click node_emergency_detection "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/EmergencyDetection.tsx"
click node_predictions "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/Predictions.tsx"
click node_routing_diversions "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/RoutingDiversions.tsx"
click node_dispatch_panel "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DispatchPanel.tsx"
click node_recommendations "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/Recommendations.tsx"
click node_traffic_heatmap "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TrafficHeatmap.tsx"
click node_diversion_route_map "https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DiversionRouteMap.tsx"
click node_traffic_api "https://github.com/supratim-2006/traffic-website/blob/main/src/lib/traffic-api.ts"
click node_error_support "https://github.com/supratim-2006/traffic-website/blob/main/src/lib/error-capture.ts"
click node_theme_styles "https://github.com/supratim-2006/traffic-website/blob/main/src/styles.css"
click node_leaflet_heat_type "https://github.com/supratim-2006/traffic-website/blob/main/src/types/leaflet-heat.d.ts"
click node_use_mobile "https://github.com/supratim-2006/traffic-website/blob/main/src/hooks/use-mobile.tsx"
click node_ui_primitives "https://github.com/supratim-2006/traffic-website/tree/main/src/components/ui"

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_src_start,node_src_server,node_src_router,node_src_route_tree,node_root_route,node_index_route toneBlue
class node_dashboard_layout,node_top_bar,node_workflow_sidebar,node_tab_content,node_incident_input,node_location_picker,node_congestion_analysis,node_emergency_detection,node_predictions,node_routing_diversions,node_dispatch_panel,node_recommendations,node_traffic_heatmap,node_diversion_route_map toneAmber
class node_ui_primitives toneMint
class node_traffic_api,node_error_support,node_theme_styles,node_leaflet_heat_type,node_use_mobile toneRose
```

## Components

### Runtime & entry

SSR app bootstrap, router wiring, and server/client boundary.

- [App start](https://github.com/supratim-2006/traffic-website/blob/main/src/start.ts): entry/client bootstrap · Client-side TanStack Start bootstrap entry. · `src/start.ts`
- [Server entry](https://github.com/supratim-2006/traffic-website/blob/main/src/server.ts): entry/ssr server · Server-side runtime entry for Nitro/SSR. · `src/server.ts`
- [Router](https://github.com/supratim-2006/traffic-website/blob/main/src/router.tsx): routing setup · TanStack Router configuration and route wiring. · `src/router.tsx`
- [Route tree](https://github.com/supratim-2006/traffic-website/blob/main/src/routeTree.gen.ts): generated routes · Generated TanStack route tree. · `src/routeTree.gen.ts`
- [Root layout](https://github.com/supratim-2006/traffic-website/blob/main/src/routes/__root.tsx): route shell · Shared app shell and global route wrapper. · `src/routes/__root.tsx`
- [Dashboard route](https://github.com/supratim-2006/traffic-website/blob/main/src/routes/index.tsx): main page · Primary dashboard screen entry route. · `src/routes/index.tsx`

### Dashboard domain

Traffic operations workflow and map-centered incident handling UI.

- [Dashboard shell](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DashboardLayout.tsx): layout · Top-level dashboard layout and page framing. · `src/components/dashboard/DashboardLayout.tsx`
- [Top bar](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TopBar.tsx): navigation header · Global header and top-level controls. · `src/components/dashboard/TopBar.tsx`
- [Sidebar](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/WorkflowSidebar.tsx): workflow nav · Navigation and workflow staging for the dashboard. · `src/components/dashboard/WorkflowSidebar.tsx`
- [Tab content](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TabContent.tsx): content switcher · Panel container for dashboard sections. · `src/components/dashboard/TabContent.tsx`
- [Incident input](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/IncidentInput.tsx): intake form · Incident intake and initial case details. · `src/components/dashboard/IncidentInput.tsx`
- [Location picker](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/LocationPicker.tsx): geo input · Incident location selection and geospatial targeting. · `src/components/dashboard/LocationPicker.tsx`
- [Congestion analysis](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/CongestionAnalysis.tsx): analysis panel · Traffic congestion scoring and operational analysis. · `src/components/dashboard/CongestionAnalysis.tsx`
- [Detection](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/EmergencyDetection.tsx): event analysis · Emergency detection and incident recognition logic in the UI flow. · `src/components/dashboard/EmergencyDetection.tsx`
- [Predictions](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/Predictions.tsx): forecast panel · Forward-looking traffic or incident predictions. · `src/components/dashboard/Predictions.tsx`
- [Diversions](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/RoutingDiversions.tsx): routing workflow · Route diversion orchestration and guidance output. · `src/components/dashboard/RoutingDiversions.tsx`
- [Dispatch panel](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DispatchPanel.tsx): response actions · Dispatch recommendations and response actions. · `src/components/dashboard/DispatchPanel.tsx`
- [Recommendations](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/Recommendations.tsx): decision support · Recommended operational actions derived from analysis. · `src/components/dashboard/Recommendations.tsx`
- [Heatmap](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/TrafficHeatmap.tsx): map overlay · Traffic intensity visualization using Leaflet heatmap integration. · `src/components/dashboard/TrafficHeatmap.tsx`
- [Route map](https://github.com/supratim-2006/traffic-website/blob/main/src/components/dashboard/DiversionRouteMap.tsx): map view · Map-based visualization of diversion routes. · `src/components/dashboard/DiversionRouteMap.tsx`

### Shared UI system

Reusable design-system primitives and general-purpose UI helpers.

- [UI primitives](https://github.com/supratim-2006/traffic-website/tree/main/src/components/ui): design system · Reusable shadcn/Radix-style components used throughout the app. · `src/components/ui`

### Infra & integration

Data access, error handling, styling, and type/runtime support.

- [Traffic API](https://github.com/supratim-2006/traffic-website/blob/main/src/lib/traffic-api.ts): data client · Integration layer for traffic-related data and analysis. · `src/lib/traffic-api.ts`
- [Error support](https://github.com/supratim-2006/traffic-website/blob/main/src/lib/error-capture.ts): resilience · Error capture, reporting, and error page utilities. · `src/lib/error-capture.ts`
- [Global styles](https://github.com/supratim-2006/traffic-website/blob/main/src/styles.css): tailwind css · Global stylesheet and theme layer. · `src/styles.css`
- [Leaflet types](https://github.com/supratim-2006/traffic-website/blob/main/src/types/leaflet-heat.d.ts): type def · TypeScript declaration for Leaflet heatmap support. · `src/types/leaflet-heat.d.ts`
- [Mobile hook](https://github.com/supratim-2006/traffic-website/blob/main/src/hooks/use-mobile.tsx): responsive hook · Centralized responsive behavior for smaller screens. · `src/hooks/use-mobile.tsx`

## Connections

- App start → Router: boots · Client bootstrap enters routing stack.
- Server entry → Router: serves · Server runtime serves the routed app.
- Router → Route tree: uses · Router consumes generated route tree.
- Route tree → Root layout: includes · Generated tree includes the root route.
- Root layout → Dashboard route: nests · Root layout wraps the dashboard page route.
- Dashboard route → Dashboard shell: renders · Main route composes dashboard shell.
- Dashboard shell → Top bar: contains · Layout includes the top-level header.
- Dashboard shell → Sidebar: contains · Layout includes workflow navigation.
- Dashboard shell → Tab content: contains · Layout hosts tabbed dashboard content.
- Tab content → Incident input: starts · Incident intake begins the workflow.
- Incident input → Location picker: feeds · Incident details lead into location selection.
- Location picker → Detection: initiates · Location/context feeds detection stage.
- Detection → Congestion analysis: updates · Detection informs congestion analysis.
- Congestion analysis → Predictions: feeds · Analysis results drive predictions.
- Congestion analysis → Heatmap: visualizes · Congestion intensity is shown on the heatmap.
- Predictions → Recommendations: drives · Forecasts inform recommended actions.
- Recommendations → Dispatch panel: prompts · Recommendations surface dispatch actions.
- Dispatch panel → Diversions: coordinates · Dispatch decisions coordinate diversions.
- Diversions → Route map: renders · Diversion workflow is visualized on the map.
- Traffic API → Congestion analysis: supplies data · Analysis pulls traffic data from the integration layer.
- Traffic API → Predictions: supplies data · Prediction stage can query traffic data.
- Traffic API → Diversions: supplies data · Diversion planning can use external traffic data.
- Error support → Dashboard shell: guards · App shell can present resilient error states.
- Error support → Traffic API: reports · Integration errors are captured and reported.
- Global styles → UI primitives: styles · Global styling supports the shared component system.
- UI primitives → Dashboard shell: builds · Layout uses shared primitives.
- UI primitives → Incident input: builds · Form and input widgets are composed from primitives.
- Mobile hook → Dashboard shell: adapts · Responsive behavior shapes the dashboard shell.
- Leaflet types → Heatmap: supports · Type declaration supports heatmap integration.