# shuncoder/limousine-booking-app architecture

> Architecture diagram of the GitHub repository shuncoder/limousine-booking-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuncoder/limousine-booking-app
- Repository: https://github.com/shuncoder/limousine-booking-app

## Overview

1. **Repository shape**
   This is a three-part system: a **Node.js backend**, a **React Native mobile app**, and a **Next.js web admin portal**. The backend is the shared integration point; both clients consume its REST APIs and realtime socket events.

2. **Backend as the central application layer**
   The backend (`backend/src`) is an Express-based API server that also owns **authentication**, **business rules**, **database access**, **realtime messaging**, and **background jobs**. It is the architectural core of the repo.

3. **Persistence and domain model**
   MongoDB is the main data store, accessed through models such as `User`, `Trip`, `Ride`, `Ticket`, `SeatHold`, `Notification`, `Complaint`, `Promo`, `Banner`, and `AdminNotification`. These models indicate the main domain boundaries: identity, trip planning, booking, seat reservation, customer communications, and admin content.

4. **Request flow in the backend**
   Incoming HTTP requests are routed through `routes/*`, passed through middleware like JWT auth and role checks, then handled by controllers in `controllers/*`. Controllers coordinate validation, pricing, booking logic, notifications, and persistence through the models and utility modules.

5. **Realtime and concurrency handling**
   Socket.IO is used for live updates, especially around booking and trip status. The presence of `seatHoldController`, `SeatHold` model, `seatHoldWatcher`, and `seatJobs` suggests the system protects inventory with **temporary seat locks** and expiry-based cleanup to prevent double booking.

6. **Routing, maps, and trip computation**
   The backend includes a dedicated routing subsystem: `routingController`, `astar`, `osmGraph`, `routeSimulator`, and the bundled `hanoi.osm.pbf` data. This indicates the app computes or simulates routes locally using OpenStreetMap-derived graph data rather than relying only on an external map API.

7. **Pricing and booking rules**
   Utilities like `pricing.js` and `bookingValidation.js` suggest the booking flow is not a simple CRUD action. Fare calculation, seat validation, and trip eligibility are centralized in backend utility modules so that both mobile and admin views use the same rules.

8. **Notifications and messaging**
   Notifications are modeled on the backend and delivered through `notificationController`, `notify.js`, and Socket.IO. There is also Gmail/mailer configuration, which implies email is used for account or booking-related communication, alongside in-app notifications.

9. **Mobile app role**
   The mobile app (`mobile/src`) is the customer and driver-facing client. It contains screens for login, registration, home, booking, seat selection, payment, ride history, profile, notifications, and route visualization, plus a separate driver area under `screens/driver`.

10. **Mobile app data integration**
   The mobile client uses a service layer (`services/api.js`, `axiosWithRefresh.js`, `socket.js`, token storage) and many feature hooks (`useTripSearch`, `useTicketPayment`, `useSeatSocket`, `useNotifications`, etc.). This shows a hook-driven architecture where UI screens stay thin and domain logic is pushed into reusable hooks and services.

11. **Realtime booking UX on mobile**
   Seat selection and payment are tightly coupled to backend state via sockets and countdown hooks. The mobile app likely listens for seat availability changes and ticket/payment timers so the user sees live availability and reservation expiry while booking.

12. **Web admin portal role**
   The `webadmin` app is a separate Next.js admin console for operational management. Its pages for users, drivers, trips, tickets, complaints, reports, banners, and promos map directly to backend admin endpoints and are designed for staff workflows rather than end-user booking.

13. **Cross-app boundary**
   The key architectural boundary is between **clients** and **shared backend services**. Mobile and admin do not talk to each other directly; both depend on the backend for data consistency, authentication, role-based access, and realtime event propagation.

14. **Operational concerns**
   Backend infrastructure includes Docker-oriented packaging, a MongoDB datastore, file uploads for banners, and background processes for seat-hold expiration. The result is a system that blends request/response APIs with realtime and scheduled processing to support a limousine booking workflow end to end.

