# blazkull/app-reservation-hotel-web architecture

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

- Interactive diagram: https://gitdiagram.com/blazkull/app-reservation-hotel-web
- Repository: https://github.com/blazkull/app-reservation-hotel-web

## Overview

##### Project type and purpose
- This is a full-stack backend application (a RESTful API) for hotel reservation management, built with FastAPI, SQLAlchemy (ORM), MySQL, and Pydantic.
- Its purpose is to expose endpoints to manage rooms, clients, reservations, users, and related lookup/status tables, consumable by any HTTP client or frontend.

##### File structure
- Top-level files
- README.md, LICENSE, .gitignore, requirements.txt, script_create_db_…sql
- .env (holds DATABASE_URL)
- Directories
- app/ — entry point (main.py) that boots FastAPI (Uvicorn)
- core/ — central configuration and database connection (config.py, database.py)
- models/ — SQLAlchemy ORM models (client, reservation, room, user, types & statuses)
- routers/ — FastAPI routers for each resource (clients, reservations, rooms, users, dashboards, login)
- Key patterns
- Layered architecture: routers (API layer) → core (infrastructure) → models (persistence) → MySQL
- Configuration via environment variables
- Automatic table creation via SQLAlchemy on startup
- External scripts to bootstrap the database

##### README for additional insights
- Technology stack: Python 3.10+, FastAPI, MySQL 8+, SQLAlchemy, Pydantic, Uvicorn
- Endpoints documented in Swagger UI (/docs) and ReDoc (/redoc)
- Step-by-step setup instructions

