# Fastapi Architect

> Scaffold, review, or refactor FastAPI services using uv, a src/ layout, versioned routers, and optional singleton clients; use for new services or architecture cleanups. Use when this capability is needed.

- Skill: `tomevault-io/fastapi-architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/fastapi-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/fastapi-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/fastapi-architect

---


# FastAPI + uv Architect Skill

## When to use
Use this skill when the user asks to:
- Create a new FastAPI service with best practices (uv + src/ layout + Dockerfile).
- Refactor an existing FastAPI codebase into a clean, versioned API layout.
- Enforce consistent conventions: settings via pydantic-settings, structured logging, thin endpoints, and external client singletons (only when required).

## Non-goals
- Do not invent domain/business logic.
- Do not add heavy abstractions or excessive comments.
- Do not introduce new frameworks unless required.

## Core standards (must follow)
1. Project uses **uv** and defines `pyproject.toml`.
2. Code lives under `src/` and is importable (Docker uses `PYTHONPATH=/app/src`).
3. API versioning is explicit in `src/main.py`:
   - `app.include_router(<project_relevant>_router, prefix="/v1", tags=["<project_relevant>"])`
   - optionally `/v2` as well.
4. External clients go in `src/services/clients/` **ONLY when the project needs them** (HTTP APIs, DB, Redis, etc.).
5. When external clients exist, `src/services/clients/*` **must use a singleton pattern**.
6. Utilities (small helpers) go in `src/utils/`.
7. Comments are **only the essentials** and **in English**.
8. After any major change, always run `uv run task lint_fix` as the final step.

## Workflow
### A) If the user does NOT have a project yet (scaffold)
1. Scaffold without clients (default):
   - `uv run python {baseDir}/scripts/scaffold_fastapi_uv.py --project-dir <path> --service-name <name> --app-title "<title>"`
2. If the project requires an HTTP client (external APIs), scaffold with clients:
   - `uv run python {baseDir}/scripts/scaffold_fastapi_uv.py --project-dir <path> --service-name <name> --app-title "<title>" --with-http-client`
3. Then in the new project directory:
   - `uv sync`
   - `uv run task lint_fix`
   - `uv run task test`
4. Run locally:
   - `uv run uvicorn main:app --host 0.0.0.0 --port 8000 --app-dir src`
5. If any major changes are applied during setup, run:
   - `uv run task lint_fix` (final step)

### B) If the user ALREADY has a project (audit + plan + refactor)
1. Run:
   - `uv run python {baseDir}/scripts/audit_fastapi_project.py --project-dir <path>`
2. Produce an **objective, numbered** plan:
   - What to move/rename
   - What to add/remove
   - What to fix (imports, routers, settings, tests)
   - External clients section is included **only if clients are actually used**
3. Apply changes incrementally:
   - Keep diffs small
   - Update imports
   - Ensure `/v1` routing works with a project-relevant router alias and tags
4. Finish with quality gates:
   - `uv run task lint_fix` (required final step after major changes)
   - `uv run task test`

## Singleton clients (only when needed)
- Implement singleton clients in `src/services/clients/*`.
- Prefer an `@lru_cache` factory to guarantee one instance per process.
- Close clients on shutdown using FastAPI `lifespan`.

## Deliverables checklist
- `pyproject.toml` with minimal runtime deps + dev tooling.
- `src/main.py` with `/v1` (and optionally `/v2`) routing using a **project-relevant router alias** and **tags**.
- `src/core/config.py` using `pydantic-settings`.
- `src/core/log_config.py` + `src/core/logger_func.py`.
- `src/api/deps.py` for shared dependencies.
- `tests/` with a basic health test (and `conftest.py` to ensure `src/` is importable).
- Dockerfile using uv.
- `src/services/clients/` only if required by the project.

## Notes
- Use `fastapi[standard]` unless the user explicitly requests otherwise.
- Prefer FastAPI `lifespan` to manage startup/shutdown resources.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/y4rd13) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->