python-backend-core

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.