Architecture - aelassas/bookcars GitHub Wiki

Overall Architecture

This section provides a detailed overview of the overall architecture of the BookCars platform, which consists of several distinct but interconnected applications:

Backend – The server-side API responsible for handling data storage, business logic, authentication, and communication between the client apps and the database.
Frontend – The web-based customer application where users can browse available vehicles, book them, and manage their reservations.
Admin Panel – A management dashboard for administrators and car suppliers to control vehicles, monitor bookings, manage users, and oversee platform operations.
Mobile App – A native-like cross-platform app built with React Native and Expo, offering a seamless rental experience on both iOS and Android devices.

BookCars follows modern software engineering principles, including:

Monorepo architecture: All apps (backend, frontend, admin panel, and mobile) are organized within a single repository. This allows shared code, configuration, and dependencies to be managed centrally.
TypeScript-first development: All components are written in TypeScript to ensure type safety, improved tooling, and better collaboration across teams.
Code sharing: Common models, utility functions, and TypeScript types are extracted into shared packages for consistent logic between the backend and frontend/mobile clients.
API-first approach: The backend exposes a REST API that serves as the single source of truth for all client apps.
Docker-based workflow: All apps are containerized using Docker, allowing consistent development and production environments across teams and deployments.

By combining modern tools and technologies with a clean modular structure, BookCars delivers a unified development experience while supporting a wide range of platforms and user roles.

Technologies Overview

Component	Technologies Used
Backend	Node.js, Express.js, MongoDB, JWT, Stripe SDK, PayPal SDK
Frontend	React, MUI, Stripe, PayPal, Zod, Vite
Admin Panel	React, MUI, Zod, Vite
Mobile App	React Native, Expo, Expo Push Notifications, Firebase, Stripe
Shared	TypeScript, ESLint, Husky, Docker

Platform Highlights

Secure Authentication: JWT-based auth ensures secure and stateless login flows for all users (customers, suppliers, admins).
Payment Integration: Seamless payments with support for both Stripe and PayPal, including web and mobile flows.
Internationalization (i18n): Multi-language support is built-in using a shared translation structure for consistency across all platforms.
Push Notifications: The mobile app integrates with Expo Push and Firebase Cloud Messaging (FCM) to keep users updated on booking status and important events.
Live Availability and Scheduling: Real-time car availability, date-based pricing, and conflict-free booking logic.
Reusable Components: A large collection of shared UI components across frontend and admin apps to ensure consistent UX and reduce duplication.
Type-safe Forms: Zod schemas are used across all apps for form validation and data parsing.

This architecture empowers developers to scale the product efficiently, onboard new features with confidence, and deliver a seamless experience to both end users and administrators.

TypeScript Across the Stack

All core components of BookCars are written in TypeScript, including backend APIs, web apps, and the mobile app. Shared types and interfaces live in a centralized package to maintain consistency between the different apps.

Shared Types

Shared types are defined in: ./packages/bookcars-types
Ensures consistent request/response models across all clients
Also used to define form validation schemas via Zod

Backend

The BookCars Backend is a modular, scalable REST API built using Node.js, Express, and MongoDB, following the Model-View-Controller (MVC) architectural pattern. It serves as the central data and business logic layer for all platform clients, including the customer-facing frontend web app, the admin panel, and the mobile app.

This unified API architecture ensures consistent data handling, centralized security, and maintainable code across the ecosystem. The backend is designed to be:

Modular: Clean folder structure and reusable components (controllers, models, middlewares)
Extensible: Easy to add new features, such as additional payment providers or modules
Secure: JWT-based authentication, middleware-based authorization, and robust request validation
Scalable: Supports high concurrency and real-time updates with efficient MongoDB queries and indexing

In addition to core CRUD operations, the backend also handles:

User authentication and authorization
Payment processing via Stripe and PayPal
Booking availability and scheduling
Location-based search and filtering
Push notification triggers
Multi-language support through dynamic i18n content

The backend also includes setup scripts for data seeding, environment configuration, and test coverage to streamline development, testing, and deployment.

Security

Uses JWT for user authentication (access & refresh tokens)
Public and private routes protected via middleware
Input validation, sanitization, and error handling via middlewares

Core Entry Points

src/app.ts: Express app creation, middleware registration
src/index.ts: Entry point and server bootstrap
src/montitoring/instrument.ts: Sentry integration and initialization
src/payment/stripe.ts: Stripe integration (checkout, webhooks)
src/payment/paypal.ts: PayPal integration

Structure

/backend
├── src/
│   ├── config/           # Environment configs
│   ├── controllers/      # Business logic
│   ├── lang/             # i18n translations
│   ├── middlewares/      # Auth, error handling, etc.
│   ├── models/           # Mongoose models
│   ├── monitoring/       # Sentry setup
│   ├── payment/          # Stripe, PayPal, and payment integration handlers
│   ├── routes/           # Express route handlers
│   ├── setup/            # Setup and reset scripts
│   ├── utils/            # common utilities
│   ├── app.ts            # App instance
│   └── index.ts          # API bootstrap
├── __tests__/            # Jest integration tests

