How ashbhat/boilerplate_fastapi works
Project Type and Purpose
• This is a FastAPI boilerplate/project template for building a backend HTTP API.
• It uses Uvicorn to serve the application, SQLAlchemy + Alembic for DB migrations, and Postgres as the persistence layer.
• Its purpose is to let a developer clone the template, define new “sample”-style modules, run migrations, and have a working API immediately.
File Structure
• Top-level:
• main.py – entry point configuring FastAPI and mounting routers
• alembic.ini + _meta/_migrations/… – Alembic configuration and revision scripts
• api/
– router.py – central API router
– sample/
• controllers.py – request handlers
• services.py – business-logic layer
• models.py – SQLAlchemy ORM definitions
• schemas.py – Pydantic request/response schemas
• Requirements.txt drives installed frameworks; shortcuts.sh simplifies common commands.
• No separate “frontend” directory—this is backend-only.
README
• Describes environment setup (Conda, pip install).
• Walks through Postgres creation, .env variables, and running Alembic migrations.
• Starts the server with “uvicorn main:app --reload --port 8001”.
Main Components
a. External Client(s) – e.g. Browser, Mobile App, API Consumer
b. Uvicorn Server + FastAPI App (main.py)
c. API Router (api/router.py)
d. Domain Module (“sample”):
• Controllers
• Services
• Schemas
• Models
e. Database (Postgres)
f. Migration Engine (Alembic)
g. Configuration (.env, alembic.ini)
Relationships and Data Flow
• Client → HTTP request → Uvicorn/FastAPI
• FastAPI → Router → Controller
• Controller → Service → Model (SQLAlchemy ORM)
• Model → SQL operations → Postgres
• Alembic CLI → Migration scripts → Postgres
• Configuration files inject DB credentials into the app and Alembic.
Architectural Patterns and Principles
• Layered architecture (Presentation / API layer, Business logic layer, Data access layer).
• Clear separation of concerns: routers map paths to controllers; controllers orchestrate services; services encapsulate business rules; models define the schema.
• Declarative validation via Pydantic schemas.
• Migrations decoupled from runtime code—version-controlled scripts.
– Router (api/router.py)
– Controllers (api/sample/controllers.py)
– Services (api/sample/services.py)
– Schemas & Models (api/sample/schemas.py & models.py)
6. .env / alembic.ini as a config block feeding both the FastAPI app and Alembic.
7. Port 8001 on the server and DB port 5432 on the DB.