How shuncoder/limousine-booking-app works
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: index.js API server · Ticket.js Booking data · database.js Database · App.js Mobile app
Components 27
Backend
Express API, domain logic, realtime, jobs, and MongoDB persistence.
- API server · Bootstraps the backend, HTTP routes, sockets, and app lifecycle.
backend/src/index.js - Auth layer · JWT authentication and role enforcement for protected APIs.
backend/src/middlewares/authMiddleware.js - Role guard · Restricts admin and operator actions by role.
backend/src/middlewares/requireRole.js - Auth · Login and registration flows for shared identity.
backend/src/controllers/authController.js - Trips · Trip search, lifecycle, and trip-facing operations.
backend/src/controllers/tripController.js - Tickets · Booking, ticket issuance, and reservation persistence.
backend/src/controllers/ticketController.js - Seat holds · Temporary seat locking to prevent double booking.
backend/src/controllers/seatHoldController.js - Routing · Route calculation and trip path simulation.
backend/src/controllers/routingController.js - Notifications · In-app notification delivery and unread state.
backend/src/controllers/notificationController.js - Admin · Admin-facing coordination for oversight workflows.
backend/src/controllers/adminController.js - Booking rules · Fare, availability, and booking validation logic.
backend/src/utils/pricing.js - Route engine · Local routing graph, A* search, and simulation over OSM data.
backend/src/utils/astar.js - Seat jobs · Expiry and cleanup workers for temporary seat holds.
backend/src/jobs/seatJobs.js - Realtime · Server-side event channel for booking and trip updates.
backend/src/sockets/socket.js - Users · Identity and account records.
backend/src/models/User.js - Trips · Trip schedules, capacity, and route metadata.
backend/src/models/Trip.js - Booking data · Tickets, rides, seat holds, notifications, complaints, promos, banners, and admin notifications.
backend/src/models/Ticket.js - Database · MongoDB connection and persistence setup.
backend/src/config/database.js
Mobile
React Native customer and driver app.
- Mobile app · Customer and driver client shell for navigation and UI.
mobile/App.js - API services · Axios, token refresh, socket, and local storage integration.
mobile/src/services/api.js - Feature hooks · Trip search, booking, payment, notifications, seat sockets, and driver workflows.
mobile/src/hooks/useTripSearch.js - Screens · Customer and driver screens for search, booking, payment, history, and profile.
mobile/src/screens/HomeScreen.js - Seat map · 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 · Staff console shell and routing for operational pages.
webadmin/src/app/layout.tsx - Admin pages · Pages for users, drivers, trips, tickets, complaints, reports, banners, and promos.
webadmin/src/app/(admin)/page.tsx - Sign in · Admin login form and authentication entry point.
webadmin/src/components/auth/SignInForm.tsx - Admin API · Shared API layer used by the admin console.
webadmin/src/lib/api.ts
Connections 31
- 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.