a. Main components
- Client/Consumer (Web frontend, Mobile app, Postman/Swagger UI)
- API Layer (FastAPI + Uvicorn server in app/main.py)
- Router modules (one per resource)
- Business logic & validation (Pydantic schemas + dependency injection)
- Infrastructure layer (core/config.py, core/database.py)
- ORM layer (models/*.py using SQLAlchemy)
- Relational Database (MySQL)
- External scripts (SQL bootstrap script)
- Documentation interfaces (Swagger UI, ReDoc)
b. Relationships & interactions
1. Client sends HTTP request → Uvicorn/ASGI
2. FastAPI dispatches to the correct router
3. Router function validates input with Pydantic models
4. Router calls SQLAlchemy session (from core/database.py)
5. ORM maps Python objects to MySQL tables
6. Query results return up the stack → response model → HTTP response
7. Swagger UI/ReDoc query the OpenAPI schema auto-generated by FastAPI
c. Architectural patterns & principles
- Layered separation of concerns: Presentation (routers) vs Domain (models) vs Infrastructure (DB)
- Dependency injection (FastAPI) for config & DB sessions
- Declarative ORM mapping (SQLAlchemy)
- Data validation & serialization (Pydantic)
- Environment-driven configuration (.env, core/config.py)
- FastAPI (API framework)
- Uvicorn (ASGI server)
- Pydantic (request/response schemas)
- SQLAlchemy (ORM)
- MySQL (database)
- Python-dotenv or os.environ for config

##### Essential architectural elements
- Don’t just show “API → DB”—break the API block into Uvicorn server, routers, Pydantic schemas, and core database connector
- Resource router (clients, rooms, reservations, users, statuses) to reflect modularity
- Explicitly show the automatic table-generation via SQLAlchemy on startup
- External SQL script as part of your “Database Initialization” component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["HTTP Client<br/>(Web/Mobile/Postman)"]:::external
    Client -->|HTTP Request| Uvicorn

    %% API Layer
    subgraph "API Layer"
        Uvicorn["Uvicorn ASGI Server<br>app/main.py"]:::api
        click Uvicorn "https://github.com/blazkull/app-reservation-hotel-web/blob/main/app/main.py"
        Uvicorn -->|dispatch to| Routers
    end

    subgraph "API Routers"
        Routers["FastAPI Routers"]:::api
        Routers -->|routes| ClientsRouter
        Routers --> ReservationsRouter
        Routers --> RoomRouter
        Routers --> RoomStatusRouter
        Routers --> RoomTypesRouter
        Routers --> UsersRouter
        Routers --> UserTypesRouter
        Routers --> ReservationStatuesRouter
        Routers --> DashboardRouter
        Routers --> LoginRouter

        ClientsRouter["clients.py"]:::api
        click ClientsRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/clients.py"
        ReservationsRouter["reservations.py"]:::api
        click ReservationsRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/reservations.py"
        RoomRouter["room.py"]:::api
        click RoomRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/room.py"
        RoomStatusRouter["roomstatus.py"]:::api
        click RoomStatusRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/roomstatus.py"
        RoomTypesRouter["roomtypes.py"]:::api
        click RoomTypesRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/roomtypes.py"
        UsersRouter["users.py"]:::api
        click UsersRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/users.py"
        UserTypesRouter["usertypes.py"]:::api
        click UserTypesRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/usertypes.py"
        ReservationStatuesRouter["reservation_statues.py"]:::api
        click ReservationStatuesRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/reservation_statues.py"
        DashboardRouter["dashboard.py"]:::api
        click DashboardRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/dashboard.py"
        LoginRouter["login.py"]:::api
        click LoginRouter "https://github.com/blazkull/app-reservation-hotel-web/blob/main/routers/login.py"
    end

    %% Documentation UIs
    Uvicorn -->|serves| SwaggerUI
    Uvicorn -->|serves| ReDoc
    SwaggerUI["Swagger UI<br>/docs"]:::docs
    ReDoc["ReDoc<br>/redoc"]:::docs

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Config["config.py"]:::infra
        click Config "https://github.com/blazkull/app-reservation-hotel-web/blob/main/core/config.py"
        DBConnector["database.py"]:::infra
        click DBConnector "https://github.com/blazkull/app-reservation-hotel-web/blob/main/core/database.py"
        Routers -->|get DB Session| DBConnector
    end

    %% ORM Models
    subgraph "ORM Models"
        ClientModel["client.py"]:::data
        click ClientModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/client.py"
        ReservationModel["reservation.py"]:::data
        click ReservationModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/reservation.py"
        ReservationStatusModel["reservation_status.py"]:::data
        click ReservationStatusModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/reservation_status.py"
        RoomModel["room.py"]:::data
        click RoomModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/room.py"
        RoomStatusModel["room_status.py"]:::data
        click RoomStatusModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/room_status.py"
        RoomTypeModel["room_type.py"]:::data
        click RoomTypeModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/room_type.py"
        UserModel["user.py"]:::data
        click UserModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/user.py"
        UserTypeModel["user_type.py"]:::data
        click UserTypeModel "https://github.com/blazkull/app-reservation-hotel-web/blob/main/models/user_type.py"
    end
    DBConnector -->|SQLAlchemy Session| ClientModel
    DBConnector --> ReservationModel
    DBConnector --> ReservationStatusModel
    DBConnector --> RoomModel
    DBConnector --> RoomStatusModel
    DBConnector --> RoomTypeModel
    DBConnector --> UserModel
    DBConnector --> UserTypeModel

    %% Database
    MySQL["MySQL Database"]:::data
    ClientModel -->|ORM Mapping| MySQL
    ReservationModel --> MySQL
    ReservationStatusModel --> MySQL
    RoomModel --> MySQL
    RoomStatusModel --> MySQL
    RoomTypeModel --> MySQL
    UserModel --> MySQL
    UserTypeModel --> MySQL

    %% Initialization Script
    Script["DB Init Script<br>script_create_db_reservation_hotel_and_insert_data.sql"]:::data
    click Script "https://github.com/blazkull/app-reservation-hotel-web/blob/main/script_create_db_reservation_hotel_and_insert_data.sql"
    Script -->|initializes| MySQL

    %% Documentation
    README["README.md"]:::docs
    click README "https://github.com/blazkull/app-reservation-hotel-web/blob/main/README.md"

    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef infra fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef docs fill:#FFB6C1,stroke:#333,stroke-width:1px
```
