Skip to content

avibebuilder/claude-prime / .claude/starter-skills/backend-fastapi-python

backend-fastapi-python

Unverified

Use this skill for any Python backend work in this project: building FastAPI endpoints, writing service functions, defining Pydantic/SQLModel schemas, running Alembic migrations, or debugging 422 errors. Essential for authentication and authorization patterns — setting up get_current_user, is_superuser checks, admin-only guards, role-based access, and dependency injection chains like Depends(). Also covers middleware, background tasks, async SQLAlchemy sessions, ORM relationship loading, and request/response design. Activate whenever the question involves Python API code, FastAPI patterns, or backend architecture in this codebase. Not for frontend, Docker, CI/CD, or infrastructure.

Backend FastAPI Python

Project-specific conventions for FastAPI with SQLModel, pydantic-settings, and async SQLAlchemy.

Architecture Decisions

  1. Services are stateless functions — Not classes. First param is db: AsyncSession.
  2. Generic response wrapper — Always use ApiResponse[T] for consistency.
  3. Dependencies chain — get_current_user -> require_auth -> require_admin.
  4. Module-scoped config — Each module can have its own {module}_config.py.
  5. Error codes for frontend — AppException(status, message, error_code).

Gotchas

  • SQLModel Relationship() fields are NOT included in API responses by default. You must explicitly add them to model_config or use a separate response schema with those fields.
  • AsyncSession.refresh() does not load relationships. After commit, re-query with .options(selectinload(...)) if you need related objects.
  • Pydantic V2 uses model_validator not validator. The @validator decorator is V1 and will break silently or raise deprecation warnings.
  • Depends() in FastAPI creates a NEW instance per request — don't store state in dependency return values expecting it to persist.
  • Background tasks (BackgroundTasks) run AFTER the response is sent. If they fail, the client already got a 200. Use proper task queues (Celery, ARQ) for anything that must not silently fail.
  • Alembic --autogenerate misses: table renames (generates drop+create), index changes on existing columns, and Enum type modifications in PostgreSQL. Always review generated migrations.
  • async def endpoints block the event loop if you call sync I/O inside them. Use run_in_executor for sync libraries or define the endpoint as def (FastAPI runs sync endpoints in a threadpool).
  • HTTPException from FastAPI and HTTPException from Starlette are different classes. Importing the wrong one causes middleware to miss exception handlers.
  • SQLAlchemy's lazy="selectin" on relationships causes N+1 queries in async sessions. Use explicit selectinload() in queries instead.
  • Optional[str] = None in query params makes the field optional. str = None also works but loses type information — prefer the explicit Optional form.
  • When using response_model, FastAPI filters OUT any fields not in the model. If your response is missing data, check that the response model includes all fields, not just the ORM model.

References

When you need...Read
Directory layoutfile-structure.md
Settings and env varsconfiguration.md
Database sessions and connectionsdatabase.md
ORM modelsmodels.md
Request/response schemasschemas.md
Router and endpoint patternsrouting.md
Service layer patternsservices.md
Dependency injectiondependencies.md
Middleware setupmiddleware.md
Error handlingerror-handling.md
Auth flow exampleauth.md
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall