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 ${CLAUDE_PLUGIN_ROOT}/skills/fastapi-architect/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 ${CLAUDE_PLUGIN_ROOT}/skills/fastapi-architect/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 ${CLAUDE_PLUGIN_ROOT}/skills/fastapi-architect/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.