---
name: python-backend-core
description: "Shared reference for the python-backend cluster: the thin-adapter model (web/API layer over a typed, tested core), the Django-vs-FastAPI decision, boundary validation, the test/verify gate, and the shared tooling matrix. USE WHEN choosing a Python web framework, wiring persistence or validation, or planning a release — the conventions every spoke in this cluster shares."
cluster: python-backend
version: 1.0.0
---

# Python Backend Core

Shared model for the `python-backend` cluster. The framework, testing, security, and ML spokes
all depend on these conventions — keep them consistent here so no spoke contradicts another.

## 1. The decision this cluster turns on: a thin adapter over a typed core

Every spoke assumes the same layering. The HTTP/task layer is **thin**; it parses, validates,
delegates, and serializes. Business logic lives in plain, typed, testable Python that knows
nothing about the request:

```
Request ──> Boundary (validate + parse) ──> Service / domain (typed, framework-free) ──> Persistence
                  ▲                                   │
              serialize ◄────────── typed result ◄────┘
```

- **Boundary** — DRF serializers (Django) or Pydantic models (FastAPI) validate *every* input and shape *every* output. Raw ORM objects, secrets, and framework globals never cross into a response schema. → `django-patterns`, `fastapi-patterns`
- **Service / domain** — pure Python, fully type-hinted; this is what the tests target directly. → `python-patterns`, `python-testing`
- **Persistence** — ORM (Django) or explicit DB dependencies (FastAPI); kept behind the service, never called from a view.

**Rule:** if logic can live in a framework-free function, it does. Views/routers stay skimmable.

## 2. The framework choice (Django vs FastAPI)

The cluster's first fork. Pick the lane, then stay in it.

| Pick **Django** when… | Pick **FastAPI** when… |
|---|---|
| You want batteries included: ORM, migrations, admin, auth, forms | You want an async-first, minimal service |
| Server-rendered pages **or** DRF REST API | Pure JSON API, OpenAPI/schema-driven |
| A relational data model is central | You compose your own DB/validation stack |
| Background jobs via Celery (`django-celery`) | High-concurrency I/O-bound endpoints (`async def`) |

Both follow §1. Django spokes are the deep lane here (patterns/TDD/security/celery/verification);
FastAPI is one consolidated spoke. Need ranking/feed logic behind either → `recsys-pipeline-architect`.

## 3. Testing & the verify gate (nothing is "done" untested)

- **TDD is the default** — red → green → refactor. Plain Python → `python-testing`; Django → `django-tdd` (pytest-django, factory_boy, DRF test client).
- **Target the service layer**, not the framework. Test transforms, branching, and contracts directly; use fixtures/mocks at the edges.
- **The gate before any PR or deploy**: environment → lint/format → type-check → tests + coverage → security scan → readiness. Django ships this as `django-verification`; for FastAPI/ML, run the same phases with the tools in §5.

## 4. Security & secrets (non-negotiable in production)

- `DEBUG` off; secrets from the environment, never committed. → `django-security`
- Validate at the boundary (§1) — defense against SQLi/XSS/mass-assignment starts there.
- Auth/authz explicit per endpoint; CSRF for cookie-session apps; HTTPS-only cookies + HSTS in prod.
- For ML, treat artifacts/datasets/prompts/logs as a security surface (secrets, PII, unsafe deserialization). → `mle-workflow`

## 5. Version / tooling matrix

| Concern | Default tool | Spoke |
|---|---|---|
| Language | Python 3.11+, full type hints | `python-patterns` |
| Tests | pytest (+ pytest-django for Django) | `python-testing`, `django-tdd` |
| Test data | factory_boy | `django-tdd` |
| Lint / format | ruff + black | `python-patterns`, `django-verification` |
| Type check | mypy | `python-patterns`, `django-verification` |
| Web (batteries) | Django + DRF | `django-patterns` |
| Web (async) | FastAPI + Pydantic v2 | `fastapi-patterns` |
| Async tasks | Celery + Redis/RabbitMQ | `django-celery` |
| ML training | PyTorch (device-agnostic, seeded) | `pytorch-patterns` |
| ML system | data contracts, eval gates, rollback | `mle-workflow` |
| Ranking/feed | six-stage pipeline | `recsys-pipeline-architect` |

## 6. Shared guardrails

- **Thin adapter**: no business logic in views/routers; logic is framework-free and typed.
- **Validate at the boundary**: DRF serializers / Pydantic models on every input *and* output; the client is untrusted.
- **No raw ORM / secrets in responses**; explicit `response_model` / serializer fields only.
- **Untested = unfinished**: TDD by default; the verify gate (§3) must pass before PR/deploy.
- **Prod hygiene**: `DEBUG=False`, env-sourced secrets, secure cookies/HSTS, explicit auth.
- **State scope changes**: a new external call, a loosened auth check, a skipped migration check, or an un-gated model promotion is a change worth saying out loud.
- **Django vs FastAPI**: choose once per service by §2; don't blend ORM-centric Django logic into an async FastAPI router or vice versa.