# FastAPI Phase 1 Audit Checklist

Use this when auditing a new modular Clean Architecture FastAPI scaffold. It captures failure modes found during a Phase 1 streaming-app audit where tests were green but success paths were broken.

## Runtime and API checks

- Run normal gates first: `ruff check app tests`, `mypy app`, `pytest -q`.
- Do not stop at validation tests. Add/verify at least one successful HTTP integration test per endpoint module with `httpx.ASGITransport`.
- For auth, test the full path: register -> login -> /me.
- Smoke `/health` with live Uvicorn. Smoke state-changing endpoints against live app only when DB/services are running; otherwise use dependency-overridden integration tests.

## Auth/JWT checks

- Tokens should include and validation should require: `sub`, `exp`, `iat`, `nbf`, `iss`, `aud`, `jti`, and token type (`typ=access`).
- Reject non-string/missing/non-parseable subjects with 401, not 500.
- Preserve `WWW-Authenticate: Bearer` when custom HTTP exception handlers rebuild JSON responses.
- Check duplicate unique fields in application logic for UX, and also translate DB `IntegrityError` as race-condition protection.

## Clean Architecture checks

- Domain entities are pure Python (dataclasses/plain classes), not Pydantic/SQLAlchemy models.
- Application ports return/accept domain objects or DTOs, not ORM models.
- Infrastructure adapters own ORM <-> domain mapping.
- Use cases receive concrete capabilities through constructor-injected ports (`PasswordHasher`, `TokenService`, repositories), not direct imports of PyJWT/pwdlib/SQLAlchemy helpers.
- FastAPI `Depends` only appears in presentation/dependencies/router layers.
- Dependency factories are centralized in `presentation/dependencies.py`; routers import them. Tests override the exact callable used by routes.

## Test quality checks

- Prefer typed stubs over `MagicMock` for application use-case tests.
- Add regression tests for protocol headers, not only JSON body/status.
- Add successful response schema checks; logging/serialization failures often only appear after the use case succeeds.
- Ensure test client fixtures actually install DB dependency overrides; unused inner `get_test_session()` functions are a red flag.