App factory, lifespan et injection de dépendances

create_app() : l'assembleur

Le package api/ ne contient presque aucune logique : c'est l'assembleur. Sa fonction create_app() construit l'application en montant les routers de chaque module :

def create_app() -> FastAPI:
    app = FastAPI(lifespan=lifespan)
    app.add_middleware(CORSMiddleware, ...)
    app.add_middleware(AuthMiddleware)          # JWT → tenant_id (module 3)
    app.include_router(copilot_router,  prefix="/api/copilot")
    app.include_router(catalog_router,  prefix="/api/catalog")
    app.include_router(engine_router)           # /extract, /jobs/{id}
    return app

Chaque module expose son router.py (la couche HTTP) qui délègue à ses services/ (le métier). Trois couches, pas plus : router → service → shared.

lifespan : le câblage au démarrage

Le lifespan (async context manager) remplace les vieux startup/shutdown events. C'est là que tout se branche :

@asynccontextmanager
async def lifespan(app: FastAPI):
    engine = create_async_engine(DATABASE_URL, pool_pre_ping=True)
    checkpointer = await setup_postgres_checkpointer()      # LangGraph, module 6
    app.state.copilot_service = CopilotService(
        catalog=LocalCatalogProvider(...),     # les Protocols du module 0,
        prices=LocalPriceProvider(...),        # câblés ICI et nulle part ailleurs
    )
    reconciler = asyncio.create_task(job_reconcile_loop())  # boucles de fond
    yield                                                    # ← l'app tourne
    reconciler.cancel()                                      # arrêt propre
    await engine.dispose()

L'injection du projet est volontairement simple : pas de conteneur DI magique — les dépendances vivent sur app.state, posées une fois au boot, lues par les handlers via request.app.state. Explicite, typé, testable (en test on pose des fakes sur app.state).

Les middlewares : l'oignon

Chaque requête traverse, dans l'ordre : sécurité (headers) → logs structurés (structlog, un JSON par requête) → métriques RED (rate/errors/duration, exposées pour Prometheus) → auth (valide le JWT, résout le tenant_id, le pose sur request.state) → le router. Le tenant_id posé ici est LA donnée que tout le reste consomme — module suivant.