FastAPI: Routers, layers & project structure

Tutorials put everything in main.py. Real services outgrow that within weeks. The structure that lasts has three ideas: routers group endpoints by resource, an app factory builds the application (so tests can build their own), and layers keep HTTP, business rules and persistence apart, so each can change and be tested on its own. This part builds that structure as real files and runs it.

1. The layers

2. Build it for real

This example writes a small package with a router, a service, a repository, shared schemas and an app factory, then imports and exercises it:

a layered FastAPI package, written to disk and tested

from pathlib import Path

files = {
    "app/__init__.py": "",
    "app/schemas.py": '''
from pydantic import BaseModel, ConfigDict, Field
class OrderCreate(BaseModel):
    model_config = ConfigDict(extra="forbid")
    sku: str
    qty: int = Field(gt=0, le=50)
class OrderRead(BaseModel):
    id: int
    sku: str
    qty: int
    status: str
''',
    "app/errors.py": '''
class DomainError(Exception): pass
class NotFound(DomainError): pass
class OutOfStock(DomainError): pass
''',
    "app/repository.py": '''
class OrderRepository:                       # in-memory here; SQLAlchemy in lesson 15
    def __init__(self):
        self.rows, self.next_id = {}, 1
    def add(self, sku, qty):
        row = {"id": self.next_id, "sku": sku, "qty": qty, "status": "pending"}
        self.rows[row["id"]] = row
        self.next_id += 1
        return row
    def get(self, order_id):
        return self.rows.get(order_id)
''',
    "app/service.py": '''
from app.errors import NotFound, OutOfStock
STOCK = {"TEA-01": 5, "MLK-02": 0}
class OrderService:                          # business rules, no HTTP anywhere
    def __init__(self, repo):
        self.repo = repo
    def place(self, sku, qty):
        if STOCK.get(sku, 0) < qty:
            raise OutOfStock(f"only {STOCK.get(sku, 0)} of {sku} left")
        STOCK[sku] -= qty
        return self.repo.add(sku, qty)
    def get(self, order_id):
        row = self.repo.get(order_id)
        if row is None:
            raise NotFound(f"order {order_id} not found")
        return row
''',
    "app/api/__init__.py": "",
    "app/api/orders.py": '''
from typing import Annotated
from fastapi import APIRouter, Depends, Request, Response, status
from app.schemas import OrderCreate, OrderRead
from app.service import OrderService

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

def get_service(request: Request) -> OrderService:
    return request.app.state.order_service      # built once by the factory

Service = Annotated[OrderService, Depends(get_service)]

@router.post("", status_code=status.HTTP_201_CREATED)
def place_order(body: OrderCreate, service: Service, request: Request, response: Response) -> OrderRead:
    order = service.place(body.sku, body.qty)
    response.headers["Location"] = str(request.url_for("get_order", order_id=order["id"]))
    return order

@router.get("/{order_id}", name="get_order")
def get_order(order_id: int, service: Service) -> OrderRead:
    return service.get(order_id)
''',
    "app/main.py": '''
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from app.api import orders
from app.errors import NotFound, OutOfStock
from app.repository import OrderRepository
from app.service import OrderService

def create_app() -> FastAPI:                    # the app factory: tests call it for a fresh app
    app = FastAPI(title="Orders API")
    app.state.order_service = OrderService(OrderRepository())
    app.include_router(orders.router, prefix="/v1")

    @app.exception_handler(NotFound)              # domain error → HTTP, in exactly one place
    async def not_found(request, exc):
        return JSONResponse({"detail": str(exc)}, status_code=404)

    @app.exception_handler(OutOfStock)
    async def out_of_stock(request, exc):
        return JSONResponse({"detail": str(exc)}, status_code=409)
    return app
''',
}
for name, text in files.items():
    Path(name).parent.mkdir(parents=True, exist_ok=True)
    Path(name).write_text(text.lstrip("\n"), encoding="utf-8")

from fastapi.testclient import TestClient
from app.main import create_app

client = TestClient(create_app())
r = client.post("/v1/orders", json={"sku": "TEA-01", "qty": 2})
print(r.status_code, r.json(), "Location:", r.headers["location"])
print(client.get("/v1/orders/1").json())
print(client.get("/v1/orders/99").status_code, client.get("/v1/orders/99").json())
print(client.post("/v1/orders", json={"sku": "MLK-02", "qty": 1}).json())

app = create_app()
print("app.routes holds:", sorted({type(r).__name__ for r in app.routes}))    # a tree, not a flat list
print("public paths:", sorted(p for p in app.openapi()["paths"]))            # list endpoints this way

Output

201 {'id': 1, 'sku': 'TEA-01', 'qty': 2, 'status': 'pending'} Location: http://testserver/v1/orders/1
{'id': 1, 'sku': 'TEA-01', 'qty': 2, 'status': 'pending'}
404 {'detail': 'order 99 not found'}
{'detail': 'only 0 of MLK-02 left'}
app.routes holds: ['Route', '_IncludedRouter']
public paths: ['/v1/orders', '/v1/orders/{order_id}']

3. Router features worth knowing

4. Organise by layer or by feature?

app/
api/ orders.py users.py
services/ orders.py users.py
db/ models.py repositories.py
schemas/ orders.py users.py

app/
orders/ router.py service.py
repository.py schemas.py
users/  router.py service.py …
core/   settings.py db.py errors.py

Either works. What matters is that the direction of imports stays one-way, that shared things live in core, and that the choice is consistent. A feature layout scales better once several teams own different parts, because everything about “orders” is in one folder.

5. Why an app factory

serving a factory

uvicorn "app.main:create_app" --factory      # uvicorn calls the factory itself
# or keep a module-level instance for tools that need one:   app = create_app()

Recap