Main entry points: [`backend/src/index.js`](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/index.js) (API server), [`backend/src/models/Ticket.js`](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/Ticket.js) (Booking data), [`backend/src/config/database.js`](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/config/database.js) (Database), [`mobile/App.js`](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/App.js) (Mobile app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_api_server["API server<br/>express app<br/>[index.js]"]
  node_auth_layer["Auth layer<br/>jwt middleware<br/>[authMiddleware.js]"]
  node_admin_guard["Role guard<br/>rbac middleware<br/>[requireRole.js]"]
  node_auth_ctrl["Auth<br/>controller<br/>[authController.js]"]
  node_trip_ctrl["Trips<br/>controller<br/>[tripController.js]"]
  node_ticket_ctrl["Tickets<br/>controller"]
  node_seat_ctrl["Seat holds<br/>controller"]
  node_route_ctrl["Routing<br/>controller"]
  node_notify_ctrl["Notifications<br/>controller"]
  node_admin_ctrl["Admin<br/>controller<br/>[adminController.js]"]
  node_booking_rules["Booking rules<br/>utils<br/>[pricing.js]"]
  node_route_engine["Route engine<br/>utils<br/>[astar.js]"]
  node_seat_jobs["Seat jobs<br/>background jobs<br/>[seatJobs.js]"]
  node_socket_layer(("Realtime<br/>socket.io<br/>[socket.js]"))
  node_user_model["Users<br/>mongo model<br/>[User.js]"]
  node_trip_model["Trips<br/>mongo model<br/>[Trip.js]"]
  node_booking_models["Booking data<br/>mongo models<br/>[Ticket.js]"]
  node_db_config[("Database<br/>mongo config<br/>[database.js]")]
end

subgraph group_mobile["Mobile"]
  node_mobile_app["Mobile app<br/>react native app<br/>[App.js]"]
  node_mobile_services["API services<br/>client services<br/>[api.js]"]
  node_mobile_hooks["Feature hooks<br/>[useTripSearch.js]"]
  node_mobile_screens["Screens<br/>[HomeScreen.js]"]
  node_mobile_seat["Seat map<br/>ui component<br/>[SeatMap.js]"]
end

subgraph group_webadmin["Web Admin"]
  node_web_app["Admin app<br/>next.js app<br/>[layout.tsx]"]
  node_web_pages["Admin pages<br/>routes<br/>[page.tsx]"]
  node_web_auth["Sign in<br/>auth ui<br/>[SignInForm.tsx]"]
  node_web_api["Admin API<br/>client api<br/>[api.ts]"]
end

node_api_server -->|"protects"| node_auth_layer
node_api_server -->|"enforces"| node_admin_guard
node_api_server -->|"routes to"| node_auth_ctrl
node_api_server -->|"routes to"| node_trip_ctrl
node_api_server -->|"routes to"| node_ticket_ctrl
node_api_server -->|"routes to"| node_seat_ctrl
node_api_server -->|"routes to"| node_route_ctrl
node_api_server -->|"routes to"| node_notify_ctrl
node_api_server -->|"routes to"| node_admin_ctrl
node_auth_ctrl -->|"reads/writes"| node_user_model
node_trip_ctrl -->|"reads/writes"| node_trip_model
node_ticket_ctrl -->|"uses"| node_booking_rules
node_ticket_ctrl -->|"persists"| node_booking_models
node_seat_ctrl -->|"locks"| node_booking_models
node_seat_ctrl -.->|"expires"| node_seat_jobs
node_route_ctrl -->|"computes"| node_route_engine
node_notify_ctrl -->|"broadcasts"| node_socket_layer
node_notify_ctrl -->|"persists"| node_booking_models
node_db_config -->|"supports"| node_user_model
node_db_config -->|"supports"| node_trip_model
node_db_config -->|"supports"| node_booking_models
node_mobile_app -->|"uses"| node_mobile_services
node_mobile_app -->|"renders"| node_mobile_hooks
node_mobile_app -->|"navigates"| node_mobile_screens
node_mobile_screens -->|"includes"| node_mobile_seat
node_mobile_services -->|"calls"| node_api_server
node_mobile_services -->|"listens to"| node_socket_layer
node_web_app -->|"hosts"| node_web_pages
node_web_app -->|"authenticates"| node_web_auth
node_web_pages -->|"uses"| node_web_api
node_web_api -->|"calls"| node_api_server

click node_api_server "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/index.js"
click node_auth_layer "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/middlewares/authMiddleware.js"
click node_admin_guard "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/middlewares/requireRole.js"
click node_auth_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/authController.js"
click node_trip_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/tripController.js"
click node_ticket_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/ticketController.js"
click node_seat_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/seatHoldController.js"
click node_route_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/routingController.js"
click node_notify_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/notificationController.js"
click node_admin_ctrl "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/adminController.js"
click node_booking_rules "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/utils/pricing.js"
click node_route_engine "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/utils/astar.js"
click node_seat_jobs "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/jobs/seatJobs.js"
click node_socket_layer "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/sockets/socket.js"
click node_user_model "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/User.js"
click node_trip_model "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/Trip.js"
click node_booking_models "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/Ticket.js"
click node_db_config "https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/config/database.js"
click node_mobile_app "https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/App.js"
click node_mobile_services "https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/services/api.js"
click node_mobile_hooks "https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/hooks/useTripSearch.js"
click node_mobile_screens "https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/screens/HomeScreen.js"
click node_mobile_seat "https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/components/SeatMap.js"
click node_web_app "https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/app/layout.tsx"
click node_web_pages "https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/app/(admin)/page.tsx"
click node_web_auth "https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/components/auth/SignInForm.tsx"
click node_web_api "https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/lib/api.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_api_server,node_auth_layer,node_admin_guard,node_auth_ctrl,node_trip_ctrl,node_ticket_ctrl,node_seat_ctrl,node_route_ctrl,node_notify_ctrl,node_admin_ctrl,node_booking_rules,node_route_engine,node_seat_jobs,node_socket_layer,node_user_model,node_trip_model,node_booking_models,node_db_config toneBlue
class node_mobile_app,node_mobile_services,node_mobile_hooks,node_mobile_screens,node_mobile_seat toneAmber
class node_web_app,node_web_pages,node_web_auth,node_web_api toneMint
```

## Components

### Backend

Express API, domain logic, realtime, jobs, and MongoDB persistence.

- [API server](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/index.js): express app · Bootstraps the backend, HTTP routes, sockets, and app lifecycle. · `backend/src/index.js`
- [Auth layer](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/middlewares/authMiddleware.js): jwt middleware · JWT authentication and role enforcement for protected APIs. · `backend/src/middlewares/authMiddleware.js`
- [Role guard](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/middlewares/requireRole.js): rbac middleware · Restricts admin and operator actions by role. · `backend/src/middlewares/requireRole.js`
- [Auth](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/authController.js): controller · Login and registration flows for shared identity. · `backend/src/controllers/authController.js`
- [Trips](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/tripController.js): controller · Trip search, lifecycle, and trip-facing operations. · `backend/src/controllers/tripController.js`
- [Tickets](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/ticketController.js): controller · Booking, ticket issuance, and reservation persistence. · `backend/src/controllers/ticketController.js`
- [Seat holds](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/seatHoldController.js): controller · Temporary seat locking to prevent double booking. · `backend/src/controllers/seatHoldController.js`
- [Routing](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/routingController.js): controller · Route calculation and trip path simulation. · `backend/src/controllers/routingController.js`
- [Notifications](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/notificationController.js): controller · In-app notification delivery and unread state. · `backend/src/controllers/notificationController.js`
- [Admin](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/controllers/adminController.js): controller · Admin-facing coordination for oversight workflows. · `backend/src/controllers/adminController.js`
- [Booking rules](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/utils/pricing.js): utils · Fare, availability, and booking validation logic. · `backend/src/utils/pricing.js`
- [Route engine](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/utils/astar.js): utils · Local routing graph, A* search, and simulation over OSM data. · `backend/src/utils/astar.js`
- [Seat jobs](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/jobs/seatJobs.js): background jobs · Expiry and cleanup workers for temporary seat holds. · `backend/src/jobs/seatJobs.js`
- [Realtime](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/sockets/socket.js): socket.io · Server-side event channel for booking and trip updates. · `backend/src/sockets/socket.js`
- [Users](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/User.js): mongo model · Identity and account records. · `backend/src/models/User.js`
- [Trips](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/Trip.js): mongo model · Trip schedules, capacity, and route metadata. · `backend/src/models/Trip.js`
- [Booking data](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/models/Ticket.js): mongo models · Tickets, rides, seat holds, notifications, complaints, promos, banners, and admin notifications. · `backend/src/models/Ticket.js`
- [Database](https://github.com/shuncoder/limousine-booking-app/blob/main/backend/src/config/database.js): mongo config · MongoDB connection and persistence setup. · `backend/src/config/database.js`

### Mobile

React Native customer and driver app.

- [Mobile app](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/App.js): react native app · Customer and driver client shell for navigation and UI. · `mobile/App.js`
- [API services](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/services/api.js): client services · Axios, token refresh, socket, and local storage integration. · `mobile/src/services/api.js`
- [Feature hooks](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/hooks/useTripSearch.js): hooks · Trip search, booking, payment, notifications, seat sockets, and driver workflows. · `mobile/src/hooks/useTripSearch.js`
- [Screens](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/screens/HomeScreen.js): ui screens · Customer and driver screens for search, booking, payment, history, and profile. · `mobile/src/screens/HomeScreen.js`
- [Seat map](https://github.com/shuncoder/limousine-booking-app/blob/main/mobile/src/components/SeatMap.js): ui component · Interactive seat selection tied to live availability. · `mobile/src/components/SeatMap.js`

### Web Admin

Next.js staff console for operations and content management.

- [Admin app](https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/app/layout.tsx): next.js app · Staff console shell and routing for operational pages. · `webadmin/src/app/layout.tsx`
- [Admin pages](https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/app/(admin)/page.tsx): routes · Pages for users, drivers, trips, tickets, complaints, reports, banners, and promos. · `webadmin/src/app/(admin)/page.tsx`
- [Sign in](https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/components/auth/SignInForm.tsx): auth ui · Admin login form and authentication entry point. · `webadmin/src/components/auth/SignInForm.tsx`
- [Admin API](https://github.com/shuncoder/limousine-booking-app/blob/main/webadmin/src/lib/api.ts): client api · Shared API layer used by the admin console. · `webadmin/src/lib/api.ts`

## Connections

- API server → Auth layer: protects · HTTP routes are guarded by authentication middleware.
- API server → Role guard: enforces · Role checks restrict admin operations.
- API server → Auth: routes to · Authentication requests are handled by the auth controller.
- API server → Trips: routes to · Trip-related requests flow into trip controllers.
- API server → Tickets: routes to · Booking and ticket actions flow into ticket handling.
- API server → Seat holds: routes to · Seat reservation holds are managed centrally.
- API server → Routing: routes to · Route computation endpoints are exposed by the backend.
- API server → Notifications: routes to · Notification APIs are served by the backend.
- API server → Admin: routes to · Admin workflows are coordinated in the API layer.
- Auth → Users: reads/writes · Authentication creates and validates user records.
- Trips → Trips: reads/writes · Trip state is persisted through trip models.
- Tickets → Booking rules: uses · Pricing and booking validation are shared here.
- Tickets → Booking data: persists · Tickets and related booking entities are stored in MongoDB.
- Seat holds → Booking data: locks · Temporary seat holds are stored alongside booking data.
- Seat holds → Seat jobs: expires · Background workers clear stale seat holds.
- Routing → Route engine: computes · Routes and simulations use local OSM graph utilities.
- Notifications → Realtime: broadcasts · Notifications are pushed in realtime.
- Notifications → Booking data: persists · Notifications and related messages are stored.
- Database → Users: supports · MongoDB backing store for core identity data.
- Database → Trips: supports · MongoDB backing store for trip data.
- Database → Booking data: supports · MongoDB backing store for booking and admin content.
- Mobile app → API services: uses · The app shell consumes shared network and socket services.
- Mobile app → Feature hooks: renders · Feature screens are driven by reusable hooks.
- Mobile app → Screens: navigates · Primary customer and driver experiences live in screens.
- Screens → Seat map: includes · Seat selection is a key booking interaction.
- API services → API server: calls · Mobile clients consume backend REST APIs.
- API services → Realtime: listens to · Mobile clients subscribe to realtime booking events.
- Admin app → Admin pages: hosts · Admin routes render operational pages.
- Admin app → Sign in: authenticates · Admin console sign-in entry point.
- Admin pages → Admin API: uses · Admin pages fetch data through the shared client API layer.
- Admin API → API server: calls · Admin console depends on the backend REST API.
