FastAPI Clean Base Recipe

A production-ready, modular, and lightweight foundation for modern FastAPI applications. Designed for developers who need a clean architectural pattern with separated routing, central environment configuration, and strict module boundaries without bloat.

🏗️ Architecture Overview

This recipe scaffolds a predictable, decoupled layout following Python/FastAPI best practices:

app/
├── api/
│   ├── endpoints/
│   │   └── health.py    # Route controller definitions
│   └── router.py        # Central API Router aggregator
├── core/
│   └── config.py        # Pydantic Settings with .env parsing
└── main.py              # Application entrypoint & Lifecycle

🚀 Installation & Automated Setup

You don't need to manually install dependencies or set up file structures. The Nex CLI handles everything out of the box using the recipe manifest:

xnex install fastapi-clean

What Happens Automatically Behind the Scenes:

1. Scaffolding: Downloads and places the modular app/ architecture into your current working directory.
2. Dependencies: Automatically executes pip install using the recipe's requirements.txt.
3. Dev Server: Launches the live development server instantly.

⚙️ Configuration & Execution

Environment Variables

Optionally create a .env file in your root directory to override default settings:

PROJECT_NAME="FastAPI Clean App"
API_STR="/api"

Running the Application

If you need to start the development server manually in the future:

fastapi dev app/main.py

Access the interactive Swagger API documentation at: http://127.0.0.1:8000/docs

🧩 Deep-Dive Code Examples

1. Settings Management (app/core/config.py)

Uses pydantic-settings to parse environment variables securely while ignoring unexpected system input.

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    PROJECT_NAME: str = "FastAPI Clean Architecture"
    API_STR: str = "/api"

    # Ignores unknown extra environment variables (e.g., NODE_ENV)
    model_config = SettingsConfigDict(
        env_file=".env",
        extra="ignore"
    )

settings = Settings()

2. Endpoint Logic (app/api/endpoints/health.py)

Define domain-specific route handlers in separate files inside endpoints/.

from fastapi import APIRouter

router = APIRouter()

@router.get("/health", tags=["System"])
async def health_check():
    return {
        "status": "ok",
        "message": "Service is up and running"
    }

3. Router Aggregator (app/api/router.py)

Combines isolated endpoint modules into a unified router module.

from fastapi import APIRouter
from api.endpoints import health

api_router = APIRouter()
api_router.include_router(health.router)

4. Application Entry (app/main.py)

Attaches the aggregated router and configures global application settings.

from fastapi import FastAPI
from core.config import settings
from api.router import api_router

app = FastAPI(
    title=settings.PROJECT_NAME,
    openapi_url=f"{settings.API_STR}/openapi.json"
)

# Register top-level API routes under configured prefix
app.include_router(api_router, prefix=settings.API_STR)

🛠️ Adding New Endpoints

To extend this base structure:

1. Add a new route handler in app/api/endpoints/ (e.g., users.py).
2. Define an APIRouter() instance inside users.py.
3. Register it inside app/api/router.py:

from api.endpoints import users
api_router.include_router(users.router, prefix="/users", tags=["Users"])