architecture

Layer Architecture Rules

This codebase follows strict 4-layer architecture: Router → Service → Repository → ORM/HTTP/Storage. Imports flow downward only. Each layer has hard boundaries you must NOT cross.

Hard Rules

1. Router files (app/routers/**)

• Handlers are thin: ≤10 lines of executable code per handler.
• Allowed imports: fastapi, app.schemas.*, app.core.deps, app.services.*.
• Forbidden imports: sqlalchemy, httpx, boto3, app.models.*, app.repositories.* (except via Depends).
• Every endpoint declares response_model= for OpenAPI fidelity.
• Every endpoint (except /auth/*) requires user_id: str = Depends(get_current_user_id).
• Business logic lives in services. Routers parse input, call one service method, return a response.

# ✅ GOOD
@router.post("/wallet/charge", response_model=WalletResponse, status_code=201)
async def charge(
    req: ChargeRequest,
    user_id: str = Depends(get_current_user_id),
    svc: WalletUserService = Depends(get_wallet_service),
) -> WalletResponse:
    wallet = await svc.charge(user_id=user_id, amount=req.amount, key=req.idempotency_key)
    return WalletResponse.from_domain(wallet)

# ❌ BAD — business logic and SQL in router
@router.post("/wallet/charge")
async def charge(req: ChargeRequest, db: Session = Depends(get_db)):
    wallet = db.query(Wallet).filter(Wallet.user_id == user_id).with_for_update().one()
    if wallet.balance < req.amount:
        raise HTTPException(402)
    wallet.balance -= req.amount
    db.commit()
    return wallet

2. Service files (app/services/**)

• Forbidden imports: sqlalchemy, httpx, boto3, redis, FastAPI Request/Response/HTTPException.
• Allowed imports: app.repositories.protocols, app.providers._types, app.domain.*, stdlib, Pydantic.
• Services raise domain exceptions (e.g. InsufficientFundsError); routers map them to HTTP.
• Constructor injects Protocol-typed dependencies, not concrete classes.