Reference chat application for the modern-python organisation: a
single-package Litestar service with JWT cookie auth, direct and group chats,
idempotent message send, cursor-paginated history, per-member read markers
and unread counts. It shows the org's libraries composed on a domain more
realistic than a two-table CRUD template.
- tests on
pytestwith automatic rollback after each test case, DI providers exposed as fixtures viamodern-di-pytest - IOC (Inversion of Control) container built on modern-di, one container for app- and request-scoped providers
- Observability tools integration built on lite-bootstrap
- Linting and formatting with
ruff, type checking withty Alembicfor DB migrations- retried, use-case-owned transactions via db-retry
just --listto see every recipe. just run brings up the app and Postgres in Docker
Compose and serves the API on :8000. just test cycles the database and
runs the full test suite (also via Docker Compose) at 100% coverage.
litestar-sqlalchemy-template shows each library in isolation on a two-table
domain. The templates never need a transaction spanning two writes, a unique
constraint hit by concurrent requests, or a count that must not cost a row per
event. This domain needs all three. See
PR #1 for the full design
and docs/adr/ for the calls taken along the way.
| Pattern | Where to look |
|---|---|
| One DI container, app + request scopes | app/ioc.py |
| Use case owns the transaction boundary | app/use_cases/create_message.py |
| Idempotent write with a concurrent-retry fallback | app/use_cases/create_message.py |
| Direct-chat upsert that survives a race | app/use_cases/create_chat.py |
| Cursor pagination in both directions | app/repositories/messages_repository.py |
| Unread counts without receipt rows | app/repositories/chats_repository.py |
| Atomic monotonic read marker | app/repositories/chat_members_repository.py |
| Per-test rollback via a container override | tests/conftest.py |
| DI providers as pytest fixtures | tests/use_cases/conftest.py |
| Simulating a DB race at the repository seam | tests/use_cases/test_create_chat.py |
📝 License
Browse the full list of templates and libraries in
modern-python; the org profile has the categorized index.