# aelassas/bookcars architecture

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

- Interactive diagram: https://gitdiagram.com/aelassas/bookcars
- Repository: https://github.com/aelassas/bookcars

## Overview

#### Purpose and Topology
BookCars is a multi-channel car-rental platform: customer web app, supplier/admin console, and native mobile client backed by one API. It supports single- and multi-supplier operations, fleet/location management, availability search, bookings, and Stripe/PayPal checkout. The deployable units are `frontend/`, `admin/`, `backend/`, and `mobile/`; shared TypeScript packages live in `packages/`.

#### Entrypoints and Runtime Boundaries
- The Node/TypeScript API boots from `backend/src/index.ts`, with Express application composition in `backend/src/app.ts`.
- Customer and admin web clients are Vite React SPAs entered through `frontend/src/main.tsx` / `frontend/src/App.tsx` and `admin/src/main.tsx` / `admin/src/App.tsx`.
- The mobile client is Expo/React Native file-routed, rooted at `mobile/app/_layout.tsx`, with screens under `mobile/app/(screens)/`.
- API access is isolated in per-client service layers, e.g. `frontend/src/services/axiosInstance.ts`, `admin/src/services/axiosInstance.ts`, and `mobile/services/axiosInstance.ts`.

#### API Domain Pipeline
The backend follows a route → controller → persistence/integration structure. Feature route modules such as `backend/src/routes/bookingRoutes.ts`, `backend/src/routes/carRoutes.ts`, and `backend/src/routes/userRoutes.ts` expose endpoints; their controllers execute domain operations. Route behavior is parameterized by matching route configuration modules, e.g. `backend/src/config/bookingRoutes.config.ts`. Security and protocol boundaries are centralized in `backend/src/middlewares/authJwt.ts`, `backend/src/middlewares/cors.ts`, and `backend/src/middlewares/allowedMethods.ts`.

#### Core Rental Data Model
Mongo-style domain models define the system of record for users, suppliers, fleets, geography, and rentals: `backend/src/models/User.ts`, `backend/src/models/Supplier.ts`, `backend/src/models/Car.ts`, `backend/src/models/Booking.ts`, `backend/src/models/Location.ts`, and `backend/src/models/DateBasedPrice.ts`. Booking and car controllers are the primary boundary for availability and pricing workflows: `backend/src/controllers/bookingController.ts` and `backend/src/controllers/carController.ts`. Database lifecycle/setup and operational scripts are located in `backend/src/setup/setup.ts`, `backend/src/setup/reset.ts`, and `backend/scripts/price.ts`.

#### Customer Journey and Payments
Customer clients search locations/cars, filter availability, select a vehicle, create a booking, then complete checkout. In web, this flow centers on `frontend/src/pages/Search.tsx`, `frontend/src/pages/Booking.tsx`, and `frontend/src/pages/Checkout.tsx`; mobile parallels it in `mobile/app/(screens)/cars.tsx`, `mobile/app/(screens)/booking.tsx`, and `mobile/app/(screens)/checkout.tsx`. Payment providers are adapterized at `backend/src/payment/stripe.ts` and `backend/src/payment/paypal.ts`, exposed through `backend/src/routes/stripeRoutes.ts` and `backend/src/routes/paypalRoutes.ts`; clients call dedicated payment services such as `frontend/src/services/StripeService.ts` and `frontend/src/services/PayPalService.ts`.

#### Operations, Identity, and Notifications
The admin SPA manages suppliers, fleet, bookings, users, pricing, and scheduling via pages such as `admin/src/pages/Bookings.tsx`, `admin/src/pages/Cars.tsx`, and `admin/src/pages/Scheduler.tsx`. The scheduler is a substantial embedded subsystem rooted at `admin/src/components/scheduler/SchedulerComponent.tsx`, with separate state and positioning providers. Authentication/user state is held at client boundaries (`admin/src/context/UserContext.tsx`, `frontend/src/context/UserContext.tsx`, `mobile/context/AuthContext.tsx`) and enforced server-side by JWT middleware. Notifications are modeled and routed through `backend/src/models/Notification.ts`, `backend/src/controllers/notificationController.ts`, and `backend/src/routes/notificationRoutes.ts`.

