# aime-loic/book_it architecture

> Architecture diagram of the GitHub repository aime-loic/book_it, 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/aime-loic/book_it
- Repository: https://github.com/aime-loic/book_it

## Overview

BookIt is a Rwanda bus-ticketing and operations platform. Passengers search routes, reserve seats, pay, and use tickets for boarding; operators manage services, while drivers handle trips and ticket validation. The graph emphasizes the documented product workflows and the sampled backend entry points. Some route and controller implementations were not sampled, so their internal links are omitted; README-described capabilities remain represented at the API boundary.

Main entry points: [`src/services/ticket.service.js`](https://github.com/aime-loic/book_it/blob/main/src/services/ticket.service.js) (Reservations and payments), [`src/services/scheduler.service.js`](https://github.com/aime-loic/book_it/blob/main/src/services/scheduler.service.js) (Trip and retention jobs), [`src/app.js`](https://github.com/aime-loic/book_it/blob/main/src/app.js) (Express API), [`src/routes/driver.routes.js`](https://github.com/aime-loic/book_it/blob/main/src/routes/driver.routes.js) (Driver endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["API runtime"]
  node_api["Express API<br/>[app.js]"]
  node_ticket_routes["Ticket endpoints<br/>[ticket.routes.js]"]
  node_driver_routes["Driver endpoints<br/>[driver.routes.js]"]
end

subgraph group_booking["Passenger booking"]
  node_ticket_controller["Ticket handlers"]
  node_ticket_service["Reservations and payments<br/>[ticket.service.js]"]
  node_ticket_data[("Ticket records<br/>[ticket.js]")]
end

subgraph group_operations["Fleet operations"]
  node_route_management["Routes and stops<br/>[route.service.js]"]
  node_fleet_management["Buses and drivers<br/>[driver.service.js]"]
  node_driver_controller["Driver handlers"]
end

subgraph group_identity["Identity and boarding"]
  node_travel_cards["Travel-card validation"]
  node_rfid_cards["RFID registration"]
  node_identity_service["Authentication<br/>[auth.service.js]"]
end

subgraph group_platform["Messaging and scheduling"]
  node_sequelize["Database connection<br/>[sequelize.js]"]
  node_notifications["Notifications"]
  node_push_service["Push delivery<br/>[fcm.service.js]"]
  node_promo_service["Promo codes<br/>[promo.service.js]"]
  node_scheduler_routes["Scheduled-job endpoint<br/>[internal.routes.js]"]
  node_scheduler_service["Trip and retention jobs"]
end

node_passenger(("Passenger"))
node_operator(("Bus operator"))
node_driver(("Driver"))
node_flutterwave["Flutterwave"]

node_passenger -->|"searches and books"| node_api
node_operator -->|"manages services"| node_api
node_driver -->|"handles trips"| node_api
node_api -->|"mounts endpoints"| node_ticket_routes
node_api -->|"mounts endpoints"| node_driver_routes
node_ticket_routes -->|"dispatches requests"| node_ticket_controller
node_driver_routes -->|"dispatches requests"| node_driver_controller
node_driver_routes -->|"dispatches validation"| node_travel_cards
node_ticket_controller -->|"calls booking logic"| node_ticket_service
node_driver_controller -->|"uses ticket logic"| node_ticket_service
node_ticket_service -->|"reads and writes"| node_ticket_data
node_ticket_service -->|"creates notices"| node_notifications
node_ticket_service -->|"initiates and checks charges"| node_flutterwave
node_driver -->|"validates boarding cards"| node_travel_cards
node_passenger -->|"registers card UID"| node_rfid_cards
node_operator -->|"manages routes"| node_route_management
node_operator -->|"manages fleet"| node_fleet_management
node_ticket_service -->|"uses database models"| node_sequelize
node_notifications -->|"delegates push delivery"| node_push_service
node_scheduler_routes -->|"runs scheduled jobs"| node_scheduler_service
node_scheduler_service -->|"creates notices"| node_notifications
node_scheduler_service -->|"generates loyalty offers"| node_promo_service
node_scheduler_service -->|"checks payment status"| node_ticket_service
node_scheduler_service -->|"reads ticket state"| node_ticket_data

click node_api "https://github.com/aime-loic/book_it/blob/main/src/app.js"
click node_ticket_routes "https://github.com/aime-loic/book_it/blob/main/src/routes/ticket.routes.js"
click node_driver_routes "https://github.com/aime-loic/book_it/blob/main/src/routes/driver.routes.js"
click node_ticket_controller "https://github.com/aime-loic/book_it/blob/main/src/controllers/ticket.controller.js"
click node_ticket_service "https://github.com/aime-loic/book_it/blob/main/src/services/ticket.service.js"
click node_ticket_data "https://github.com/aime-loic/book_it/blob/main/src/database/models/ticket.js"
click node_route_management "https://github.com/aime-loic/book_it/blob/main/src/services/route.service.js"
click node_fleet_management "https://github.com/aime-loic/book_it/blob/main/src/services/driver.service.js"
click node_driver_controller "https://github.com/aime-loic/book_it/blob/main/src/controllers/driver.controller.js"
click node_travel_cards "https://github.com/aime-loic/book_it/blob/main/src/controllers/travel-card.controller.js"
click node_rfid_cards "https://github.com/aime-loic/book_it/blob/main/src/controllers/rfid-card.controller.js"
click node_identity_service "https://github.com/aime-loic/book_it/blob/main/src/services/auth.service.js"
click node_sequelize "https://github.com/aime-loic/book_it/blob/main/src/config/sequelize.js"
click node_notifications "https://github.com/aime-loic/book_it/blob/main/src/services/notification.service.js"
click node_push_service "https://github.com/aime-loic/book_it/blob/main/src/services/fcm.service.js"
click node_promo_service "https://github.com/aime-loic/book_it/blob/main/src/services/promo.service.js"
click node_scheduler_routes "https://github.com/aime-loic/book_it/blob/main/src/routes/internal.routes.js"
click node_scheduler_service "https://github.com/aime-loic/book_it/blob/main/src/services/scheduler.service.js"

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_api,node_ticket_routes,node_driver_routes toneBlue
class node_ticket_controller,node_ticket_service,node_ticket_data toneAmber
class node_route_management,node_fleet_management,node_driver_controller toneMint
class node_travel_cards,node_rfid_cards,node_identity_service toneRose
class node_sequelize,node_notifications,node_push_service,node_promo_service,node_scheduler_routes,node_scheduler_service,node_passenger,node_operator,node_driver,node_flutterwave toneIndigo
```

## Components

### API runtime

- [Express API](https://github.com/aime-loic/book_it/blob/main/src/app.js): `src/app.js`
- [Ticket endpoints](https://github.com/aime-loic/book_it/blob/main/src/routes/ticket.routes.js): `src/routes/ticket.routes.js`
- [Driver endpoints](https://github.com/aime-loic/book_it/blob/main/src/routes/driver.routes.js): `src/routes/driver.routes.js`

### Passenger booking

- [Ticket handlers](https://github.com/aime-loic/book_it/blob/main/src/controllers/ticket.controller.js): `src/controllers/ticket.controller.js`
- [Reservations and payments](https://github.com/aime-loic/book_it/blob/main/src/services/ticket.service.js): `src/services/ticket.service.js`
- [Ticket records](https://github.com/aime-loic/book_it/blob/main/src/database/models/ticket.js): `src/database/models/ticket.js`

### Fleet operations

- [Routes and stops](https://github.com/aime-loic/book_it/blob/main/src/services/route.service.js): `src/services/route.service.js`
- [Buses and drivers](https://github.com/aime-loic/book_it/blob/main/src/services/driver.service.js): `src/services/driver.service.js`
- [Driver handlers](https://github.com/aime-loic/book_it/blob/main/src/controllers/driver.controller.js): `src/controllers/driver.controller.js`

### Identity and boarding

- [Travel-card validation](https://github.com/aime-loic/book_it/blob/main/src/controllers/travel-card.controller.js): `src/controllers/travel-card.controller.js`
- [RFID registration](https://github.com/aime-loic/book_it/blob/main/src/controllers/rfid-card.controller.js): `src/controllers/rfid-card.controller.js`
- [Authentication](https://github.com/aime-loic/book_it/blob/main/src/services/auth.service.js): `src/services/auth.service.js`

### Messaging and scheduling

- [Database connection](https://github.com/aime-loic/book_it/blob/main/src/config/sequelize.js): `src/config/sequelize.js`
- [Notifications](https://github.com/aime-loic/book_it/blob/main/src/services/notification.service.js): `src/services/notification.service.js`
- [Push delivery](https://github.com/aime-loic/book_it/blob/main/src/services/fcm.service.js): `src/services/fcm.service.js`
- [Promo codes](https://github.com/aime-loic/book_it/blob/main/src/services/promo.service.js): `src/services/promo.service.js`
- [Scheduled-job endpoint](https://github.com/aime-loic/book_it/blob/main/src/routes/internal.routes.js): `src/routes/internal.routes.js`
- [Trip and retention jobs](https://github.com/aime-loic/book_it/blob/main/src/services/scheduler.service.js): `src/services/scheduler.service.js`

### Other components

- **Passenger**
- **Bus operator**
- **Driver**
- **Flutterwave**

## Connections

- Passenger → Express API: searches and books
- Bus operator → Express API: manages services
- Driver → Express API: handles trips
- Express API → Ticket endpoints: mounts endpoints (evidence: `src/app.js`)
- Express API → Driver endpoints: mounts endpoints (evidence: `src/app.js`)
- Ticket endpoints → Ticket handlers: dispatches requests (evidence: `src/routes/ticket.routes.js`)
- Driver endpoints → Driver handlers: dispatches requests (evidence: `src/routes/driver.routes.js`)
- Driver endpoints → Travel-card validation: dispatches validation (evidence: `src/routes/driver.routes.js`)
- Ticket handlers → Reservations and payments: calls booking logic (evidence: `src/controllers/ticket.controller.js`)
- Driver handlers → Reservations and payments: uses ticket logic (evidence: `src/controllers/driver.controller.js`)
- Reservations and payments → Ticket records: reads and writes (evidence: `src/services/ticket.service.js`)
- Reservations and payments → Notifications: creates notices (evidence: `src/services/ticket.service.js`)
- Reservations and payments → Flutterwave: initiates and checks charges (evidence: `src/services/ticket.service.js`)
- Driver → Travel-card validation: validates boarding cards
- Passenger → RFID registration: registers card UID
- Bus operator → Routes and stops: manages routes
- Bus operator → Buses and drivers: manages fleet
- Reservations and payments → Database connection: uses database models (evidence: `src/services/ticket.service.js`)
- Notifications → Push delivery: delegates push delivery (evidence: `src/services/notification.service.js`)
- Scheduled-job endpoint → Trip and retention jobs: runs scheduled jobs (evidence: `src/routes/internal.routes.js`)
- Trip and retention jobs → Notifications: creates notices (evidence: `src/services/scheduler.service.js`)
- Trip and retention jobs → Promo codes: generates loyalty offers (evidence: `src/services/scheduler.service.js`)
- Trip and retention jobs → Reservations and payments: checks payment status (evidence: `src/services/scheduler.service.js`)
- Trip and retention jobs → Ticket records: reads ticket state (evidence: `src/services/scheduler.service.js`)
