OpenTeams Backend Development

Conventions and patterns for the OpenTeams Python backend stack. Follow these when building or changing any FastAPI backend in this org. To scaffold a brand-new project, use the new-project skill instead — this skill governs ongoing development.

The Stack

First Moves In Any Project

Before writing code, confirm what the project actually uses — conventions below are the org default, but a given repo may differ. Check, in order:

1. pyproject.toml — deps, optional-extras, [dependency-groups], the [tool.ruff]/[tool.mypy]/[tool.pytest] config, build backend.
2. The package layout — src/ vs app/ (see below). Mirror whichever is present.
3. AGENTS.md / README.md — repo-specific commands and conventions.
4. alembic.ini + migrations/ — whether the project uses migrations.
5. docker-compose.yml — local Postgres (and its ports).
6. The surrounding code's idioms — match them over these defaults when they conflict.

Two Layouts — Identify Which You're In

The org runs two layouts. Detect, then mirror — never convert one to the other unasked.

app/ — deployable service (scaffolded by new-project --backend). Flat application package, layered by responsibility:

app/
├── main.py            # FastAPI app + router includes
├── config.py          # pydantic-settings Settings
├── database.py        # async engine + sessionmaker
├── deps.py            # FastAPI dependencies (get_db, ...)
├── models/            # SQLAlchemy models (import each in __init__.py)
├── schemas/           # Pydantic request/response models
├── repositories/      # DB queries — ThingRepository
├── services/          # business logic — ThingService
└── routers/           # route handlers (include in main.py)

Per-resource, you add five files: models/thing.py, schemas/thing.py, repositories/thing.py, services/thing.py, routers/thing.py. Routers call services, services call repositories, repositories touch the DB. Keep the layers one-directional.

src/ — publishable package (e.g. ravnar, hrafnar). Uses the org's public/private split:

src/
├── <pkg>/             # PUBLIC API — thin re-exports, py.typed, __main__.py (Typer)
└── _<pkg>/            # PRIVATE impl — config.py, orm.py, core.py, database.py, ...

<pkg>/__init__.py re-exports the supported surface from _<pkg>/; everything in _<pkg>/ is internal and may change. When editing one of these repos, put implementation in _<pkg>/ and only widen <pkg>/ when intentionally exposing API. Version comes from git via uv-dynamic-versioning — never hand-edit a version string.

Non-Negotiables

• Async all the way down. Async route → async service → async repository → AsyncSession. Never block the event loop with sync DB/HTTP calls.
• Pydantic v2 only. model_config = ConfigDict(...), model_validate, model_dump. No v1 .dict()/Config class.
• Config via pydantic-settings, never os.environ[...] scattered through code. One Settings object, env-prefixed, loaded once.
• Separate ORM models from API schemas. SQLAlchemy models ≠ Pydantic schemas. Map between them explicitly.
• Structured logging via structlog, not print or bare logging. Bind context, log events as logger.info("event_name", key=value).
• Full type annotations. mypy runs strict (disallow_untyped_defs, disallow_untyped_calls). No untyped public functions.
• Migrations for every model change (in app/ services): edit model → uv run alembic revision --autogenerate -m "..." → review the generated SQL → uv run alembic upgrade head. Never hand-write schema drift.
• Run the quality gate before declaring done (see references/quality.md): uv run ruff format . && uv run ruff check . && uv run mypy <pkg-or-src> && uv run pytest

Reference Files

Read the relevant reference before doing that kind of work — they hold the canonical patterns:

• references/structure.md — both layouts in detail, the public/private split, adding a resource to an app/ service, config + database + deps patterns, Typer CLI entrypoints.
• references/quality.md — the exact ruff rule set + mypy strictness + pytest config used across the org, the quality-gate commands, and async test patterns (asyncio_mode=auto, xfail_strict, filterwarnings=error).

What NOT To Do