Copilot instructions

1---
2applyTo: "**/routers/**/*.py, **/routes/**/*.py, **/api/**/*.py, **/main.py, **/app.py"
3---
4 
5## Context
6 
7This instruction file applies to FastAPI application files — routers, schemas, dependencies, middleware, and the application factory. The project uses FastAPI 0.111+ with Pydantic v2 for request/response validation. All routes must be `async def`, return typed Pydantic models, and use RFC 7807 `ProblemDetail` for error responses. OpenAPI documentation is auto-generated; keep schema names meaningful and descriptions accurate.
8 
9---
10 
11## Coding Standards
12 
13- **All routes `async def`:** Never `def` (synchronous) for route handlers — use `async def` with `await`
14- **Explicit `response_model=`:** Every route declares `response_model=` and `status_code=`
15- **Pydantic v2 schemas:** Request and response models inherit from `pydantic.BaseModel`; use `model_config` for settings
16- **`Annotated[T, Depends()]` injection:** Prefer `Annotated` dependency aliases over bare `Depends()` in signatures
17- **RFC 7807 errors:** Domain errors translate to `ProblemDetail` (type, title, status, detail, instance); never return raw strings
18- **Router organisation:** One `APIRouter` per bounded context; mount routers in `app.py` — no routes in `main.py`
19- **Versioned paths:** All routes under `/v{n}/` prefix — e.g. `/v1/orders`
20- **`BaseSettings` for config:** No hardcoded URLs, credentials, or feature flags in route code
21- **Lifespan events:** Use `@asynccontextmanager` `lifespan` parameter — never deprecated `on_startup`/`on_shutdown`
22 
23---
24 
25## Preferred Patterns
26 
27### Router with Typed Response
28 
29```python
30# ✅ CORRECT
31from typing import Annotated
32from fastapi import APIRouter, Depends, HTTPException, status
33from app.dependencies import get_order_service
34from app.schemas.orders import CreateOrderRequest, OrderResponse
35from app.services.orders import OrderService
36 
37router = APIRouter(prefix="/v1/orders", tags=["orders"])
38 
39OrderServiceDep = Annotated[OrderService, Depends(get_order_service)]
40 
41@router.post("/", response_model=OrderResponse, status_code=status.HTTP_201_CREATED)
42async def create_order(body: CreateOrderRequest, service: OrderServiceDep) -> OrderResponse:
43    result = await service.place_order(body.to_command())
44    return OrderResponse.from_domain(result)
45 
46# ❌ WRONG — synchronous, no response_model, raw dict return
47@router.post("/orders")
48def create_order(body: dict):
49    return {"id": "123"}
50```
51 
52### RFC 7807 Error Handler
53 
54```python
55# ✅ CORRECT — global exception handler in app.py
56from fastapi import Request
57from fastapi.responses import JSONResponse
58 
59class DomainError(Exception):
60    def __init__(self, message: str, status_code: int = 400) -> None:
61        self.message = message
62        self.status_code = status_code
63 
64@app.exception_handler(DomainError)
65async def domain_error_handler(request: Request, exc: DomainError) -> JSONResponse:
66    return JSONResponse(
67        status_code=exc.status_code,
68        content={
69            "type": "https://api.example.com/errors/domain-error",
70            "title": "Domain Error",
71            "status": exc.status_code,
72            "detail": exc.message,
73            "instance": str(request.url),
74        },
75        media_type="application/problem+json",
76    )
77```
78 
79### Pydantic v2 Request/Response Schema
80 
81```python
82# ✅ CORRECT — Pydantic v2 with model_config
83from datetime import datetime
84from pydantic import BaseModel, ConfigDict, field_validator
85 
86class CreateOrderRequest(BaseModel):
87    model_config = ConfigDict(str_strip_whitespace=True)
88 
89    customer_id: str
90    items: list[OrderLineItem]
91    currency: str = "GBP"
92 
93    @field_validator("currency")
94    @classmethod
95    def validate_currency(cls, v: str) -> str:
96        if v not in {"GBP", "USD", "EUR"}:
97            raise ValueError(f"Unsupported currency: {v}")
98        return v
99 
100class OrderResponse(BaseModel):
101    model_config = ConfigDict(from_attributes=True)
102 
103    order_id: str
104    status: str
105    created_at: datetime
106 
107    @classmethod
108    def from_domain(cls, order: Order) -> "OrderResponse":
109        return cls(order_id=str(order.id), status=order.status.value, created_at=order.created_at)
110```
111 
112### Dependency Injection with Lifespan
113 
114```python
115# ✅ CORRECT — lifespan manages resource setup/teardown
116from contextlib import asynccontextmanager
117from fastapi import FastAPI
118 
119@asynccontextmanager
120async def lifespan(app: FastAPI):
121    # startup
122    await database.connect()
123    yield
124    # shutdown
125    await database.disconnect()
126 
127app = FastAPI(lifespan=lifespan)
128 
129# ❌ WRONG — deprecated startup/shutdown events
130@app.on_event("startup")
131async def startup():
132    await database.connect()
133```
134 
135---
136 
137## Anti-Patterns — Do NOT Generate
138 
139```python
140# WRONG: synchronous route handler [BLOCKER]
141@router.get("/orders/{order_id}")
142def get_order(order_id: str):
143    return order_repo.find(order_id)
144 
145# WRONG: missing response_model [MAJOR]
146@router.post("/orders")
147async def create_order(body: dict) -> dict:
148    return {"status": "ok"}
149 
150# WRONG: returning raw dict from route [MAJOR]
151@router.get("/health")
152async def health():
153    return {"status": "up"}  # Use a typed HealthResponse model
154 
155# WRONG: raise HTTPException with plain string detail [MAJOR]
156raise HTTPException(status_code=400, detail="Invalid order")  # Use ProblemDetail
157 
158# WRONG: global mutable state [MAJOR]
159db = AsyncSession()  # module-level; not thread/request safe
160 
161# WRONG: hardcoded config [MAJOR]
162DATABASE_URL = "postgresql://localhost/orders"
163 
164# WRONG: deprecated on_event [MINOR]
165@app.on_event("startup")
166async def init():
167    ...
168```
169 
170---
171 
172## Dependencies & Versions
173 
174| Technology | Version | Notes |
175|-----------|---------|-------|
176| FastAPI | 0.111+ | Annotated dependencies, lifespan parameter |
177| Pydantic | 2.x | `model_config = ConfigDict(...)` replaces `class Config:` |
178| uvicorn | 0.29+ | ASGI server; run with `--workers` in production |
179| SQLAlchemy | 2.x | `async_sessionmaker`; always `await` sessions |
180| alembic | 1.13+ | Database migrations; `async` env configuration |
181| httpx | 0.27+ | Async HTTP client for downstream calls |
182| python-jose | 3.x | JWT decoding; verify `alg`, `aud`, `iss`, `exp` |
183 
184---
185 
186## Test Conventions
187 
188- Use `httpx.AsyncClient` with FastAPI `app` as transport for integration tests — not `TestClient` (synchronous)
189- Override dependencies in tests via `app.dependency_overrides`
190- Test the full HTTP layer (router → service → repo) in integration tests with `Testcontainers`
191- Unit test service logic with mocked repositories using `unittest.mock.AsyncMock`
192- Use `pytest.mark.parametrize` for status code boundary tests (200, 201, 400, 404, 422, 500)
193- Verify `Content-Type: application/problem+json` on all error responses
194