<!-- L1:START -->

backend-layer

The Python FastAPI backend layer for RepoForge Web, handling HTTP routing, middleware, authentication, rate limiting, and database migrations. Owns all server-side request processing and API endpoints.

Trigger: When working in backend/ directory — adding routes, modifying middleware, debugging authentication, or extending API endpoints.

<!-- L1:END --> <!-- L2:START -->

Quick Reference

Task	Pattern
Run migrations	cd apps/server && alembic upgrade head
Start server	uvicorn apps.server.main:app --reload
Test endpoints	pytest apps/server/tests/

Critical Patterns (Summary)

• Middleware Chain: FastAPI middleware runs in order — correlation_id → request_logging → security_headers. Each must call call_next to pass control.
• Settings Fail-Fast: Settings from config.py validates required env vars on startup; missing vars cause immediate exit.

Critical Patterns (Detailed)

Middleware Chain

FastAPI middleware executes in declaration order. Each handler must invoke call_next to forward the request; omitting this breaks the chain and returns 500 errors.

@app.middleware("http")
async def security_headers_middleware(request: Request, call_next):  # noqa: ANN001
    response = await call_next(request)
    response.headers["X-Content-Type-Options"] = "nosniff"
    return response

Settings Fail-Fast

from apps.server.app.config import Settings

settings = Settings()  # Raises ValueError if required vars missing

When to Use

• Adding new HTTP routes or API endpoints
• Modifying request validation or authentication flow
• Configuring rate limits or adding middleware
• Running or writing database migrations

Adding a New middleware

1. Create <name>.py in apps/server/app/middleware/
2. Export a FastAPI dependency or middleware function following existing pattern
3. Add to middleware chain in apps/server/app/main.py if needed
4. Verify with pytest apps/server/tests/middleware/

Commands

cd apps/server && alembic upgrade head       # Run migrations
uvicorn apps.server.main:app --reload        # Start dev server
pytest apps/server/tests/                    # Run test suite

Anti-Patterns

Don't: Skip call_next in middleware

@app.middleware("http")
async def bad_middleware(request: Request, call_next):
    # BUG: Missing call_next — request never proceeds
    return JSONResponse({"error": "chain broken"}, status_code=500)

Why: Without calling call_next, the middleware short-circuits the entire request pipeline, returning a 500 error to the client and breaking all downstream handlers.

<!-- L3:END -->