# fotatoe24/busahero-webapp architecture

> Architecture diagram of the GitHub repository fotatoe24/busahero-webapp, 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/fotatoe24/busahero-webapp
- Repository: https://github.com/fotatoe24/busahero-webapp

## Overview

BUSAhero is an operator-facing bus fleet dashboard with live bus monitoring, bus details, and distance-based fare settings. Operators register or sign in, then view bus status and map data or edit bus and fare information; session and terms controls gate access. Firebase supplies realtime bus data and fare settings, with simulated buses when Firebase is unavailable. The README also describes fare CRUD, but the sampled Fares page implements fare calculation settings. Some unsampled subsystem relationships are omitted rather than inferred.

Main entry points: [`lib/useAuth.tsx`](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useAuth.tsx) (Auth state), [`lib/useRealtimeBuses.ts`](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useRealtimeBuses.ts) (Realtime bus feed), [`app/dashboard/page.tsx`](https://github.com/fotatoe24/busahero-webapp/blob/main/app/dashboard/page.tsx) (Dashboard), [`app/api/register/route.ts`](https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/register/route.ts) (Registration API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_authui["Sign-in and registration<br/>[page.tsx]"]
  node_authclient["Auth state<br/>[useAuth.tsx]"]
  node_register["Registration API<br/>[route.ts]"]
  node_loginapi["Login API<br/>[route.ts]"]
  node_session["Session cookies<br/>[session.ts]"]
  node_operatorstore[("Operator records<br/>[supabaseAdmin.ts]")]
  node_terms["Terms acceptance<br/>[route.ts]"]
  node_guard["Access guard<br/>[AuthGuard.tsx]"]
  node_termsgate["Terms gate<br/>[TermsGate.tsx]"]
end

subgraph group_fleet["Fleet monitoring"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_businfo["Bus information<br/>[page.tsx]"]
  node_busfeed["Realtime bus feed"]
  node_busdata[("Bus database")]
  node_busstatus["Status normalization<br/>[busStatus.ts]"]
  node_map["Live bus map<br/>[RealtimeMap.tsx]"]
  node_routes["Route geometry<br/>[routes.ts]"]
end

subgraph group_fares["Fare management"]
  node_farespage["Fare settings page<br/>[page.tsx]"]
  node_farehook["Fare settings state<br/>[useFareSettings.ts]"]
  node_faredata[("Fare settings store")]
  node_calculator["Fare matrix calculator"]
  node_faremath["Fare calculation<br/>[fareCalculator.ts]"]
  node_distances["Route distances<br/>[routeDistances.ts]"]
end

subgraph group_shared["Shared services"]
  node_firebase["Firebase client<br/>[firebase.ts]"]
end

node_operator(("Fleet operator"))

node_operator -->|"signs in"| node_authui
node_authui -->|"calls auth"| node_authclient
node_authclient -->|"posts registration"| node_register
node_register -->|"creates operator"| node_operatorstore
node_register -->|"creates session"| node_session
node_authclient -->|"posts credentials"| node_loginapi
node_loginapi -->|"checks operator"| node_operatorstore
node_loginapi -->|"creates session"| node_session
node_authclient -->|"accepts terms"| node_terms
node_terms -->|"reads session"| node_session
node_terms -->|"updates acceptance"| node_operatorstore
node_dashboard -->|"guards page"| node_guard
node_businfo -->|"guards page"| node_guard
node_guard -->|"checks operator"| node_authclient
node_termsgate -->|"checks acceptance"| node_authclient
node_dashboard -->|"reads buses"| node_busfeed
node_businfo -->|"reads and updates"| node_busfeed
node_busfeed -->|"uses database client"| node_firebase
node_busfeed -->|"subscribes and updates"| node_busdata
node_busfeed -->|"normalizes status"| node_busstatus
node_dashboard -->|"renders map"| node_map
node_map -->|"uses geometry"| node_routes
node_farespage -->|"loads settings"| node_farehook
node_farehook -->|"uses database client"| node_firebase
node_farehook -.->|"reads and writes"| node_faredata
node_farespage -->|"renders calculator"| node_calculator
node_calculator -->|"calculates fares"| node_faremath
node_calculator -->|"uses distances"| node_distances

click node_authui "https://github.com/fotatoe24/busahero-webapp/blob/main/app/page.tsx"
click node_authclient "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useAuth.tsx"
click node_register "https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/register/route.ts"
click node_loginapi "https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/login/route.ts"
click node_session "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/session.ts"
click node_operatorstore "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/supabaseAdmin.ts"
click node_terms "https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/accept-terms/route.ts"
click node_dashboard "https://github.com/fotatoe24/busahero-webapp/blob/main/app/dashboard/page.tsx"
click node_businfo "https://github.com/fotatoe24/busahero-webapp/blob/main/app/bus-info/page.tsx"
click node_busfeed "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useRealtimeBuses.ts"
click node_firebase "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/firebase.ts"
click node_busstatus "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/busStatus.ts"
click node_map "https://github.com/fotatoe24/busahero-webapp/blob/main/components/RealtimeMap.tsx"
click node_routes "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/routes.ts"
click node_farespage "https://github.com/fotatoe24/busahero-webapp/blob/main/app/fares/page.tsx"
click node_farehook "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useFareSettings.ts"
click node_calculator "https://github.com/fotatoe24/busahero-webapp/blob/main/components/FareMatrixCalculator.tsx"
click node_faremath "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/fareCalculator.ts"
click node_distances "https://github.com/fotatoe24/busahero-webapp/blob/main/lib/routeDistances.ts"
click node_guard "https://github.com/fotatoe24/busahero-webapp/blob/main/components/AuthGuard.tsx"
click node_termsgate "https://github.com/fotatoe24/busahero-webapp/blob/main/components/TermsGate.tsx"

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_authui,node_authclient,node_register,node_loginapi,node_session,node_operatorstore,node_terms,node_guard,node_termsgate toneBlue
class node_dashboard,node_businfo,node_busfeed,node_busdata,node_busstatus,node_map,node_routes toneAmber
class node_farespage,node_farehook,node_faredata,node_calculator,node_faremath,node_distances toneMint
class node_firebase toneRose
class node_operator toneIndigo
```

## Components

### Identity and access

- [Sign-in and registration](https://github.com/fotatoe24/busahero-webapp/blob/main/app/page.tsx): `app/page.tsx`
- [Auth state](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useAuth.tsx): `lib/useAuth.tsx`
- [Registration API](https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/register/route.ts): `app/api/register/route.ts`
- [Login API](https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/login/route.ts): `app/api/login/route.ts`
- [Session cookies](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/session.ts): `lib/session.ts`
- [Operator records](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/supabaseAdmin.ts): `lib/supabaseAdmin.ts`
- [Terms acceptance](https://github.com/fotatoe24/busahero-webapp/blob/main/app/api/accept-terms/route.ts): `app/api/accept-terms/route.ts`
- [Access guard](https://github.com/fotatoe24/busahero-webapp/blob/main/components/AuthGuard.tsx): `components/AuthGuard.tsx`
- [Terms gate](https://github.com/fotatoe24/busahero-webapp/blob/main/components/TermsGate.tsx): `components/TermsGate.tsx`

### Fleet monitoring

- [Dashboard](https://github.com/fotatoe24/busahero-webapp/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Bus information](https://github.com/fotatoe24/busahero-webapp/blob/main/app/bus-info/page.tsx): `app/bus-info/page.tsx`
- [Realtime bus feed](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useRealtimeBuses.ts): `lib/useRealtimeBuses.ts`
- **Bus database**
- [Status normalization](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/busStatus.ts): `lib/busStatus.ts`
- [Live bus map](https://github.com/fotatoe24/busahero-webapp/blob/main/components/RealtimeMap.tsx): `components/RealtimeMap.tsx`
- [Route geometry](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/routes.ts): `lib/routes.ts`

### Fare management

- [Fare settings page](https://github.com/fotatoe24/busahero-webapp/blob/main/app/fares/page.tsx): `app/fares/page.tsx`
- [Fare settings state](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/useFareSettings.ts): `lib/useFareSettings.ts`
- **Fare settings store**
- [Fare matrix calculator](https://github.com/fotatoe24/busahero-webapp/blob/main/components/FareMatrixCalculator.tsx): `components/FareMatrixCalculator.tsx`
- [Fare calculation](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/fareCalculator.ts): `lib/fareCalculator.ts`
- [Route distances](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/routeDistances.ts): `lib/routeDistances.ts`

### Shared services

- [Firebase client](https://github.com/fotatoe24/busahero-webapp/blob/main/lib/firebase.ts): `lib/firebase.ts`

### Other components

- **Fleet operator**

## Connections

- Fleet operator → Sign-in and registration: signs in (evidence: `app/page.tsx`)
- Sign-in and registration → Auth state: calls auth (evidence: `app/page.tsx`)
- Auth state → Registration API: posts registration (evidence: `lib/useAuth.tsx`)
- Registration API → Operator records: creates operator (evidence: `app/api/register/route.ts`)
- Registration API → Session cookies: creates session (evidence: `app/api/register/route.ts`)
- Auth state → Login API: posts credentials (evidence: `lib/useAuth.tsx`)
- Login API → Operator records: checks operator (evidence: `app/api/login/route.ts`)
- Login API → Session cookies: creates session (evidence: `app/api/login/route.ts`)
- Auth state → Terms acceptance: accepts terms (evidence: `lib/useAuth.tsx`)
- Terms acceptance → Session cookies: reads session (evidence: `app/api/accept-terms/route.ts`)
- Terms acceptance → Operator records: updates acceptance (evidence: `app/api/accept-terms/route.ts`)
- Dashboard → Access guard: guards page (evidence: `app/dashboard/page.tsx`)
- Bus information → Access guard: guards page (evidence: `app/bus-info/page.tsx`)
- Access guard → Auth state: checks operator (evidence: `components/AuthGuard.tsx`)
- Terms gate → Auth state: checks acceptance (evidence: `components/TermsGate.tsx`)
- Dashboard → Realtime bus feed: reads buses (evidence: `app/dashboard/page.tsx`)
- Bus information → Realtime bus feed: reads and updates (evidence: `app/bus-info/page.tsx`)
- Realtime bus feed → Firebase client: uses database client (evidence: `lib/useRealtimeBuses.ts`)
- Realtime bus feed → Bus database: subscribes and updates (evidence: `README.md`)
- Realtime bus feed → Status normalization: normalizes status (evidence: `lib/useRealtimeBuses.ts`)
- Dashboard → Live bus map: renders map (evidence: `app/dashboard/page.tsx`)
- Live bus map → Route geometry: uses geometry (evidence: `components/RealtimeMap.tsx`)
- Fare settings page → Fare settings state: loads settings (evidence: `app/fares/page.tsx`)
- Fare settings state → Firebase client: uses database client (evidence: `lib/useFareSettings.ts`)
- Fare settings state → Fare settings store: reads and writes
- Fare settings page → Fare matrix calculator: renders calculator (evidence: `app/fares/page.tsx`)
- Fare matrix calculator → Fare calculation: calculates fares (evidence: `components/FareMatrixCalculator.tsx`)
- Fare matrix calculator → Route distances: uses distances (evidence: `components/FareMatrixCalculator.tsx`)
