Architecture Decision Records
This directory contains the foundational Architecture Decision Records (ADRs) governing eventsource-py.
Canonical Architectural Foundations
- 1. Async-First Concurrency Model — Pure asyncio core throughout stores, buses, runners, and repositories.
- 2. Hexagonal Ring Layering and Dependency Isolation — Strict layered architecture: adapters > application > ports > domain.
- 3. Pure Functional Decider Pattern and Immutable State Folding — Typed DeciderAggregate, immutable Pydantic states, and pure state folding.
- 4. Declarative Aggregate Root and Domain Event Strictness — Declarative @handles decorators, single-source wire names, and strict event validation.
- 5. Clean Storage Ports, Composed Protocols, and Connection Lifecycle — Segregated store ports, explicit connection ownership, and clean shutdown.
- 6. Snapshot Policies, Scheduling, and Boundary-Crossing Rehydration — Composed snapshot policies decoupled from stores with boundary-crossing rehydration.
- 7. Uniform Message Bus Contract and At-Least-Once Delivery Semantics — Uniform EventBus protocol across brokers with at-least-once delivery and DLQ isolation.
- 8. Subscription Engine, Feed-Driven Checkpointing, and Ordered Sequential Delivery — Feed-driven checkpointing, sequential subscriber delivery, and page-based batching.
- 9. Projection Engine, Deterministic Replay, and Additive Read-Model Reconciliation — StoreProjection base, replay drivers, version conflict protection, and additive schemas.
- 10. Ambient Multi-Tenant SaaS Isolation Model — ContextVar tenant propagation, hard reset safety, and storage query pushdown.
- 11. Zero-Downtime 5-State Live Store Migration and Distributed Locking — 5-state live migration coordinator, bounded pause rollback, and advisory locks.
- 12. Tier-0 Packaging, PEP 562 Lazy Front Door, and Zero-Overhead Observability — Lightweight base install, named extras, lazy frontdoor loading, and no-op tracing.
- 13. Tenant Ownership Check on the Repository Read and Write Path — Under a tenant scope, the repository refuses to load, probe, or append to a stream that another tenant owns.
- 14. Tenant Scope for Read Models, the Dead Letter Queue, and Checkpoints — Under a tenant scope, read models, DLQ entries, and checkpoints are scoped to the active tenant.