2. Project Structure & Application Lifecycle

Minimal vs Scalable Folder Structure

A minimal FastAPI application often begins as a single-file project, which is effective for rapid experimentation and learning. As the codebase grows, a scalable folder structure becomes essential to separate routing, schemas, services, and infrastructure layers. This separation reduces coupling and enables teams to extend functionality without destabilizing existing features.

---

main.py vs Modular Applications

The main.py file serves as the application entry point, responsible for instantiating the FastAPI app and wiring high-level components. In production systems, route definitions and business logic are organized into modules and included via routers. This modular approach improves clarity, testability, and parallel development across teams.

from fastapi import FastAPI
from app.routes import users

app = FastAPI()
app.include_router(users.router)

---

Startup and Shutdown Events

FastAPI provides lifecycle hooks that execute code during application startup and shutdown phases. These hooks are commonly used to initialize database connections, warm caches, or release resources gracefully. Proper lifecycle management ensures predictable behavior during deployments, restarts, and scaling events.

from fastapi import FastAPI

app = FastAPI()

@app.on_event("startup")
async def startup():
    print("Starting application")

@app.on_event("shutdown")
async def shutdown():
    print("Shutting down application")

---

Environment-Driven Configuration

FastAPI applications typically rely on environment variables to manage configuration across environments. This approach decouples configuration from source code and supports clean separation between development, staging, and production. Typed configuration models add validation and prevent misconfiguration at runtime.

from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "FastAPI Service"
    debug: bool = False

settings = Settings()