# Full-stack FastAPI Template source notes

Repo: `fastapi/full-stack-fastapi-template`
Local checkout: `/home/ubuntu/repos/rodin-sources/full-stack-fastapi-template`

## Why this repo was chosen
- This template is a production-oriented FastAPI service skeleton, so it is useful for spotting conventions that survive outside toy examples: central assembly, typed dependency aliases, explicit schema boundaries, and visible test resource lifetimes.
- It is also valuable because it includes a few pragmatic exceptions that should not be over-generalized.

## Repeated patterns

### 1) Route modules are grouped by feature and assembled centrally
- `backend/app/api/main.py:6-14` creates a single `api_router`, includes feature routers (`login`, `users`, `utils`, `items`), and conditionally includes a `private` router only in local environments.
- `backend/app/main.py:17-33` creates the app, configures OpenAPI identity generation and CORS middleware, then mounts the API router under the versioned prefix.

Why chosen:
- This is the top-level assembly pattern for the template, not a side example.

Caveat / counterexample:
- `backend/app/api/main.py:13-14` shows an environment-specific router include. Good synthesis should treat this as a deliberate local-only escape hatch, not a reason to scatter router registration across arbitrary modules.

Implication for synthesis:
- Favor one central API router and one central app assembly module.
- Mention that environment-specific routes can still be expressed centrally.

### 2) Dependencies own session/auth wiring, and typed aliases keep route signatures concise
- `backend/app/api/deps.py:21-27` defines `get_db()` and publishes `SessionDep` / `TokenDep` as `Annotated[..., Depends(...)]` aliases.
- `backend/app/api/deps.py:30-57` decodes the token, validates it with `TokenPayload`, loads the user, and raises semantic HTTP errors for invalid credentials, missing users, inactive users, and insufficient privileges.
- `backend/app/api/routes/items.py:13-16`, `48-49`, `61-64`, `75-82`, and `99-102` repeatedly inject `SessionDep` and `CurrentUser` directly in handler signatures.

Why chosen:
- The dependency alias pattern is repeated across route handlers, not used once.

Implication for synthesis:
- Strong evidence for typed dependency aliases when the same collaborators appear across many handlers.
- Shared auth/session logic belongs in dependencies, not repeated inline in each route.

### 3) Schema transitions stay explicit at route boundaries
- `backend/app/api/routes/items.py:44-45` converts ORM/domain objects to `ItemPublic` before constructing the collection response.
- `backend/app/api/routes/items.py:61-72` accepts `ItemCreate`, validates it into an `Item` with `owner_id` injected, persists it, and returns the created object.
- `backend/app/api/routes/items.py:91-96` uses `item_in.model_dump(exclude_unset=True)` before applying a partial update.

Why chosen:
- The route code repeatedly marks transitions between input schema, persistence model, and output schema.

Caveat / counterexample:
- `backend/app/api/routes/items.py:48-58`, `75-96`, and `99-113` still return ORM objects directly in some single-item handlers while relying on `response_model` to shape output. So the template mixes explicit conversion with response-model-driven shaping; future synthesis should describe that nuance instead of claiming one exclusive pattern.

Implication for synthesis:
- Prefer explicit schema boundaries, especially for collections and patch-style updates.
- When handlers return domain objects directly, note that `response_model` is still doing boundary work.

### 4) Tests keep DB lifetime and cleanup visible
- `backend/tests/conftest.py:15-24` creates a session fixture, initializes the DB once, yields the session, then deletes `Item` and `User` rows and commits cleanup.
- `backend/tests/conftest.py:27-30` keeps the test client lifecycle explicit with a context-managed `TestClient` fixture.

Why chosen:
- This is the template's default testing setup, so it is strong evidence for visible resource lifetime management.

## Strong citation candidates
- Central API router assembly with local-only conditional include: `backend/app/api/main.py:6-14`
- Typed dependency aliases: `backend/app/api/deps.py:21-27`
- Auth dependency handles token decode + user lookup + semantic errors: `backend/app/api/deps.py:30-57`
- Explicit patch update boundary via `model_dump(exclude_unset=True)`: `backend/app/api/routes/items.py:91-96`
- Test DB lifetime and cleanup: `backend/tests/conftest.py:15-24`

## Pattern candidates supported by this repo
- centralize app and API router assembly
- use typed dependency aliases for repeated collaborators
- keep auth/session logic in dependencies
- keep request/update/response schema transitions explicit
- keep test resource lifetime and cleanup visible