# osama8809/bus-booking-system architecture

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

- Interactive diagram: https://gitdiagram.com/osama8809/bus-booking-system
- Repository: https://github.com/osama8809/bus-booking-system

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Laravel application (PHP 8, Laravel Sail/Docker) exposing two JSON APIs for seat-availability and booking plus a Blade-based admin UI.
- Domain: bus fleet management / seat reservation across predefined trips and stations.

##### File structure
- Top-level folders & files:
- app.php, artisan, console.php – Laravel’s entrypoints
- api.php, web.php – route definitions for JSON APIs vs web/admin UI
- Controllers (e.g., ReservationsController.php, RegisteredUserController.php, VerifyEmailController.php)
- Domain Models & Factories at root: Bus, City, Trip, TripsSeat, Reservations, User + Factories
- config/*.php – all Laravel config files (database, cache, queue, cors, sanctum, etc.)
- docker-compose.yml – orchestrates PHP, MySQL, Node (for front-end builds)
- package.json, vite.config.js, tailwind.config.js, postcss.config.js – front-end asset pipeline
- bus-seats-reservations.mwb – MySQL workbench schema model

##### README for additional insights
- Two public APIs:
- GET /available-seats?start={station}&end={station}
- POST /reservations (user books a seat)
- Laravel Sanctum for API auth, seeders/migrations to bootstrap trips, buses, cities
- Admin UI at /admin uses Blade templates

a. Main components
- Client layer:
- Web browser (admin UI, Blade + JS assets)
- Mobile/web clients (consume JSON API via /api/* endpoints)
- API Gateway & Web Server:
- Nginx (or Sail’s default) routing incoming HTTP to PHP-FPM
- Application layer (Laravel)
- Routes (api.php vs web.php)
- Controllers (ReservationController, CityController, etc.)
- Services or Domain Logic (business rules for “can I book seat X?”)
- Models / Eloquent Repositories (Bus, City, Trip, TripsSeat, Reservations, User)
- Persistence layer:
- MySQL (database container) with tables for cities, trips, seats, reservations, users
- Infrastructure / DevOps
- Docker Compose orchestrating containers (PHP, MySQL, Node)
- Vite/Tailwind build container for front-end assets
- Scheduler / Queue (if used for notifications)

b. Relationships & interactions
- User → Nginx → Laravel (api.php) → ReservationController → Trip/Seat model → MySQL
- Admin UI: Browser → Nginx → Laravel (web.php) → Blade templates → DB
- Docker Compose: inter-container networking among PHP, DB, Node
- Sanctum issues tokens → used in API calls

c. Architectural patterns & design principles
- MVC (Controllers, Models, Views/JSON responses)
- Layered architecture (Presentation → Application → Domain → Infrastructure)
- Dependency inversion for config/services, use of factories for testing
- Containerization for environment parity (Docker)

d. Key technologies & frameworks
- PHP 8 + Laravel 10 (HTTP Kernel, Service Container, Eloquent ORM, Sanctum)
- MySQL (docker-compose)
- Docker & Laravel Sail
- Vite + Tailwind CSS + PostCSS for front-end assets
- PHPUnit for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web Browser (Admin UI)"]:::client
        APIClient["API Client (Mobile/Web)"]:::client
    end

    %% Infrastructure Layer
    subgraph "Docker Network" 
        direction TB
        Nginx["Nginx Reverse Proxy"]:::infra
        PHPFPM["PHP-FPM Container"]:::infra
        MySQL["MySQL Container"]:::db
        NodeVite["Node/Vite Build Container"]:::build
    end

    %% Laravel Application Layer inside PHP-FPM
    subgraph "Laravel Application" 
        direction TB
        Entrypoints["Entry Points"]:::app
        Router["Route Dispatcher"]:::app
        Controllers["Controllers"]:::app
        Services["Domain Services"]:::app
        Models["Eloquent Models"]:::app
        Configs["Configuration Files"]:::app
    end

    %% Relationships
    Browser -->|"HTTP /admin"| Nginx
    APIClient -->|"HTTP /api/*"| Nginx
    NodeVite -->|"Build Assets"| Nginx
    Nginx -->|"FastCGI"| PHPFPM
    PHPFPM -->|"handles"| Entrypoints
    Entrypoints -->|"load routes"| Router
    Router -->|"dispatch to"| Controllers
    Controllers -->|"use"| Services
    Services -->|"query/update"| Models
    Models -->|"SQL"| MySQL

    %% Click Events for Mappings
    click api.php "https://github.com/osama8809/bus-booking-system/blob/main/api.php"
    click web.php "https://github.com/osama8809/bus-booking-system/blob/main/web.php"
    click app.php "https://github.com/osama8809/bus-booking-system/blob/main/app.php"
    click artisan "https://github.com/osama8809/bus-booking-system/tree/main/artisan"
    click console.php "https://github.com/osama8809/bus-booking-system/blob/main/console.php"
    click ReservationsController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/ReservationsController.php"
    click RegisteredUserController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/RegisteredUserController.php"
    click VerifyEmailController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/VerifyEmailController.php"
    click AuthenticatedSessionController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/AuthenticatedSessionController.php"
    click PasswordResetLinkController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/PasswordResetLinkController.php"
    click NewPasswordController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/NewPasswordController.php"
    click ConfirmablePasswordController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/ConfirmablePasswordController.php"
    click EmailVerificationPromptController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/EmailVerificationPromptController.php"
    click EmailVerificationNotificationController.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Http/Controllers/EmailVerificationNotificationController.php"
    click Bus.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/Bus.php"
    click City.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/City.php"
    click Trip.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/Trip.php"
    click TripsSeat.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/TripsSeat.php"
    click Reservations.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/Reservations.php"
    click User.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/User.php"
    click TripsStation.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/TripsStation.php"
    click ReservationsStop.php "https://github.com/osama8809/bus-booking-system/blob/main/app/Models/ReservationsStop.php"
    click BusFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/BusFactory.php"
    click CityFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/CityFactory.php"
    click TripFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/TripFactory.php"
    click TripsSeatFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/TripsSeatFactory.php"
    click TripsStationFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/TripsStationFactory.php"
    click UserFactory.php "https://github.com/osama8809/bus-booking-system/blob/main/database/factories/UserFactory.php"
    click auth.php "https://github.com/osama8809/bus-booking-system/blob/main/config/auth.php"
    click sanctum.php "https://github.com/osama8809/bus-booking-system/blob/main/config/sanctum.php"
    click cors.php "https://github.com/osama8809/bus-booking-system/blob/main/config/cors.php"
    click hashing.php "https://github.com/osama8809/bus-booking-system/blob/main/config/hashing.php"
    click passwords.php "https://github.com/osama8809/bus-booking-system/blob/main/config/passwords.php"
    click session.php "https://github.com/osama8809/bus-booking-system/blob/main/config/session.php"
    click validation.php "https://github.com/osama8809/bus-booking-system/blob/main/config/validation.php"
    click database.php "https://github.com/osama8809/bus-booking-system/blob/main/config/database.php"
    click cache.php "https://github.com/osama8809/bus-booking-system/blob/main/config/cache.php"
    click queue.php "https://github.com/osama8809/bus-booking-system/blob/main/config/queue.php"
    click mail.php "https://github.com/osama8809/bus-booking-system/blob/main/config/mail.php"
    click logging.php "https://github.com/osama8809/bus-booking-system/blob/main/config/logging.php"
    click filesystems.php "https://github.com/osama8809/bus-booking-system/blob/main/config/filesystems.php"
    click services.php "https://github.com/osama8809/bus-booking-system/blob/main/config/services.php"
    click broadcasting.php "https://github.com/osama8809/bus-booking-system/blob/main/config/broadcasting.php"
    click channels.php "https://github.com/osama8809/bus-booking-system/blob/main/config/channels.php"
    click view.php "https://github.com/osama8809/bus-booking-system/blob/main/config/view.php"
    click pagination.php "https://github.com/osama8809/bus-booking-system/blob/main/config/pagination.php"
    click docker-compose.yml "https://github.com/osama8809/bus-booking-system/blob/main/docker-compose.yml"
    click package.json "https://github.com/osama8809/bus-booking-system/blob/main/package.json"
    click package-lock.json "https://github.com/osama8809/bus-booking-system/blob/main/package-lock.json"
    click vite.config.js "https://github.com/osama8809/bus-booking-system/blob/main/vite.config.js"
    click postcss.config.js "https://github.com/osama8809/bus-booking-system/blob/main/postcss.config.js"
    click tailwind.config.js "https://github.com/osama8809/bus-booking-system/blob/main/tailwind.config.js"
    click bus-seats-reservations.mwb "https://github.com/osama8809/bus-booking-system/blob/main/bus-seats-reservations.mwb"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef infra fill:#d4edda,stroke:#155724,color:#155724;
    classDef app fill:#fff3cd,stroke:#856404,color:#856404;
    classDef db fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef build fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