Frontend

The Frontend Web App is built with React and MUI, offering a smooth car rental experience for customers.

Features

Live car search with date/time/location filters
Car details view with availability and pricing
Secure checkout with Stripe or PayPal
User account management, booking history

Structure

/frontend
├── src/
│   ├── assets/           # CSS and images
│   ├── components/       # Reusable UI components
│   ├── config/           # Environment configs
│   ├── context/          # React contexts
│   ├── hooks/            # Custom hooks
│   ├── lang/             # Translations
│   ├── models/           # Zod schemas for forms
│   ├── pages/            # Route-level pages
│   ├── services/         # API clients (Axios)
│   ├── utils/            # Common utilities
│   ├── App.tsx           # App and routes
│   └── index.tsx         # Entry point

Admin Panel

The Admin Panel provides management tools for both platform admins and suppliers, also built with React and MUI for fast loading and rich interactions.

Admin Capabilities

Manage all users, cars, locations, and bookings
View global booking statistics
Invite and manage suppliers

Supplier Capabilities

Manage only their own locations, cars and bookings
Restricted access compared to platform admins

Structure

/admin
├── src/
│   ├── assets/           # CSS and images
│   ├── components/       # Reusable UI components
│   ├── config/           # Environment configs
│   ├── context/          # React contexts
│   ├── hooks/            # Custom hooks
│   ├── lang/             # Translations
│   ├── models/           # Zod schemas for forms
│   ├── pages/            # Route-level pages
│   ├── services/         # API clients (Axios)
│   ├── utils/            # Common utilities
│   ├── App.tsx           # App and routes
│   └── index.tsx         # Entry point

Mobile App

The Mobile App is built using React Native and Expo, with full support for iOS and Android platforms.

Features

Search, filter, and book cars
Checkout using Stripe
View/manage bookings
Receive booking status updates via push notifications

Notifications

Uses Expo Push and Firebase Cloud Messaging (FCM)
Notifications triggered via backend events (booking updates, cancellations)

Structure

/mobile
├── assets/               # App images
├── config/               # Environment config
├── context/              # React contexts
├── lang/                 # i18n translations
├── plugins/              # Custom Expo plugins
├── screens/              # Pages like Home, Search, Bookings
├── components/           # Reusable UI
├── services/             # API clients
├── types/
│   ├── index.d.ts        # Global types
│   ├── env.d.ts          # Environment types
├── miscellaneous/
│   └── bookcarsTypes.ts  # Extra mobile types
├── utils/                # Common utilities
├── App.tsx               # App and navigation

Shared Packages

BookCars uses a monorepo layout with shared packages:

/packages
├── bookcars-types/         # Shared TypeScript interfaces and models
├── bookcars-helper/        # Common utilities (dates, formatting, etc.)
├── currency-converter/     # Currency converter
├── disable-react-devtools/ # Disable react dev tools utility
├── reactjs-social-login/   # Social login utility (Google, Apple, Facebook, etc.)

These packages are used across backend, frontend, admin panel, and mobile app for consistency.

Architecture Principles

Modularity: Each component is cleanly separated and easy to maintain.
Type-Safety: Powered by TypeScript, with shared types and validation.
Reusability: Core logic is abstracted into shared packages.
Internationalization: Supports multiple languages with i18n.
Security: Enforced via JWT, role-based access, and validation layers.

Docker & Development Environment

BookCars provides a Docker-first setup to support a smooth and consistent development and deployment experience:

Development (Dev Mode)

Backend
- Uses nodemon inside Docker for automatic server restarts on file changes.
- Fast feedback loop while writing API logic or working with MongoDB.
Frontend & Admin Panel
- Built using Vite with Hot Module Replacement (HMR) enabled.
- Mounted as bind volumes in Docker to reflect code changes instantly.
MongoDB
- Runs as a container alongside the backend for easy local setup.
- Runs as a containerized NoSQL database.
- Exposed for local connection (e.g., on localhost:27018).
Mongo Express
- A lightweight web-based MongoDB admin UI.
- Accessible at http://localhost:8084.
- Lets developers browse collections, documents, and manage data easily.

Docker Compose manages all services in development mode using a docker-compose.dev.yml file.

docker compose -f docker-compose.dev.yml up

For more information, checkout Docker documentation for development.

Production (Build & Deploy)

Optimized Dockerfiles for each component (backend, frontend, admin panel).
Production builds are minified and served using lightweight Node or static servers (e.g., nginx for frontend).
Environment variables are injected securely via .env.docker.

Docker Compose handles orchestration in production using docker-compose.yml.

docker compose -f docker-compose.yml up -d

For more information, checkout Docker documentation for production.

Codebase Overview

BookCars is a mature, full-featured platform with a large and well-structured codebase. As of now, the repository contains over 120,000 lines of code across the backend, frontend, admin panel, mobile app, shared packages, and test suites.

