domainkit

A Django-style framework for domain-driven FastAPI services. It provides:

• settings modules and installed domains
• manage.py commands and migrations
• DDD building blocks, with the layer rules between them enforced
• several databases: domains routed to their own, sharding by key, PostgreSQL range partitioning, and immudb ledgers for evidence
• caches in memory or in Redis and Valkey (one server, Sentinel, or Cluster), with stampede protection, and rate limits shared by every replica, globally or per route
• answers in the caller's language (English and Arabic ship), times shown in the business's time zone, and numbers and dates in local formats
• file storage and uploads checked by their content, under names the storage makes
• background work through a transactional outbox, run by polling workers or through RabbitMQ, with queues for separate worker pools
• users, groups, and permissions per content type, as in Django's contrib.auth: password hashing and rules, backends, object permissions, and a swappable user model; token or JWT authentication, and route rules as in Django REST framework
• optional apps for reliable messaging, audit trails, idempotent requests, tamper-evident evidence, signed outgoing webhooks, feature flags, and privacy requests (export, erasure, and retention)

pip install "domainkit[postgres]"     # extras: postgres, sqlite, argon2, jwt, mfa, immudb, redis, rabbitmq, metrics, tracing, uploads, testing, webhooks, tzdata

Documentation

• docs/reference.md: settings, middleware, errors, the API surface (OpenAPI, versions, deprecations), observability, testing, commands, and extension points
• docs/databases.md: several databases, routing, sharding, partitioning, and ledgers
• docs/queries.md: querying repositories, pages, filters, soft delete, row locks, and savepoints
• docs/resources.md: aggregates over REST: resource routes, commands and queries, derived schemas, partial changes, ETags and conditional writes, field policies, nesting, the generators, and the generic admin
• docs/runtime.md: how async work runs: background tasks, clean contexts, the shutdown budget, readiness, event-handler timeouts, and workers and the outbox
• docs/cache.md: caches in memory, Redis, and Valkey, and shared rate limits
• docs/runtime.md: running under load: request deadlines, load shedding, database timeouts and PgBouncer, and outgoing HTTP calls
• docs/contrib.md: messaging (and workers on RabbitMQ), webhooks, audit and records' history, idempotency, evidence, and feature flags
• docs/auth.md: users, groups, permissions, content types, passwords, backends, tokens, route rules, and the admin API
• docs/mail.md: email, mail templates, text messages, and push notifications, sent through the outbox
• docs/i18n.md: responses in the caller's language, time zones, and number and date formats
• docs/uploads.md: file storages, receiving uploads, and serving files
• docs/live.md: WebSockets and Server-Sent Events, bounded and re-authorized while open, and committed events streamed live
• docs/privacy.md: exporting and erasing a person's data, and retention
• docs/testing.md: the pytest plugin: test databases, sync and async clients, factories, a clock to freeze, and query counts
• docs/runtime.md: how async work runs: event loops, logging off the loop, finding blocking code, free-threaded Python, and servers
• docs/performance.md: what a request costs, the benchmark ladder CI gates on, and how to make requests cheaper
• docs/versioning.md: compatibility, deprecations, and releases
• docs/adr/: the decisions behind the design
• CHANGELOG.md and SECURITY.md

Quick start

python3.13 -m venv .venv && . .venv/bin/activate
pip install "domainkit[postgres,sqlite,testing]"
domainkit init billingAPI billing     # the name sets the variable prefix: BILLING_API_*
cd billing
python manage.py check
python manage.py startdomain invoices --aggregate Invoice   # installs and mounts it
python manage.py makemigrations -m "create invoices" && python manage.py migrate
python manage.py createsuperuser
pytest
python manage.py runserver            # http://127.0.0.1:8000/docs

domainkit init creates a project that passes check and its tests as it is. Users, groups, and permissions are installed, requests are authenticated, and every route must say who may call it: generated domains need their model permissions, and /auth and /admin/auth log users in and manage them (docs/auth.md).

billing/
  pyproject.toml          the name, dependencies, and the pytest plugin
  manage.py
  .env                    selects config.settings.local on this machine
  .gitignore
  src/config/settings/    base, local, test, and production settings
  src/config/urls.py      the root router: mount each domain's router here
  src/config/asgi.py      the application, for uvicorn
  src/domains/            the bounded contexts
  tests/test_health.py

The production settings read BILLING_API_ALLOWED_HOSTS, BILLING_API_DATABASE_URL, and BILLING_API_TRUSTED_PROXIES (the load balancers' networks, or empty) from the environment, and the deployment checks refuse to start without them, or without verified TLS to the database. They also turn the API docs off, send HSTS for a year, and limit each caller to 300 requests a minute; BILLING_API_API_DOCS, BILLING_API_SECURE_HSTS_SECONDS, and BILLING_API_RATE_LIMIT change that.

Serve it with one worker process per core, each on its own event loop: uvicorn config.asgi:application --workers 4 --loop uvloop, or Granian (pip install 'domainkit[granian]'). docs/reference.md gives the whole command with its limits, and docs/performance.md how many cores a load needs.

Developing domainkit

poetry install --all-extras            # Python 3.13
pre-commit install                     # after: pipx install pre-commit

poetry run ruff check . && poetry run ruff format --check . && poetry run mypy
poetry run pytest --cov                # random order; coverage gate in pyproject.toml
poetry run mutmut run "domainkit.http*" && poetry run mutmut results

Without servers, the database tests use SQLite, the Redis and RabbitMQ tests use in-memory fakes, and the tests that need PostgreSQL, immudb, or a real Redis, Valkey, or RabbitMQ are skipped. Point them at throwaway servers to run them; each test cleans up after itself:

docker run -d --rm --name domainkit-postgres -e POSTGRES_PASSWORD=postgres \
  -p 127.0.0.1:55432:5432 postgres:18-alpine
docker run -d --rm --name domainkit-redis -p 127.0.0.1:56379:6379 redis:8-alpine
DOMAINKIT_TEST_POSTGRES_URL=postgresql+asyncpg://postgres:postgres@127.0.0.1:55432/postgres \
DOMAINKIT_TEST_REDIS_URL=redis://127.0.0.1:56379/0 \
  poetry run pytest

The other variables (immudb, Redis over TLS, Valkey, RabbitMQ) are listed at the top of domainkit_tests/test_immudb.py, test_redis.py, and test_rabbitmq.py. Each run must cover 98%; CI also combines the runs with and without servers, which must cover 100%. To check that locally, run pytest --cov once without and once with the servers, each with its own COVERAGE_FILE, then coverage combine and coverage report --fail-under=100.

CI (.github/workflows/ci.yml) runs on every push and pull request:

• lint and strict typing
• the tests on Python 3.13 and 3.14
• the tests again against PostgreSQL 18, immudb with TLS and a signing key, Redis 8 (plain and TLS), Valkey 9, and RabbitMQ 4 (plain and TLS); no test may be skipped there
• coverage of both runs combined, which must be 100%
• the benchmark ladder: Python calls and database round trips per request, against budgets (python -m benchmarks; docs/performance.md)
• a wheel build, installed and imported in a clean environment
• pip-audit, and a gitleaks scan of the whole history

A full mutation testing run happens weekly, in eight shards that run side by side. Releases are published to PyPI from a version tag; see docs/versioning.md.

License

MIT; see LICENSE.