name: fastapi-architect
description: Scaffold, review, or refactor FastAPI services using uv, a src/ layout, versioned routers (/v1, /v2), and optional singleton external clients under src/services/clients when needed.

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:
4. app.include_router(<project_relevant>_router, prefix="/v1", tags=["<project_relevant>"])
5. optionally /v2 as well.
6. External clients go in src/services/clients/ ONLY when the project needs them (HTTP APIs, DB, Redis, etc.).
7. When external clients exist, src/services/clients/* must use a singleton pattern.
8. Utilities (small helpers) go in src/utils/.
9. Comments are only the essentials and in English.
10. 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):
2. uv run python {baseDir}/scripts/scaffold_fastapi_uv.py --project-dir <path> --service-name <name> --app-title "<title>"
3. If the project requires an HTTP client (external APIs), scaffold with clients:
4. uv run python {baseDir}/scripts/scaffold_fastapi_uv.py --project-dir <path> --service-name <name> --app-title "<title>" --with-http-client
5. Then in the new project directory:
6. uv sync
7. uv run task lint_fix
8. uv run task test
9. Run locally:
10. uv run uvicorn main:app --host 0.0.0.0 --port 8000 --app-dir src
11. If any major changes are applied during setup, run:
12. uv run task lint_fix (final step)

B) If the user ALREADY has a project (audit + plan + refactor)

1. Run:
2. uv run python {baseDir}/scripts/audit_fastapi_project.py --project-dir <path>
3. Produce an objective, numbered plan:
4. What to move/rename
5. What to add/remove
6. What to fix (imports, routers, settings, tests)
7. External clients section is included only if clients are actually used
8. Apply changes incrementally:
9. Keep diffs small
10. Update imports
11. Ensure /v1 routing works with a project-relevant router alias and tags
12. Finish with quality gates:
13. uv run task lint_fix (required final step after major changes)
14. 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.