This scale reflects:

Deep feature coverage across all platforms
Extensive use of modular components
Comprehensive TypeScript type safety
High test coverage for critical backend functionality
Production-ready integrations for Stripe, PayPal, push notifications, and internationalization

Despite the size, the monorepo structure and strong architectural guidelines ensure the codebase remains organized, maintainable, and contributor-friendly.

Production Readiness

BookCars is designed for real-world use in production environments. It includes:

Secure JWT-based authentication with role-based access
Verified Stripe and PayPal payment workflows
Comprehensive Docker setup for both development and production
Admin and supplier dashboards with fine-grained permissions
Fully internationalized UI with support for multiple languages
Backend test coverage exceeding 80%, with CI pipelines and code quality checks
Mobile apps compatible with both Android and iOS using Expo
Modular monorepo architecture for scalable maintenance and feature growth

Thanks to these capabilities, BookCars is ready to be deployed and used in production by startups, rental companies, or custom fleet management platforms.

Git Pre-commit Checks with Husky

To maintain high code quality and consistency across the project, BookCars uses Husky to run automated checks before each commit. This ensures all code that enters the repository meets predefined standards and avoids common issues early in the development cycle.

Checks Performed

Check	Description
`lint`	Runs ESLint to catch style violations and code quality issues
`typeCheck`	Ensures type safety using the TypeScript compiler
`sizeCheck`	Prevents committing unusually large files that may affect performance

These checks are enforced for all codebases — backend, frontend, admin panel, and mobile app.

Benefits for Developers

Detects problems before code is committed
Keeps code style consistent across contributors
Avoids broken builds or runtime type errors
Prevents performance regressions from large files

Pre-commit Script

The logic for these checks is implemented in a custom script located at:

/pre-commit.js

This script:

Runs tasks concurrently per workspace (e.g., frontend, backend, mobile)
Adapts to Docker environments if needed
Supports selective linting and type-checking
Logs summaries and failures clearly

Manual Execution

You can manually run the checks using:

npm run pre-commit

This is useful if you want to validate your code before pushing without triggering a full commit. Note that you need to stage the files first.

Docker Awareness

The script intelligently detects whether it’s running inside Docker and adjusts paths and behavior accordingly to ensure correct execution.

Husky Setup

The Husky hook is defined in:

/.husky/pre-commit

It simply executes:

node pre-commit.js

If any of the checks fail, the commit will be aborted. This helps ensure that only safe, clean, and performant code is added to the repository.

Continuous Integration (CI)

BookCars uses GitHub Actions for automated Continuous Integration (CI), ensuring code is always tested and built correctly before merging. The CI workflows help catch issues early and enforce project standards across contributions.

Build Workflow

File: .github/workflows/build.yml
Purpose: Builds all packages and apps in the monorepo to ensure there are no runtime or dependency errors.

What it does:

Installs dependencies
Builds shared packages and each app (backend, frontend, admin panel, mobile)
Verifies successful compilation

This workflow helps maintain consistency and guarantees that the entire project is in a shippable state.

Test Workflow

File: .github/workflows/test.yml
Purpose: Runs all integration tests using Jest.

What it does:

Installs dependencies
Runs Jest test suites
Generates and reports test coverage

This workflow ensures that new commits do not break existing functionality and that the codebase remains reliable and maintainable.

BookCars ensures that the backend test coverage remains consistently above 80%, providing strong guarantees for API correctness and stability. Coverage reports are automatically uploaded to:

These platforms provide detailed insights into tested and untested code paths and highlight coverage trends. This encourages contributors to write meaningful tests and maintain a high standard across the codebase.

If the coverage upload to Coveralls or Codecov fails (e.g., due to service downtime or a network issue), the CI workflow is designed to continue and not fail the build, so development is not blocked. However, the repository owner is automatically notified by email when this happens. These services generate a hidden post internally to alert maintainers of the failure, allowing follow-up without interrupting team productivity.

CI + Husky: A Unified Quality Gate

Combined with the Husky pre-commit checks, CI workflows serve as a second layer of protection, verifying that even if something is missed locally, it will be caught during pull request checks.

These CI pipelines are triggered automatically on push and pull_request events targeting the main branch.

Architecture - aelassas/bookcars GitHub Wiki

Table Of Contents

Overall Architecture

Technologies Overview

Platform Highlights

TypeScript Across the Stack

Shared Types

Backend

Security

Core Entry Points

Structure

Frontend

Features

Structure

Admin Panel

Admin Capabilities

Supplier Capabilities

Structure

Mobile App

Features

Notifications

Structure

Shared Packages

Architecture Principles

Docker & Development Environment

Development (Dev Mode)

Production (Build & Deploy)

Codebase Overview

Production Readiness

Git Pre-commit Checks with Husky

Checks Performed

Benefits for Developers

Pre-commit Script

Manual Execution

Docker Awareness

Husky Setup

Continuous Integration (CI)

Build Workflow

Test Workflow

CI + Husky: A Unified Quality Gate