#### Infrastructure and External Services
Docker Compose orchestrates the service deployment in `docker-compose.yml` and development variant `docker-compose.dev.yml`; each web/API unit has production and development Dockerfiles. Nginx configuration exists at `__config/nginx.conf`, plus SPA-specific configs. External integrations indicated by code boundaries include Stripe, PayPal, IP geolocation (`backend/src/controllers/ipinfoController.ts`), email (`backend/src/utils/mailHelper.ts`), push tokens (`backend/src/models/PushToken.ts`), reCAPTCHA client contexts, social login, and monitoring instrumentation (`backend/src/monitoring/instrument.ts`). Shared contracts/helpers/currency logic are packaged in `packages/bookcars-types/index.ts`, `packages/bookcars-helper/index.ts`, and `packages/currency-converter/index.ts`.

Main entry points: [`frontend/src/main.tsx`](https://github.com/aelassas/bookcars/blob/main/frontend/src/main.tsx) (Customer web SPA), [`admin/src/main.tsx`](https://github.com/aelassas/bookcars/blob/main/admin/src/main.tsx) (Admin SPA), [`backend/src/index.ts`](https://github.com/aelassas/bookcars/blob/main/backend/src/index.ts) (Express API), [`backend/src/routes/bookingRoutes.ts`](https://github.com/aelassas/bookcars/blob/main/backend/src/routes/bookingRoutes.ts) (Feature routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client channels"]
  node_customer_web["Customer web SPA<br/>Vite React<br/>[main.tsx]"]
  node_customer_journey["Search, booking &amp; checkout<br/>customer pages<br/>[Search.tsx]"]
  node_admin_web["Admin SPA<br/>Vite React<br/>[main.tsx]"]
  node_scheduler["Fleet scheduler<br/>admin subsystem"]
  node_mobile["Mobile client<br/>Expo React Native<br/>[_layout.tsx]"]
  node_client_api_layers["Client API services<br/>Axios service layers<br/>[axiosInstance.ts]"]
  node_client_identity["Client auth state<br/>contexts<br/>[UserContext.tsx]"]
end

subgraph group_backend["Rental API"]
  node_api_bootstrap["Express API<br/>Node TypeScript<br/>[index.ts]"]
  node_api_security["Security middleware<br/>JWT, CORS, methods<br/>[authJwt.ts]"]
  node_api_routes["Feature routes<br/>route modules<br/>[bookingRoutes.ts]"]
  node_rental_workflows["Availability &amp; booking<br/>controllers"]
  node_rental_models[("Rental system of record<br/>Mongo domain models<br/>[Booking.ts]")]
  node_payment_routes["Payment endpoints<br/>route modules<br/>[stripeRoutes.ts]"]
  node_payment_adapters["Payment adapters<br/>Stripe and PayPal<br/>[stripe.ts]"]
  node_notifications["Notifications &amp; push tokens<br/>notification domain"]
end

subgraph group_integrations["External services"]
  node_stripe{{"Stripe<br/>payment provider"}}
  node_paypal{{"PayPal<br/>payment provider"}}
end

subgraph group_platform["Shared and deployment"]
  node_shared_packages["Shared TypeScript packages<br/>contracts and helpers<br/>[index.ts]"]
  node_compose["Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_nginx["Nginx edge<br/>reverse proxy<br/>[nginx.conf]"]
end

node_customer_web -->|"renders"| node_customer_journey
node_customer_web -->|"uses"| node_client_api_layers
node_customer_web -->|"holds session"| node_client_identity
node_admin_web -->|"hosts"| node_scheduler
node_admin_web -.->|"uses equivalent layer"| node_client_api_layers
node_mobile -.->|"uses equivalent layer"| node_client_api_layers
node_mobile -.->|"holds auth state"| node_client_identity
node_client_api_layers -->|"HTTPS API calls"| node_api_bootstrap
node_api_bootstrap -->|"applies"| node_api_security
node_api_security -->|"guards"| node_api_routes
node_api_routes -->|"dispatches"| node_rental_workflows
node_rental_workflows -->|"reads and writes"| node_rental_models
node_api_routes -->|"mounts"| node_payment_routes
node_payment_routes -->|"invokes"| node_payment_adapters
node_payment_adapters -->|"charges via"| node_stripe
node_payment_adapters -->|"charges via"| node_paypal
node_api_routes -->|"routes events"| node_notifications
node_customer_journey -.->|"checkout"| node_payment_routes
node_shared_packages -.->|"shared contracts"| node_customer_web
node_shared_packages -.->|"shared contracts"| node_admin_web
node_shared_packages -.->|"shared contracts"| node_api_bootstrap
node_compose -->|"deploys"| node_api_bootstrap
node_compose -->|"deploys"| node_customer_web
node_compose -->|"deploys"| node_admin_web
node_nginx -->|"serves"| node_customer_web
node_nginx -->|"serves"| node_admin_web
node_nginx -->|"proxies"| node_api_bootstrap

click node_customer_web "https://github.com/aelassas/bookcars/blob/main/frontend/src/main.tsx"
click node_customer_journey "https://github.com/aelassas/bookcars/blob/main/frontend/src/pages/Search.tsx"
click node_admin_web "https://github.com/aelassas/bookcars/blob/main/admin/src/main.tsx"
click node_scheduler "https://github.com/aelassas/bookcars/blob/main/admin/src/components/scheduler/SchedulerComponent.tsx"
click node_mobile "https://github.com/aelassas/bookcars/blob/main/mobile/app/_layout.tsx"
click node_client_api_layers "https://github.com/aelassas/bookcars/blob/main/frontend/src/services/axiosInstance.ts"
click node_client_identity "https://github.com/aelassas/bookcars/blob/main/frontend/src/context/UserContext.tsx"
click node_api_bootstrap "https://github.com/aelassas/bookcars/blob/main/backend/src/index.ts"
click node_api_security "https://github.com/aelassas/bookcars/blob/main/backend/src/middlewares/authJwt.ts"
click node_api_routes "https://github.com/aelassas/bookcars/blob/main/backend/src/routes/bookingRoutes.ts"
click node_rental_workflows "https://github.com/aelassas/bookcars/blob/main/backend/src/controllers/bookingController.ts"
click node_rental_models "https://github.com/aelassas/bookcars/blob/main/backend/src/models/Booking.ts"
click node_payment_routes "https://github.com/aelassas/bookcars/blob/main/backend/src/routes/stripeRoutes.ts"
click node_payment_adapters "https://github.com/aelassas/bookcars/blob/main/backend/src/payment/stripe.ts"
click node_notifications "https://github.com/aelassas/bookcars/blob/main/backend/src/controllers/notificationController.ts"
click node_shared_packages "https://github.com/aelassas/bookcars/blob/main/packages/bookcars-types/index.ts"
click node_compose "https://github.com/aelassas/bookcars/blob/main/docker-compose.yml"
click node_nginx "https://github.com/aelassas/bookcars/blob/main/__config/nginx.conf"

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_customer_web,node_customer_journey,node_admin_web,node_scheduler,node_mobile,node_client_api_layers,node_client_identity toneBlue
class node_api_bootstrap,node_api_security,node_api_routes,node_rental_workflows,node_rental_models,node_payment_routes,node_payment_adapters,node_notifications toneAmber
class node_stripe,node_paypal toneMint
class node_shared_packages,node_compose,node_nginx toneRose
```

## Components

### Client channels

- [Customer web SPA](https://github.com/aelassas/bookcars/blob/main/frontend/src/main.tsx): Vite React · `frontend/src/main.tsx`
- [Search, booking & checkout](https://github.com/aelassas/bookcars/blob/main/frontend/src/pages/Search.tsx): customer pages · Customer rental journey screens. · `frontend/src/pages/Search.tsx`
- [Admin SPA](https://github.com/aelassas/bookcars/blob/main/admin/src/main.tsx): Vite React · `admin/src/main.tsx`
- [Fleet scheduler](https://github.com/aelassas/bookcars/blob/main/admin/src/components/scheduler/SchedulerComponent.tsx): admin subsystem · `admin/src/components/scheduler/SchedulerComponent.tsx`
- [Mobile client](https://github.com/aelassas/bookcars/blob/main/mobile/app/_layout.tsx): Expo React Native · `mobile/app/_layout.tsx`
- [Client API services](https://github.com/aelassas/bookcars/blob/main/frontend/src/services/axiosInstance.ts): Axios service layers · Isolate API access per client. · `frontend/src/services/axiosInstance.ts`
- [Client auth state](https://github.com/aelassas/bookcars/blob/main/frontend/src/context/UserContext.tsx): contexts · `frontend/src/context/UserContext.tsx`

### Rental API

- [Express API](https://github.com/aelassas/bookcars/blob/main/backend/src/index.ts): Node TypeScript · HTTP application and server bootstrap. · `backend/src/index.ts`
- [Security middleware](https://github.com/aelassas/bookcars/blob/main/backend/src/middlewares/authJwt.ts): JWT, CORS, methods · `backend/src/middlewares/authJwt.ts`
- [Feature routes](https://github.com/aelassas/bookcars/blob/main/backend/src/routes/bookingRoutes.ts): route modules · Configured endpoint boundary for rental domains. · `backend/src/routes/bookingRoutes.ts`
- [Availability & booking](https://github.com/aelassas/bookcars/blob/main/backend/src/controllers/bookingController.ts): controllers · Car and booking workflows calculate availability and pricing. · `backend/src/controllers/bookingController.ts`
- [Rental system of record](https://github.com/aelassas/bookcars/blob/main/backend/src/models/Booking.ts): Mongo domain models · Users, suppliers, fleet, locations, pricing, and bookings. · `backend/src/models/Booking.ts`
- [Payment endpoints](https://github.com/aelassas/bookcars/blob/main/backend/src/routes/stripeRoutes.ts): route modules · `backend/src/routes/stripeRoutes.ts`
- [Payment adapters](https://github.com/aelassas/bookcars/blob/main/backend/src/payment/stripe.ts): Stripe and PayPal · `backend/src/payment/stripe.ts`
- [Notifications & push tokens](https://github.com/aelassas/bookcars/blob/main/backend/src/controllers/notificationController.ts): notification domain · `backend/src/controllers/notificationController.ts`

### External services

- **Stripe**: payment provider
- **PayPal**: payment provider

### Shared and deployment

- [Shared TypeScript packages](https://github.com/aelassas/bookcars/blob/main/packages/bookcars-types/index.ts): contracts and helpers · `packages/bookcars-types/index.ts`
- [Container deployment](https://github.com/aelassas/bookcars/blob/main/docker-compose.yml): Docker Compose · Orchestrates deployable web and API units. · `docker-compose.yml`
- [Nginx edge](https://github.com/aelassas/bookcars/blob/main/__config/nginx.conf): reverse proxy · `__config/nginx.conf`

## Connections

- Customer web SPA → Search, booking & checkout: renders
- Customer web SPA → Client API services: uses
- Customer web SPA → Client auth state: holds session
- Admin SPA → Fleet scheduler: hosts
- Admin SPA → Client API services: uses equivalent layer
- Mobile client → Client API services: uses equivalent layer
- Mobile client → Client auth state: holds auth state
- Client API services → Express API: HTTPS API calls
- Express API → Security middleware: applies
- Security middleware → Feature routes: guards
- Feature routes → Availability & booking: dispatches
- Availability & booking → Rental system of record: reads and writes
- Feature routes → Payment endpoints: mounts
- Payment endpoints → Payment adapters: invokes
- Payment adapters → Stripe: charges via
- Payment adapters → PayPal: charges via
- Feature routes → Notifications & push tokens: routes events
- Search, booking & checkout → Payment endpoints: checkout
- Shared TypeScript packages → Customer web SPA: shared contracts
- Shared TypeScript packages → Admin SPA: shared contracts
- Shared TypeScript packages → Express API: shared contracts
- Container deployment → Express API: deploys
- Container deployment → Customer web SPA: deploys
- Container deployment → Admin SPA: deploys
- Nginx edge → Customer web SPA: serves
- Nginx edge → Admin SPA: serves
- Nginx edge → Express API: proxies
