chat-app

Description

Reference chat application for the modern-python organisation: a single-package Litestar service — JWT cookie auth, direct and group chats, idempotent message send, cursor-paginated history, per-member read markers and unread counts — built to show the org's libraries composed on a domain more realistic than a two-table CRUD template.

Key Features

• tests on pytest with automatic rollback after each test case, DI providers exposed as fixtures via modern-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 using ruff and ty
• Alembic for DB migrations
• retried, use-case-owned transactions via db-retry

After git clone run

just --list

to 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.

Why this repo

litestar-sqlalchemy-template shows each library in isolation on a two-table domain. Nothing shows them composed under load-bearing decisions — a transaction that must span two writes, a unique constraint that two concurrent requests can both hit, a count that must not cost a row per event. This repo answers that with a domain that actually needs it. See planning/changes/2026-08-21.01-chat-app-bootstrap.md for the full design and architecture/ for the capabilities as shipped.

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

Part of modern-python

Browse the full list of templates and libraries in modern-python — see the org profile for the categorized index.