# karaagexc/traintracks architecture

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

- Interactive diagram: https://gitdiagram.com/karaagexc/traintracks
- Repository: https://github.com/karaagexc/traintracks

## Overview

TrainTracks is a map-first Metro Manila rail companion: riders plan transfer-aware journeys, follow progress with location assistance, and consult fares, train estimates, and community conditions. Its domain layer supplies routing, journey tracking, simulation, and prediction logic; the app also exposes public APIs and account-backed trip history. The graph emphasizes documented product capabilities and sampled call relationships. Some UI and API wiring is inferred only from route/module names and the README; uncertain links are omitted.

Main entry points: [`src/components/MainApp.tsx`](https://github.com/karaagexc/traintracks/blob/main/src/components/MainApp.tsx) (Map and trip UI), [`src/hooks/useJourneyRuntime.ts`](https://github.com/karaagexc/traintracks/blob/main/src/hooks/useJourneyRuntime.ts) (Journey runtime), [`src/domain/routing/index.ts`](https://github.com/karaagexc/traintracks/blob/main/src/domain/routing/index.ts) (Route builder), [`src/domain/journey/engine.ts`](https://github.com/karaagexc/traintracks/blob/main/src/domain/journey/engine.ts) (Journey engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Rider experience"]
  node_main["Map and trip UI<br/>[MainApp.tsx]"]
  node_map["Map explorer<br/>[MapExplorer.tsx]"]
  node_line["Line explorer<br/>[LineExplorer.tsx]"]
  node_tripui["Trip progress<br/>[TripProgress.tsx]"]
  node_fare["Fare selection<br/>[FareSelector.tsx]"]
end

subgraph group_journey["Journey domain"]
  node_journeyhook["Journey runtime"]
  node_journeyengine["Journey engine<br/>[engine.ts]"]
  node_routing["Route builder<br/>[index.ts]"]
  node_network["Rail network data<br/>[stations.ts]"]
  node_gps["Location runtime"]
  node_location["GPS and proximity"]
  node_simulation["Train simulation<br/>[engine.ts]"]
end

subgraph group_signals["Transit signals"]
  node_presence["Train presence<br/>[trainPresence.ts]"]
  node_predictions["Train estimates<br/>[engine.ts]"]
  node_congestion["Crowd forecasting<br/>[engine.ts]"]
  node_crowdapi["Community reports<br/>[service.ts]"]
  node_incidentapi["Incident endpoints<br/>[route.ts]"]
  node_predictionapi["Prediction endpoints<br/>[route.ts]"]
end

subgraph group_services["Accounts and APIs"]
  node_account["Auth and profile<br/>[useAuth.ts]"]
  node_tripsapi["Trip history API<br/>[route.ts]"]
  node_publicapi["Public congestion API<br/>[route.ts]"]
end

subgraph group_offline["Offline runtime"]
  node_offlinehook["Offline runtime"]
  node_offlinequeue[("Offline storage<br/>[indexedDb.ts]")]
end

node_rider(("Rider"))
node_supabase[("Supabase")]
node_apiuser(("API consumer"))

node_rider -->|"uses"| node_main
node_main -->|"renders"| node_map
node_main -->|"explores"| node_line
node_main -->|"shows progress"| node_tripui
node_main -->|"selects fare"| node_fare
node_main -->|"tracks trip"| node_journeyhook
node_journeyhook -->|"updates journey"| node_journeyengine
node_journeyengine -->|"builds route"| node_routing
node_routing -->|"reads stations"| node_network
node_gps -->|"checks proximity"| node_location
node_journeyhook -->|"uses location"| node_gps
node_simulation -->|"builds simulated route"| node_routing
node_journeyhook -.->|"simulates trip"| node_simulation
node_main -->|"shows train signals"| node_presence
node_predictionapi -->|"computes estimates"| node_predictions
node_publicapi -->|"computes crowd level"| node_congestion
node_apiuser -->|"requests data"| node_publicapi
node_rider -->|"reports conditions"| node_incidentapi
node_incidentapi -->|"handles reports"| node_crowdapi
node_crowdapi -->|"persists signals"| node_supabase
node_account -->|"authenticates"| node_supabase
node_tripsapi -->|"reads and writes trips"| node_supabase
node_offlinehook -->|"stores offline data"| node_offlinequeue

click node_main "https://github.com/karaagexc/traintracks/blob/main/src/components/MainApp.tsx"
click node_map "https://github.com/karaagexc/traintracks/blob/main/src/components/MapExplorer.tsx"
click node_line "https://github.com/karaagexc/traintracks/blob/main/src/components/LineExplorer.tsx"
click node_tripui "https://github.com/karaagexc/traintracks/blob/main/src/components/TripProgress.tsx"
click node_fare "https://github.com/karaagexc/traintracks/blob/main/src/components/FareSelector.tsx"
click node_journeyhook "https://github.com/karaagexc/traintracks/blob/main/src/hooks/useJourneyRuntime.ts"
click node_journeyengine "https://github.com/karaagexc/traintracks/blob/main/src/domain/journey/engine.ts"
click node_routing "https://github.com/karaagexc/traintracks/blob/main/src/domain/routing/index.ts"
click node_network "https://github.com/karaagexc/traintracks/blob/main/src/data/stations.ts"
click node_gps "https://github.com/karaagexc/traintracks/blob/main/src/hooks/useSmartLocation.ts"
click node_location "https://github.com/karaagexc/traintracks/blob/main/src/domain/location/stationProximity.ts"
click node_simulation "https://github.com/karaagexc/traintracks/blob/main/src/domain/simulation/engine.ts"
click node_presence "https://github.com/karaagexc/traintracks/blob/main/src/domain/trainPresence.ts"
click node_predictions "https://github.com/karaagexc/traintracks/blob/main/src/domain/predictions/engine.ts"
click node_congestion "https://github.com/karaagexc/traintracks/blob/main/src/domain/congestion/engine.ts"
click node_crowdapi "https://github.com/karaagexc/traintracks/blob/main/src/domain/crowd/service.ts"
click node_incidentapi "https://github.com/karaagexc/traintracks/blob/main/src/app/api/incidents/route.ts"
click node_predictionapi "https://github.com/karaagexc/traintracks/blob/main/src/app/api/predictions/route.ts"
click node_account "https://github.com/karaagexc/traintracks/blob/main/src/hooks/useAuth.ts"
click node_tripsapi "https://github.com/karaagexc/traintracks/blob/main/src/app/api/trips/route.ts"
click node_publicapi "https://github.com/karaagexc/traintracks/blob/main/src/app/api/public/congestion/route.ts"
click node_offlinehook "https://github.com/karaagexc/traintracks/blob/main/src/hooks/useOfflineRuntime.ts"
click node_offlinequeue "https://github.com/karaagexc/traintracks/blob/main/src/domain/offline/indexedDb.ts"

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_main,node_map,node_line,node_tripui,node_fare toneBlue
class node_journeyhook,node_journeyengine,node_routing,node_network,node_gps,node_location,node_simulation,node_supabase toneAmber
class node_presence,node_predictions,node_congestion,node_crowdapi,node_incidentapi,node_predictionapi,node_apiuser toneMint
class node_account,node_tripsapi,node_publicapi toneRose
class node_offlinehook,node_offlinequeue,node_rider toneIndigo
```

## Components

### Rider experience

- [Map and trip UI](https://github.com/karaagexc/traintracks/blob/main/src/components/MainApp.tsx): `src/components/MainApp.tsx`
- [Map explorer](https://github.com/karaagexc/traintracks/blob/main/src/components/MapExplorer.tsx): `src/components/MapExplorer.tsx`
- [Line explorer](https://github.com/karaagexc/traintracks/blob/main/src/components/LineExplorer.tsx): `src/components/LineExplorer.tsx`
- [Trip progress](https://github.com/karaagexc/traintracks/blob/main/src/components/TripProgress.tsx): `src/components/TripProgress.tsx`
- [Fare selection](https://github.com/karaagexc/traintracks/blob/main/src/components/FareSelector.tsx): `src/components/FareSelector.tsx`

### Journey domain

- [Journey runtime](https://github.com/karaagexc/traintracks/blob/main/src/hooks/useJourneyRuntime.ts): `src/hooks/useJourneyRuntime.ts`
- [Journey engine](https://github.com/karaagexc/traintracks/blob/main/src/domain/journey/engine.ts): `src/domain/journey/engine.ts`
- [Route builder](https://github.com/karaagexc/traintracks/blob/main/src/domain/routing/index.ts): `src/domain/routing/index.ts`
- [Rail network data](https://github.com/karaagexc/traintracks/blob/main/src/data/stations.ts): `src/data/stations.ts`
- [Location runtime](https://github.com/karaagexc/traintracks/blob/main/src/hooks/useSmartLocation.ts): `src/hooks/useSmartLocation.ts`
- [GPS and proximity](https://github.com/karaagexc/traintracks/blob/main/src/domain/location/stationProximity.ts): `src/domain/location/stationProximity.ts`
- [Train simulation](https://github.com/karaagexc/traintracks/blob/main/src/domain/simulation/engine.ts): `src/domain/simulation/engine.ts`

### Transit signals

- [Train presence](https://github.com/karaagexc/traintracks/blob/main/src/domain/trainPresence.ts): `src/domain/trainPresence.ts`
- [Train estimates](https://github.com/karaagexc/traintracks/blob/main/src/domain/predictions/engine.ts): `src/domain/predictions/engine.ts`
- [Crowd forecasting](https://github.com/karaagexc/traintracks/blob/main/src/domain/congestion/engine.ts): `src/domain/congestion/engine.ts`
- [Community reports](https://github.com/karaagexc/traintracks/blob/main/src/domain/crowd/service.ts): `src/domain/crowd/service.ts`
- [Incident endpoints](https://github.com/karaagexc/traintracks/blob/main/src/app/api/incidents/route.ts): `src/app/api/incidents/route.ts`
- [Prediction endpoints](https://github.com/karaagexc/traintracks/blob/main/src/app/api/predictions/route.ts): `src/app/api/predictions/route.ts`

### Accounts and APIs

- [Auth and profile](https://github.com/karaagexc/traintracks/blob/main/src/hooks/useAuth.ts): `src/hooks/useAuth.ts`
- [Trip history API](https://github.com/karaagexc/traintracks/blob/main/src/app/api/trips/route.ts): `src/app/api/trips/route.ts`
- [Public congestion API](https://github.com/karaagexc/traintracks/blob/main/src/app/api/public/congestion/route.ts): `src/app/api/public/congestion/route.ts`

### Offline runtime

- [Offline runtime](https://github.com/karaagexc/traintracks/blob/main/src/hooks/useOfflineRuntime.ts): `src/hooks/useOfflineRuntime.ts`
- [Offline storage](https://github.com/karaagexc/traintracks/blob/main/src/domain/offline/indexedDb.ts): `src/domain/offline/indexedDb.ts`

### Other components

- **Rider**
- **Supabase**
- **API consumer**

## Connections

- Rider → Map and trip UI: uses
- Map and trip UI → Map explorer: renders
- Map and trip UI → Line explorer: explores
- Map and trip UI → Trip progress: shows progress
- Map and trip UI → Fare selection: selects fare
- Map and trip UI → Journey runtime: tracks trip
- Journey runtime → Journey engine: updates journey
- Journey engine → Route builder: builds route
- Route builder → Rail network data: reads stations
- Location runtime → GPS and proximity: checks proximity
- Journey runtime → Location runtime: uses location
- Train simulation → Route builder: builds simulated route
- Journey runtime → Train simulation: simulates trip
- Map and trip UI → Train presence: shows train signals
- Prediction endpoints → Train estimates: computes estimates
- Public congestion API → Crowd forecasting: computes crowd level
- API consumer → Public congestion API: requests data
- Rider → Incident endpoints: reports conditions
- Incident endpoints → Community reports: handles reports
- Community reports → Supabase: persists signals
- Auth and profile → Supabase: authenticates
- Trip history API → Supabase: reads and writes trips
- Offline runtime → Offline storage: stores offline data