# arham-apon/tesla-lagbo architecture

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

- Interactive diagram: https://gitdiagram.com/arham-apon/tesla-lagbo
- Repository: https://github.com/arham-apon/tesla-lagbo

## Overview

Dhaka Tesla Pool is a ride-pooling MVP with a documented six-service backend and a Next.js interface. The backend workflow is gateway-mediated identity and ride requests, trip coordination with matching and fare services, then event-driven settlement and rider updates. The README also notes that the frontend runs its own in-browser dispatch simulation rather than using the backend. Backend service calls and event paths below follow the README architecture; sampled source confirms service startup and shared event behavior, but not every service-to-service call.

Main entry points: [`services/trip/app/routers/passenger.py`](https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/routers/passenger.py) (Ride API), [`services/fare/app/main.py`](https://github.com/arham-apon/tesla-lagbo/blob/master/services/fare/app/main.py) (Fare and wallet), [`services/matching/app/routers/internal.py`](https://github.com/arham-apon/tesla-lagbo/blob/master/services/matching/app/routers/internal.py) (Driver matching), [`services/gateway/app/main.py`](https://github.com/arham-apon/tesla-lagbo/blob/master/services/gateway/app/main.py) (API gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend simulation"]
  node_frontend["Passenger and driver UI"]
  node_sim_engine["Dispatch simulation<br/>[engine.ts]"]
  node_sim_world["Simulation world<br/>[world.ts]"]
end

subgraph group_edge["API edge"]
  node_gateway["API gateway<br/>[main.py]"]
end

subgraph group_services["Ride services"]
  node_identity["Identity and drivers<br/>[auth.py]"]
  node_trip_api["Ride API<br/>[passenger.py]"]
  node_trip_lifecycle["Ride lifecycle<br/>[lifecycle.py]"]
  node_trip_pooling["Pool coordination<br/>[pooling.py]"]
  node_trip_history["Ride snapshots<br/>[snapshots.py]"]
  node_matching["Driver matching<br/>[internal.py]"]
  node_fare["Fare and wallet<br/>[main.py]"]
  node_settlement["Fare settlement<br/>[settlement.py]"]
  node_notification["Notifications<br/>[main.py]"]
end

subgraph group_messaging["Events and state"]
  node_broker["RabbitMQ events"]
  node_redis[("Redis state")]
  node_identity_db[("Identity database")]
  node_matching_db[("Matching database")]
  node_trip_db[("Trip database")]
  node_fare_db[("Fare database")]
  node_notification_db[("Notification database")]
end

subgraph group_shared["Shared runtime"]
  node_common["Shared auth, DB, HTTP, events"]
end

node_browser(("Browser"))

node_browser -->|"uses"| node_frontend
node_frontend -->|"runs simulation"| node_sim_engine
node_sim_engine -->|"uses world"| node_sim_world
node_frontend -->|"REST requests"| node_gateway
node_frontend -->|"opens WebSocket"| node_notification
node_gateway -->|"routes requests"| node_identity
node_gateway -->|"routes requests"| node_matching
node_gateway -->|"routes requests"| node_trip_api
node_gateway -->|"routes requests"| node_fare
node_gateway -->|"routes requests"| node_notification
node_trip_api -->|"uses lifecycle"| node_trip_lifecycle
node_trip_lifecycle -->|"uses pooling"| node_trip_pooling
node_trip_lifecycle -->|"uses snapshots"| node_trip_history
node_trip_api -->|"requests quotes"| node_fare
node_trip_api -->|"evaluates drivers"| node_matching
node_fare -->|"requests distance"| node_matching
node_identity -->|"checks live pools"| node_trip_api
node_identity -->|"publishes events"| node_broker
node_trip_api -->|"publishes events"| node_broker
node_fare -->|"publishes events"| node_broker
node_broker -->|"delivers events"| node_trip_api
node_broker -->|"delivers events"| node_matching
node_broker -->|"delivers events"| node_fare
node_broker -->|"delivers events"| node_notification
node_matching -->|"publishes locations"| node_redis
node_redis -->|"relays locations"| node_notification
node_identity -.->|"reads and writes"| node_identity_db
node_matching -.->|"reads and writes"| node_matching_db
node_trip_api -.->|"reads and writes"| node_trip_db
node_fare -.->|"reads and writes"| node_fare_db
node_notification -.->|"reads and writes"| node_notification_db
node_identity -->|"uses shared runtime"| node_common
node_trip_api -->|"uses shared runtime"| node_common
node_fare -->|"uses shared runtime"| node_common
node_notification -->|"uses shared runtime"| node_common
node_matching -->|"uses shared runtime"| node_common

click node_frontend "https://github.com/arham-apon/tesla-lagbo/tree/master/frontend/src/components"
click node_sim_engine "https://github.com/arham-apon/tesla-lagbo/blob/master/frontend/src/sim/engine.ts"
click node_sim_world "https://github.com/arham-apon/tesla-lagbo/blob/master/frontend/src/sim/world.ts"
click node_gateway "https://github.com/arham-apon/tesla-lagbo/blob/master/services/gateway/app/main.py"
click node_identity "https://github.com/arham-apon/tesla-lagbo/blob/master/services/identity/app/routers/auth.py"
click node_trip_api "https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/routers/passenger.py"
click node_trip_lifecycle "https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/lifecycle.py"
click node_trip_pooling "https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/pooling.py"
click node_trip_history "https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/snapshots.py"
click node_matching "https://github.com/arham-apon/tesla-lagbo/blob/master/services/matching/app/routers/internal.py"
click node_fare "https://github.com/arham-apon/tesla-lagbo/blob/master/services/fare/app/main.py"
click node_settlement "https://github.com/arham-apon/tesla-lagbo/blob/master/services/fare/app/settlement.py"
click node_notification "https://github.com/arham-apon/tesla-lagbo/blob/master/services/notification/app/main.py"
click node_common "https://github.com/arham-apon/tesla-lagbo/tree/master/libs/common/tesla_common"

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_frontend,node_sim_engine,node_sim_world,node_browser toneBlue
class node_gateway toneAmber
class node_identity,node_trip_api,node_trip_lifecycle,node_trip_pooling,node_trip_history,node_matching,node_fare,node_settlement,node_notification toneMint
class node_broker,node_redis,node_identity_db,node_matching_db,node_trip_db,node_fare_db,node_notification_db toneRose
class node_common toneIndigo
```

## Components

### Frontend simulation

- [Passenger and driver UI](https://github.com/arham-apon/tesla-lagbo/tree/master/frontend/src/components): `frontend/src/components`
- [Dispatch simulation](https://github.com/arham-apon/tesla-lagbo/blob/master/frontend/src/sim/engine.ts): `frontend/src/sim/engine.ts`
- [Simulation world](https://github.com/arham-apon/tesla-lagbo/blob/master/frontend/src/sim/world.ts): `frontend/src/sim/world.ts`

### API edge

- [API gateway](https://github.com/arham-apon/tesla-lagbo/blob/master/services/gateway/app/main.py): `services/gateway/app/main.py`

### Ride services

- [Identity and drivers](https://github.com/arham-apon/tesla-lagbo/blob/master/services/identity/app/routers/auth.py): `services/identity/app/routers/auth.py`
- [Ride API](https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/routers/passenger.py): `services/trip/app/routers/passenger.py`
- [Ride lifecycle](https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/lifecycle.py): `services/trip/app/lifecycle.py`
- [Pool coordination](https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/pooling.py): `services/trip/app/pooling.py`
- [Ride snapshots](https://github.com/arham-apon/tesla-lagbo/blob/master/services/trip/app/snapshots.py): `services/trip/app/snapshots.py`
- [Driver matching](https://github.com/arham-apon/tesla-lagbo/blob/master/services/matching/app/routers/internal.py): `services/matching/app/routers/internal.py`
- [Fare and wallet](https://github.com/arham-apon/tesla-lagbo/blob/master/services/fare/app/main.py): `services/fare/app/main.py`
- [Fare settlement](https://github.com/arham-apon/tesla-lagbo/blob/master/services/fare/app/settlement.py): `services/fare/app/settlement.py`
- [Notifications](https://github.com/arham-apon/tesla-lagbo/blob/master/services/notification/app/main.py): `services/notification/app/main.py`

### Events and state

- **RabbitMQ events**
- **Redis state**
- **Identity database**
- **Matching database**
- **Trip database**
- **Fare database**
- **Notification database**

### Shared runtime

- [Shared auth, DB, HTTP, events](https://github.com/arham-apon/tesla-lagbo/tree/master/libs/common/tesla_common): `libs/common/tesla_common`

### Other components

- **Browser**

## Connections

- Browser → Passenger and driver UI: uses
- Passenger and driver UI → Dispatch simulation: runs simulation
- Dispatch simulation → Simulation world: uses world (evidence: `frontend/src/sim/engine.ts`)
- Passenger and driver UI → API gateway: REST requests
- Passenger and driver UI → Notifications: opens WebSocket
- API gateway → Identity and drivers: routes requests
- API gateway → Driver matching: routes requests
- API gateway → Ride API: routes requests
- API gateway → Fare and wallet: routes requests
- API gateway → Notifications: routes requests
- Ride API → Ride lifecycle: uses lifecycle
- Ride lifecycle → Pool coordination: uses pooling (evidence: `services/trip/app/lifecycle.py`)
- Ride lifecycle → Ride snapshots: uses snapshots (evidence: `services/trip/app/lifecycle.py`)
- Ride API → Fare and wallet: requests quotes
- Ride API → Driver matching: evaluates drivers
- Fare and wallet → Driver matching: requests distance
- Identity and drivers → Ride API: checks live pools
- Identity and drivers → RabbitMQ events: publishes events
- Ride API → RabbitMQ events: publishes events
- Fare and wallet → RabbitMQ events: publishes events
- RabbitMQ events → Ride API: delivers events
- RabbitMQ events → Driver matching: delivers events
- RabbitMQ events → Fare and wallet: delivers events
- RabbitMQ events → Notifications: delivers events
- Driver matching → Redis state: publishes locations
- Redis state → Notifications: relays locations
- Identity and drivers → Identity database: reads and writes
- Driver matching → Matching database: reads and writes
- Ride API → Trip database: reads and writes
- Fare and wallet → Fare database: reads and writes
- Notifications → Notification database: reads and writes
- Identity and drivers → Shared auth, DB, HTTP, events: uses shared runtime (evidence: `services/identity/app/routers/auth.py`)
- Ride API → Shared auth, DB, HTTP, events: uses shared runtime (evidence: `services/trip/app/main.py`)
- Fare and wallet → Shared auth, DB, HTTP, events: uses shared runtime (evidence: `services/fare/app/main.py`)
- Notifications → Shared auth, DB, HTTP, events: uses shared runtime (evidence: `services/notification/app/main.py`)
- Driver matching → Shared auth, DB, HTTP, events: uses shared runtime (evidence: `services/matching/app/main.py`)