1. The “Standard” Big Project Structure#

Here is how we are reorganizing our files today:

app/
├── __init__.py
├── main.py              # App initialization and router imports
├── database.py          # SQLAlchemy engine and session
├── config.py            # Pydantic Settings (.env)
├── security.py          # Security utilities (JWT, hashing)
├── dependencies.py      # Shared dependencies and background tasks
├── routers/
│   ├── __init__.py
│   ├── users.py         # Auth and User-related endpoints
│   ├── items.py         # Item-related endpoints
│   └── misc.py          # Miscellaneous endpoints (root, info, uploads)
├── models/
│   ├── __init__.py
│   ├── user.py          # SQLAlchemy models
│   └── item.py
└── schemas/
    ├── __init__.py
    ├── user.py          # Pydantic models (schemas)
    └── item.py

2. Using APIRouter#

Instead of attaching everything to app = FastAPI(), we create routers in separate files. This makes our code modular.

In routers/items.py:

from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
)

@router.get("/")
async def read_items():
    return [{"item_id": "Portal Gun"}]

In main.py:

from app.routers import items, users, misc

app = FastAPI()

app.include_router(users.router)
app.include_router(users.user_router)
app.include_router(items.router)
app.include_router(misc.router)

3. Why tags and prefix matter?#

• Prefix: Automatically adds /items to every route in that file. It saves typing and prevents errors.
• Tags: Automatically groups your endpoints in the Swagger UI under nice headings, making your documentation much easier to navigate.

🛠️ Implementation Checklist#

• Created the app/ directory and moved logic into subfolders.
• Split Pydantic schemas from SQLAlchemy models.
• Implemented APIRouter for Items and Users.
• Updated all imports to reflect the new structure (using absolute imports like app.models.item).
• Verified that the API still runs and the /docs look more organized than ever.

📚 Resources#

1. Official Docs: FastAPI Bigger Applications - Multiple Files
2. Blog: FastAPI Best Practices (Architecture)