# hippomasakib1/tinchaka architecture

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

- Interactive diagram: https://gitdiagram.com/hippomasakib1/tinchaka
- Repository: https://github.com/hippomasakib1/tinchaka

## Overview

TinChaka is a Dhaka ride-pooling platform. Passengers authenticate and submit zoned, seat-counted requests; drivers declare availability, discover same-zone requests, and accept them into capacity-limited pools. Pool transitions update member rides, fares and audit/payment records, which both roles inspect in active-trip and history views. The graph shows the documented two-role journey and the sampled API ownership boundaries. Some web-to-API calls are indicated from the README’s workflow because UI excerpts do not expose those calls; unsampled implementation details are not inferred.

Main entry points: [`tinchaka-api/src/app.ts`](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/app.ts) (Express app), [`tinchaka-api/src/services/pool.service.ts`](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/pool.service.ts) (Pool lifecycle engine), [`tinchaka-api/src/config/db.ts`](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/config/db.ts) (Prisma client), [`tinchaka-web/app/driver/page.tsx`](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/page.tsx) (Driver dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_passengerui["Passenger booking<br/>[RequestForm.tsx]"]
  node_passengerviews["Ride tracking history<br/>[ActiveRide.tsx]"]
  node_driverdash["Driver dashboard<br/>[page.tsx]"]
  node_driverfeed["Pending requests<br/>[PendingList.tsx]"]
  node_driverpoolui["Pool controls"]
  node_driverhistory["Driver history<br/>[DriverHistory.tsx]"]
  node_clientapi["API client<br/>[api.ts]"]
  node_webdomain["Web ride operations<br/>[rides.ts]"]
  node_driverops["Driver API operations<br/>[driver.ts]"]
end

subgraph group_api["API request handling"]
  node_entry["Express app<br/>[app.ts]"]
  node_ridecontroller["Ride request controller"]
  node_poolcontroller["Pool controller<br/>[pool.controller.ts]"]
  node_vehcontroller["Vehicle controller"]
  node_rideroutes["Ride routes"]
  node_poolroutes["Pool routes<br/>[pool.routes.ts]"]
  node_authmiddleware["Auth middleware<br/>[requireAuth.ts]"]
end

subgraph group_domain["Pooling domain"]
  node_ridelogic["Ride request service"]
  node_poollogic["Pool lifecycle engine<br/>[pool.service.ts]"]
  node_fares["Fare calculation<br/>[fare.ts]"]
  node_states["State machine<br/>[stateMachine.ts]"]
  node_zones["Zone rules<br/>[zones.ts]"]
  node_vehicles["Vehicle service<br/>[vehicle.service.ts]"]
end

subgraph group_persistence["Persistence and identity"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_dbclient["Prisma client<br/>[db.ts]"]
  node_database[("PostgreSQL data")]
end

node_passenger(("Passenger"))
node_driver(("Driver"))

node_passenger -->|"books rides"| node_passengerui
node_passengerui -.->|"submits requests"| node_webdomain
node_webdomain -.->|"calls API"| node_clientapi
node_clientapi -.->|"sends HTTP"| node_entry
node_entry -->|"mounts routes"| node_rideroutes
node_rideroutes -->|"authenticates"| node_authmiddleware
node_rideroutes -->|"dispatches"| node_ridecontroller
node_ridecontroller -->|"invokes"| node_ridelogic
node_ridelogic -->|"reads and writes"| node_dbclient
node_dbclient -.->|"persists"| node_database
node_ridelogic -->|"calculates fares"| node_fares
node_ridelogic -->|"checks zones"| node_zones
node_passenger -->|"tracks trips"| node_passengerviews
node_driver -->|"manages availability"| node_driverdash
node_driverdash -->|"renders"| node_driverfeed
node_driverdash -->|"renders"| node_driverpoolui
node_driverdash -->|"renders"| node_driverhistory
node_driverfeed -.->|"loads requests"| node_driverops
node_driverpoolui -.->|"updates pool"| node_driverops
node_driverops -->|"calls API"| node_clientapi
node_driver -->|"accepts and advances"| node_poolroutes
node_entry -->|"mounts routes"| node_poolroutes
node_poolroutes -->|"dispatches"| node_poolcontroller
node_poolcontroller -->|"invokes lifecycle"| node_poollogic
node_poollogic -->|"locks and updates"| node_dbclient
node_poollogic -->|"recomputes fares"| node_fares
node_poollogic -->|"checks transitions"| node_states
node_poollogic -->|"checks pickup zone"| node_zones
node_driver -->|"reviews trips"| node_driverhistory
node_entry -.->|"serves auth routes"| node_auth
node_auth -->|"reads and writes users"| node_dbclient
node_auth -.->|"issues token"| node_clientapi
node_entry -->|"mounts vehicle routes"| node_vehcontroller
node_vehcontroller -->|"invokes"| node_vehicles
node_vehicles -.->|"updates availability"| node_dbclient

click node_passengerui "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/passenger/RequestForm.tsx"
click node_passengerviews "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/passenger/ActiveRide.tsx"
click node_driverdash "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/page.tsx"
click node_driverfeed "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/PendingList.tsx"
click node_driverpoolui "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/ActivePoolPanel.tsx"
click node_driverhistory "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/DriverHistory.tsx"
click node_clientapi "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/api.ts"
click node_webdomain "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/rides.ts"
click node_driverops "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/driver.ts"
click node_entry "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/app.ts"
click node_ridecontroller "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/rideRequest.controller.ts"
click node_poolcontroller "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/pool.controller.ts"
click node_vehcontroller "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/vehicle.controller.ts"
click node_rideroutes "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/routes/rideRequest.routes.ts"
click node_poolroutes "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/routes/pool.routes.ts"
click node_auth "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/auth.service.ts"
click node_ridelogic "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/rideRequest.service.ts"
click node_poollogic "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/pool.service.ts"
click node_fares "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/fare.ts"
click node_states "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/stateMachine.ts"
click node_zones "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/zones.ts"
click node_vehicles "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/vehicle.service.ts"
click node_dbclient "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/config/db.ts"
click node_authmiddleware "https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/middleware/requireAuth.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_passengerui,node_passengerviews,node_driverdash,node_driverfeed,node_driverpoolui,node_driverhistory,node_clientapi,node_webdomain,node_driverops toneBlue
class node_entry,node_ridecontroller,node_poolcontroller,node_vehcontroller,node_rideroutes,node_poolroutes,node_authmiddleware toneAmber
class node_ridelogic,node_poollogic,node_fares,node_states,node_zones,node_vehicles toneMint
class node_auth,node_dbclient,node_database toneRose
class node_passenger,node_driver toneIndigo
```

## Components

### Web experience

- [Passenger booking](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/passenger/RequestForm.tsx): `tinchaka-web/app/passenger/RequestForm.tsx`
- [Ride tracking history](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/passenger/ActiveRide.tsx): `tinchaka-web/app/passenger/ActiveRide.tsx`
- [Driver dashboard](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/page.tsx): `tinchaka-web/app/driver/page.tsx`
- [Pending requests](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/PendingList.tsx): `tinchaka-web/app/driver/PendingList.tsx`
- [Pool controls](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/ActivePoolPanel.tsx): `tinchaka-web/app/driver/ActivePoolPanel.tsx`
- [Driver history](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/app/driver/DriverHistory.tsx): `tinchaka-web/app/driver/DriverHistory.tsx`
- [API client](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/api.ts): `tinchaka-web/lib/api.ts`
- [Web ride operations](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/rides.ts): `tinchaka-web/lib/rides.ts`
- [Driver API operations](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-web/lib/driver.ts): `tinchaka-web/lib/driver.ts`

### API request handling

- [Express app](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/app.ts): `tinchaka-api/src/app.ts`
- [Ride request controller](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/rideRequest.controller.ts): `tinchaka-api/src/controllers/rideRequest.controller.ts`
- [Pool controller](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/pool.controller.ts): `tinchaka-api/src/controllers/pool.controller.ts`
- [Vehicle controller](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/controllers/vehicle.controller.ts): `tinchaka-api/src/controllers/vehicle.controller.ts`
- [Ride routes](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/routes/rideRequest.routes.ts): `tinchaka-api/src/routes/rideRequest.routes.ts`
- [Pool routes](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/routes/pool.routes.ts): `tinchaka-api/src/routes/pool.routes.ts`
- [Auth middleware](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/middleware/requireAuth.ts): `tinchaka-api/src/middleware/requireAuth.ts`

### Pooling domain

- [Ride request service](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/rideRequest.service.ts): `tinchaka-api/src/services/rideRequest.service.ts`
- [Pool lifecycle engine](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/pool.service.ts): `tinchaka-api/src/services/pool.service.ts`
- [Fare calculation](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/fare.ts): `tinchaka-api/src/domain/fare.ts`
- [State machine](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/stateMachine.ts): `tinchaka-api/src/domain/stateMachine.ts`
- [Zone rules](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/domain/zones.ts): `tinchaka-api/src/domain/zones.ts`
- [Vehicle service](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/vehicle.service.ts): `tinchaka-api/src/services/vehicle.service.ts`

### Persistence and identity

- [Authentication](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/services/auth.service.ts): `tinchaka-api/src/services/auth.service.ts`
- [Prisma client](https://github.com/hippomasakib1/tinchaka/blob/release/v1.0.0/tinchaka-api/src/config/db.ts): `tinchaka-api/src/config/db.ts`
- **PostgreSQL data**

### Other components

- **Passenger**
- **Driver**

## Connections

- Passenger → Passenger booking: books rides (evidence: `README.md`)
- Passenger booking → Web ride operations: submits requests
- Web ride operations → API client: calls API (evidence: `tinchaka-web/lib/rides.ts`)
- API client → Express app: sends HTTP
- Express app → Ride routes: mounts routes (evidence: `tinchaka-api/src/app.ts`)
- Ride routes → Auth middleware: authenticates (evidence: `tinchaka-api/src/routes/rideRequest.routes.ts`)
- Ride routes → Ride request controller: dispatches (evidence: `tinchaka-api/src/routes/rideRequest.routes.ts`)
- Ride request controller → Ride request service: invokes (evidence: `tinchaka-api/src/controllers/rideRequest.controller.ts`)
- Ride request service → Prisma client: reads and writes (evidence: `tinchaka-api/src/services/rideRequest.service.ts`)
- Prisma client → PostgreSQL data: persists
- Ride request service → Fare calculation: calculates fares (evidence: `tinchaka-api/src/services/rideRequest.service.ts`)
- Ride request service → Zone rules: checks zones (evidence: `tinchaka-api/src/services/rideRequest.service.ts`)
- Passenger → Ride tracking history: tracks trips (evidence: `README.md`)
- Driver → Driver dashboard: manages availability (evidence: `README.md`)
- Driver dashboard → Pending requests: renders (evidence: `tinchaka-web/app/driver/page.tsx`)
- Driver dashboard → Pool controls: renders (evidence: `tinchaka-web/app/driver/page.tsx`)
- Driver dashboard → Driver history: renders (evidence: `tinchaka-web/app/driver/page.tsx`)
- Pending requests → Driver API operations: loads requests
- Pool controls → Driver API operations: updates pool
- Driver API operations → API client: calls API (evidence: `tinchaka-web/lib/driver.ts`)
- Driver → Pool routes: accepts and advances (evidence: `README.md`)
- Express app → Pool routes: mounts routes (evidence: `tinchaka-api/src/app.ts`)
- Pool routes → Pool controller: dispatches (evidence: `tinchaka-api/src/routes/pool.routes.ts`)
- Pool controller → Pool lifecycle engine: invokes lifecycle (evidence: `tinchaka-api/src/controllers/pool.controller.ts`)
- Pool lifecycle engine → Prisma client: locks and updates (evidence: `tinchaka-api/src/services/pool.service.ts`)
- Pool lifecycle engine → Fare calculation: recomputes fares (evidence: `tinchaka-api/src/services/pool.service.ts`)
- Pool lifecycle engine → State machine: checks transitions (evidence: `tinchaka-api/src/services/pool.service.ts`)
- Pool lifecycle engine → Zone rules: checks pickup zone (evidence: `tinchaka-api/src/services/pool.service.ts`)
- Driver → Driver history: reviews trips (evidence: `README.md`)
- Express app → Authentication: serves auth routes
- Authentication → Prisma client: reads and writes users (evidence: `tinchaka-api/src/services/auth.service.ts`)
- Authentication → API client: issues token
- Express app → Vehicle controller: mounts vehicle routes (evidence: `tinchaka-api/src/app.ts`)
- Vehicle controller → Vehicle service: invokes (evidence: `tinchaka-api/src/controllers/vehicle.controller.ts`)
- Vehicle service → Prisma client: updates availability
