How blazkull/app-reservation-hotel-web works
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