From 6a4c8ead5fcf9c5e08d254bc7aa6480e3b7c34d7 Mon Sep 17 00:00:00 2001
From: Trevin Chow <trevin@trevinchow.com>
Date: Mon, 6 Apr 2026 00:33:45 -0700
Subject: [PATCH] docs: add FastAPI integration lifecycle sequence diagrams

Add mermaid sequence diagrams to the FastAPI integration page showing:

1. App lifecycle: container creation, setup, route injection, and teardown
2. Per-request lifecycle: scope creation, dependency resolution, handler
   execution, and cleanup

Closes #120
---
 docs/pages/integrations/fastapi/index.md | 61 ++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/pages/integrations/fastapi/index.md b/docs/pages/integrations/fastapi/index.md
index dd2d78bd..a0ccf0b9 100644
--- a/docs/pages/integrations/fastapi/index.md
+++ b/docs/pages/integrations/fastapi/index.md
@@ -86,6 +86,67 @@ Run the server with:
 fastapi dev main.py
 ```
 
+## Lifecycle
+
+Wireup integrates with FastAPI at two levels: once during application startup/shutdown, and once per incoming request.
+
+### App Lifecycle
+
+Container creation, route injection, and teardown.
+
+```mermaid
+sequenceDiagram
+    participant App as Application Code
+    participant Container as Wireup Container
+    participant Integration as wireup.integration.fastapi
+    participant FastAPI
+
+    App->>Container: wireup.create_async_container(injectables=[...])
+    App->>Integration: setup(container, app)
+    Integration->>FastAPI: Store container on app.state
+    Integration->>Integration: Update lifespan context
+    Integration->>FastAPI: Inject existing routes
+
+    Note over FastAPI: App startup
+    FastAPI->>Integration: Lifespan enter
+    Integration->>Integration: Instantiate class-based routes (if any)
+    Integration->>FastAPI: Inject routes (idempotent)
+    Integration-->>FastAPI: Yield to app lifespan
+
+    Note over FastAPI: App running, handling requests...
+
+    Note over FastAPI: App shutdown
+    FastAPI->>Integration: Lifespan exit
+    Integration->>Container: container.close()
+    Container-->>Integration: Resources cleaned up
+```
+
+### Per-Request Lifecycle
+
+Scope creation, dependency resolution, and cleanup for a single HTTP request.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant FastAPI
+    participant Wireup as Injection Wrapper
+    participant Container as Scoped Container
+    participant Handler as Route Handler
+
+    Client->>FastAPI: HTTP Request
+    FastAPI->>Wireup: Route matched, call handler
+    Wireup->>Wireup: Extract Request from kwargs
+    Wireup->>Container: Create request scope
+    Container->>Container: Resolve Injected[T] parameters
+    Container-->>Wireup: Resolved dependencies
+    Wireup->>Handler: Call with resolved dependencies
+    Handler-->>Wireup: Response
+    Wireup->>Container: Exit request scope
+    Container->>Container: Clean up request-scoped resources
+    Wireup-->>FastAPI: Return response
+    FastAPI-->>Client: HTTP Response
+```
+
 ## Detailed Guides
 
 - [Inject in Routes](inject_in_routes.md): HTTP/WebSocket handler injection and config value injection in route signatures.