# pranjal1-1/himachal-transit architecture

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

- Interactive diagram: https://gitdiagram.com/pranjal1-1/himachal-transit
- Repository: https://github.com/pranjal1-1/himachal-transit

## Overview

Himachal Transit is a transit operations system with an admin web console, backend API, and mobile client. The evidenced admin workflow is login or token entry, then managing fleet, routes, stops, and assignments through API requests. The repository also documents passenger and driver apps, GPS tracking, real-time updates, and ETA functionality. Mobile and ETA implementation details were not sampled, so those capabilities are represented as subsystems without asserted internal wiring; dashed edges mark unverified links.

Main entry points: [`ht_development_pack_v2/himachal_transit/backend/src/index.ts`](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/index.ts) (HTTP API), [`ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts`](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts) (Realtime Server), [`ht_development_pack_v2/himachal_transit/admin/lib/api.ts`](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/lib/api.ts) (Admin API Client), [`ht_development_pack_v2/himachal_transit/backend/src/db.ts`](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db.ts) (Database Selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin Console"]
  node_admin_login["Admin Login<br/>[page.tsx]"]
  node_admin_crud["Fleet And Routes<br/>[page.tsx]"]
  node_admin_stops["Stop Management<br/>[page.tsx]"]
  node_admin_assignments["Assignments<br/>[page.tsx]"]
  node_admin_api["Admin API Client<br/>[api.ts]"]
end

subgraph group_backend["Backend Services"]
  node_backend_api["HTTP API<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_data["Persistence"]
  node_db_layer["Database Selector<br/>[db.ts]"]
  node_file_db[("File Database<br/>[db_file.ts]")]
  node_postgres_db[("Postgres Database<br/>[db_pg.ts]")]
end

subgraph group_mobile["Mobile Client"]
  node_driver_app["Driver App"]
  node_passenger_app["Passenger App"]
  node_mobile_auth["Mobile Authentication"]
  node_maps["Maps And Location"]
end

subgraph group_tracking["Transit Tracking"]
  node_realtime_server["Realtime Server<br/>[server.ts]"]
  node_realtime_events["Realtime Events<br/>[events.ts]"]
  node_eta_engine["ETA Engine"]
end

node_admin_user(("Admin User"))
node_transit_rider(("Transit Rider"))
node_driver(("Driver"))

node_admin_user -->|"signs in"| node_admin_login
node_admin_login -->|"requests login"| node_admin_api
node_admin_crud -->|"fetches resources"| node_admin_api
node_admin_stops -->|"fetches stops"| node_admin_api
node_admin_assignments -->|"fetches assignments"| node_admin_api
node_admin_api -->|"sends HTTP requests"| node_backend_api
node_backend_api -->|"authenticates users"| node_auth
node_backend_api -->|"reads and writes"| node_db_layer
node_db_layer -->|"selects file store"| node_file_db
node_db_layer -->|"selects Postgres"| node_postgres_db
node_backend_api -->|"initializes realtime"| node_realtime_server
node_realtime_server -->|"creates events"| node_realtime_events
node_realtime_server -->|"checks active trips"| node_db_layer
node_driver -.->|"uses"| node_driver_app
node_transit_rider -.->|"uses"| node_passenger_app
node_mobile_auth -.->|"authenticates"| node_backend_api
node_driver_app -.->|"uses location"| node_maps
node_driver_app -.->|"sends GPS updates"| node_realtime_server
node_passenger_app -.->|"receives trip updates"| node_realtime_server
node_eta_engine -.->|"provides ETAs"| node_passenger_app

click node_admin_login "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/login/page.tsx"
click node_admin_crud "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/buses/page.tsx"
click node_admin_stops "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/stops/page.tsx"
click node_admin_assignments "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/assignments/page.tsx"
click node_admin_api "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/lib/api.ts"
click node_backend_api "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/index.ts"
click node_auth "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/auth.ts"
click node_db_layer "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db.ts"
click node_file_db "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db_file.ts"
click node_postgres_db "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db_pg.ts"
click node_driver_app "https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/driver"
click node_passenger_app "https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/passenger"
click node_mobile_auth "https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/auth"
click node_maps "https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/maps"
click node_realtime_server "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts"
click node_realtime_events "https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/realtime/events.ts"
click node_eta_engine "https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/backend/src"

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_admin_login,node_admin_crud,node_admin_stops,node_admin_assignments,node_admin_api,node_admin_user toneBlue
class node_backend_api,node_auth toneAmber
class node_db_layer,node_file_db,node_postgres_db toneMint
class node_driver_app,node_passenger_app,node_mobile_auth,node_maps toneRose
class node_realtime_server,node_realtime_events,node_eta_engine,node_transit_rider,node_driver toneIndigo
```

## Components

### Admin Console

- [Admin Login](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/login/page.tsx): `ht_development_pack_v2/himachal_transit/admin/app/login/page.tsx`
- [Fleet And Routes](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/buses/page.tsx): `ht_development_pack_v2/himachal_transit/admin/app/buses/page.tsx`
- [Stop Management](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/stops/page.tsx): `ht_development_pack_v2/himachal_transit/admin/app/stops/page.tsx`
- [Assignments](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/app/assignments/page.tsx): `ht_development_pack_v2/himachal_transit/admin/app/assignments/page.tsx`
- [Admin API Client](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/admin/lib/api.ts): `ht_development_pack_v2/himachal_transit/admin/lib/api.ts`

### Backend Services

- [HTTP API](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/index.ts): `ht_development_pack_v2/himachal_transit/backend/src/index.ts`
- [Authentication](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/auth.ts): `ht_development_pack_v2/himachal_transit/backend/src/auth.ts`

### Persistence

- [Database Selector](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db.ts): `ht_development_pack_v2/himachal_transit/backend/src/db.ts`
- [File Database](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db_file.ts): `ht_development_pack_v2/himachal_transit/backend/src/db_file.ts`
- [Postgres Database](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/db_pg.ts): `ht_development_pack_v2/himachal_transit/backend/src/db_pg.ts`

### Mobile Client

- [Driver App](https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/driver): `ht_development_pack_v2/himachal_transit/mobile/lib/features/driver`
- [Passenger App](https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/passenger): `ht_development_pack_v2/himachal_transit/mobile/lib/features/passenger`
- [Mobile Authentication](https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/auth): `ht_development_pack_v2/himachal_transit/mobile/lib/features/auth`
- [Maps And Location](https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/mobile/lib/features/maps): `ht_development_pack_v2/himachal_transit/mobile/lib/features/maps`

### Transit Tracking

- [Realtime Server](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts): `ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts`
- [Realtime Events](https://github.com/pranjal1-1/himachal-transit/blob/master/ht_development_pack_v2/himachal_transit/backend/src/realtime/events.ts): `ht_development_pack_v2/himachal_transit/backend/src/realtime/events.ts`
- [ETA Engine](https://github.com/pranjal1-1/himachal-transit/tree/master/ht_development_pack_v2/himachal_transit/backend/src): `ht_development_pack_v2/himachal_transit/backend/src`

### Other components

- **Admin User**
- **Transit Rider**
- **Driver**

## Connections

- Admin User → Admin Login: signs in (evidence: `ht_development_pack_v2/himachal_transit/admin/app/login/page.tsx`)
- Admin Login → Admin API Client: requests login (evidence: `ht_development_pack_v2/himachal_transit/admin/app/login/page.tsx`)
- Fleet And Routes → Admin API Client: fetches resources (evidence: `ht_development_pack_v2/himachal_transit/admin/app/buses/page.tsx`)
- Stop Management → Admin API Client: fetches stops (evidence: `ht_development_pack_v2/himachal_transit/admin/app/stops/page.tsx`)
- Assignments → Admin API Client: fetches assignments (evidence: `ht_development_pack_v2/himachal_transit/admin/app/assignments/page.tsx`)
- Admin API Client → HTTP API: sends HTTP requests (evidence: `ht_development_pack_v2/himachal_transit/admin/lib/api.ts`)
- HTTP API → Authentication: authenticates users (evidence: `ht_development_pack_v2/himachal_transit/backend/src/index.ts`)
- HTTP API → Database Selector: reads and writes (evidence: `ht_development_pack_v2/himachal_transit/backend/src/index.ts`)
- Database Selector → File Database: selects file store (evidence: `ht_development_pack_v2/himachal_transit/backend/src/db.ts`)
- Database Selector → Postgres Database: selects Postgres (evidence: `ht_development_pack_v2/himachal_transit/backend/src/db.ts`)
- HTTP API → Realtime Server: initializes realtime (evidence: `ht_development_pack_v2/himachal_transit/backend/src/index.ts`)
- Realtime Server → Realtime Events: creates events (evidence: `ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts`)
- Realtime Server → Database Selector: checks active trips (evidence: `ht_development_pack_v2/himachal_transit/backend/src/realtime/server.ts`)
- Driver → Driver App: uses
- Transit Rider → Passenger App: uses
- Mobile Authentication → HTTP API: authenticates
- Driver App → Maps And Location: uses location
- Driver App → Realtime Server: sends GPS updates
- Passenger App → Realtime Server: receives trip updates
- ETA Engine → Passenger App: provides ETAs
