repoforge: Skill for Claude Code

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.

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/