Navigate by location.

Two independent services, linked by streams.

A full HTTP backend and a standalone worker in one monorepo. Two Valkey streams cross the boundary and nothing else -- video_uploaded out, video_status back -- each one a name plus a payload shape that both sides declare for themselves.

contract = stream name + payload shape, redefined on each side · VideoUploadedIntegration ✕ VideoUploadedSchema · 0 shared imports

• Not one shared import. grep "from event_microservice" in the backend returns nothing -- context independence is an import-linter contract, not a promise. enforced
• Either service extracts unchanged. Each is its own uv project, Dockerfile and CI; they share only the wire contract.

One hexagon, repeated. Dependencies point inward.

Requests climb the driving side into the core; effects fall down the driven side out of it. domain/ sits on top and imports nothing; frameworks touch only the two adapter columns. Hover a layer to find it in the tree -- you'll meet this exact map again in errors and logging.

★ the four real driven adapters media_example can't show -- it has no adapters/driven at all. Layer direction is an import-linter contract. enforced

contexts connect exactly two ways

architecture.md →  auth/ source →

The patterns are the product.

Each one is implemented end-to-end, tested at four levels, and documented with the reasoning that picked it.

INSERT video ─┐ one tx
INSERT outbox ─┘   └─▶ relay ─▶ stream

at-least-once delivery
+ event_id inbox ─▶ exactly-once effect

JWT ─▶ API-key ─▶ static token
first match wins · fail-closed

WHERE (created_at,id) < (:ts,:id)
ORDER BY created_at DESC, id DESC

{event_id, event_type,
 version, occurred_at, ...payload}

One request, every pattern.

The shipped video pipeline exercises the whole catalog · watch a request travel through both services and come back as an SSE event.

at-least-once everywhere, duplicates absorbed at each edge · full field-by-field contracts in docs/contract/ →

One DI graph. Swap anything in one line.

Every bounded context ships its own Dishka provider -- its own sub-graph. One build_container() call composes them into a single container, resolved lazily on the first request. Hover a provider to see what it puts into the graph.

hover a provider to see what it binds

• Swap, disable, add -- one line each. provide(SystemClock, provides=IClock) swaps an implementation; dropping a provider from build_container() disables that context; a new <ctx>/provider.py plus one line adds one. structural
• The graph is lazy. APP-scope resolves on the first request; tests warm it explicitly and a boot does no hidden I/O.
• Prod invariants fail closed. No admin token or CSRF secret under APP_ENV=prod and the app refuses to start.

infra/dishka.md →  container.py →

Config is one file per context.

Each context owns a config.py -- a Pydantic-Settings class with its own env_prefix and typed, self-validating fields. Values flow one way: env → Settings → provider → constructor; domain and app never read os.environ. Hover a field to light up the variable it reads.

# auth/config.py
class AuthConfig(BaseAppConfig):
    model_config = SettingsConfigDict(
        env_prefix="AUTH_",
    )

    admin_token: SecretStr | None = None
    jwt_secret: SecretStr | None = None
    jwt_issuer: str = Field("litestar-base")
    jwt_access_ttl_seconds: int = Field(900, ge=1)
    jwt_refresh_ttl_seconds: int = Field(1_209_600, ge=1)
    pool_size: int = Field(5, ge=1)  # validated here

# the full contract · every var, annotated
AUTH_ADMIN_TOKEN=
AUTH_JWT_SECRET=
AUTH_JWT_ISSUER=litestar-base
AUTH_JWT_ACCESS_TTL_SECONDS=900
AUTH_JWT_REFRESH_TTL_SECONDS=1209600
AUTH_POOL_SIZE=5

# same shape per context:
# MEDIA_* LOG_* METRICS_* POSTGRES_* VALKEY_*

One env_prefix per context: MEDIA_ · AUTH_ · LOG_ · METRICS_ · POSTGRES_ · VALKEY_ · DB_EXAMPLE_LITESTAR_ -- two contexts can both hold a POOL_SIZE without collision, and each class validates only its own slice of the environment.

• The domain can't see the environment. No os.environ in any domain/ or app/ across every context (grep-verified); config arrives only as constructor arguments.
• Two templates bound the surface. .env.example is the 12-var minimum to boot; .env.full.example is the complete contract. Secrets are empty placeholders with a generation hint; .env is gitignored. convention

auth/config.py →  .env.full.example →

One base error. Each layer derives its own.

Every layer raises its own subtype of LayerError; the driving edge is the single place that catches and maps. Pick a layer.

• One 6-entry map is the whole translation layer. Four base classes plus two framework cases. A new context error inherits its status and a stable urn:litestar-base:error:<slug> for free. enforced at one site
• Two honest deviations. No AdapterError exists here (no raise-site), and NotFoundError nests under AppError so 404 wins over 422 by MRO.

contract/errors.md →  error_hierarchy.md →

Bind the trace once. Each layer signs its own line.

trace_id is created once, at the driving-adapter edge; below it nobody passes it along -- merge_contextvars merges it from a contextvar. Pick a layer to see the line it really writes.

infra/structlog.md →  observability.md →  ·  layer is an explicit bind via layer_logger, never auto-derived convention

Four levels. Every context alone, then all together.

The folder is the level -- a path-reading collection hook tags the marker, so -m unit selects a tier across every context with zero hand-kept markers.

371 total · backend 340 + worker 31 · tiers rank by isolation, not head-count (a template proves itself end-to-end, so e2e runs heavy)

standalone for the fast loop, together for the proof

run just your context for a tight loop; e2e boots the whole composition to prove they compose -- no mocks. path = level, enforced by the collection hook

tests/ →  development.md →

Architecture is a test, not a diagram.

One canonical gate -- ruff · mypy · lint-imports · pytest -- lives in the Docker tester image, and that is what CI runs.

Contracts guard context independence, an un-importable root, a dependency-free shared kernel and inward layering. A cross-layer import fails the build. enforced   ci.yml →  contracts →

Brief enough to read. Complete enough to trust.

Every page has one job, one audience, and a line budget -- brief is a rule, not a hope. Every fact has one authoritative home; wire truth lives only in docs/contract/. Behaviour ships in the same change as the doc that describes it.

docs/                    platform · cross-service
├ architecture.md         ≤300
├ contract/               single wire truth
├ adr/                    ≤40 each
├ features/               ≤100 · zero wire facts
└ infra/                  ≤150

src/<service>/docs/       service-internal
├ contexts/               ≤250 · ownership · invariants
├ subsystems/             ≤200 · errors · jwt · metrics
├ infra/                  ≤150 · dishka · structlog
└ adr/                    service ADR tree

• One authoritative home per fact. Wire truth lives only in docs/contract/; feature maps and ADRs carry zero wire fields and link out -- a field name or status code is defined once in the whole repo.
• A stale doc is a bug. Behaviour and its doc ship in the same change; the line budgets keep pages short enough that they actually get read.

ADR index →  adopting.md →

Every change walks the same path -- docs at both ends.

Design comes from the documentation, the plan comes from the code, and the docs close the loop. A written convention, not a linter.

development.md → feature workflow  convention

Reading it is running it.