name: fastapi-web-framework description: Create FastAPI web server with standard middleware, JWT authentication, and REST API endpoints license: MIT compatibility: opencode,claude metadata: created_at: "2026-01-29T23:01:15.231Z" updated_at: "2026-01-29T23:01:15.231Z" version: "1"

Purpose

Create a FastAPI web server with standard production-ready middleware and authentication.

When To Use

• Building FastAPI web backend
• Creating API server for web frontend
• Ticket requires web framework implementation

Procedure

Dependencies

Add to pyproject.toml:

fastapi>=0.128.0
uvicorn[standard]>=0.40.0
python-jose[cryptography]>=3.5.0
passlib[bcrypt]>=1.7.4
python-multipart>=0.0.22
email-validator>=2.0.0

Project Structure

src/vibe_piper/web/
├── __init__.py              # Main FastAPI app
├── api/
│   ├── router.py             # API router
│   └── endpoints/
│       ├── auth.py          # Authentication endpoints
│       ├── health.py        # Health check endpoints
│       └── pipelines.py     # Feature endpoints
└── middleware/
    ├── error_handler.py   # Structured error handling
    ├── rate_limit.py     # Rate limiting
    └── request_id.py     # Request ID for tracing

App Creation

src/vibe_piper/web/__init__.py:

from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

from vibe_piper.web.api.router import api_router
from vibe_piper.web.middleware.error_handler import add_error_handlers
from vibe_piper.web.middleware.rate_limit import RateLimitMiddleware
from vibe_piper.web.middleware.request_id import RequestIDMiddleware

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield

def create_app() -> FastAPI:
    app = FastAPI(
        title="API Name",
        version="0.1.0",
        docs_url="/docs",
        lifespan=lifespan,
    )

    app.add_middleware(CORSMiddleware, allow_origins=["http://localhost:5173"])
    app.add_middleware(GZipMiddleware, minimum_size=1000)
    app.add_middleware(RequestIDMiddleware)
    app.add_middleware(RateLimitMiddleware)
    add_error_handlers(app)
    app.include_router(api_router, prefix="/api/v1")

    return app

app = create_app()

Authentication

Use JWT with python-jose:

• SECRET_KEY from env (production)
• ACCESS_TOKEN_EXPIRE_MINUTES = 30
• REFRESH_TOKEN_EXPIRE_DAYS = 7
• bcrypt for password hashing
• OAuth2PasswordBearer for token scheme

Error Handling

Create structured error responses:

class ErrorResponse(BaseModel):
    error: str
    message: str
    detail: dict | None
    request_id: str | None

Rate Limiting

Token bucket algorithm:

• 60 requests per minute
• 1000 requests per hour
• Client by IP or X-Forwarded-For

Testing

uv run vibepiper-server --reload
curl http://127.0.0.1:8000/api/v1/health

Acceptance Criteria

• FastAPI server runs on port 8000
• CORS configured for frontend
• JWT authentication implemented
• Rate limiting configured
• Structured error responses
• OpenAPI/Swagger UI at /docs

Manual notes

This section is preserved when the skill is updated. Put human notes, caveats, and exceptions here.