Architecture¶

Layer hierarchy¶

Application layer (depends on Domain + Primitives)
├── gridflow-python-mediator
├── python-cqrs-dispatcher (depends on cqrs-core + mediator)
├── fastapi-config-patterns
├── fastapi-middleware-toolkit
├── python-structlog-config
├── python-outbox-core
├── sqlalchemy-async-session-factory
└── sqlalchemy-async-repositories

Domain layer (depends on Primitives only)
├── python-app-exceptions
├── python-infrastructure-exceptions
├── python-input-validation
├── python-cqrs-core
├── python-domain-events
├── python-dto-mappers
└── pydantic-response-models

Primitives layer (zero dependencies)
└── python-technical-primitives

Import-linter contracts¶

Layer boundaries are enforced via import-linter in pyproject.toml:

Primitives cannot import from domain or application
Domain can import from primitives, cannot import from application
Application can import from domain and primitives

Inter-package dependencies¶

Only one cross-package dependency exists:

python-cqrs-dispatcher
├── python-cqrs-core (ICommand, IQuery interfaces)
└── gridflow-python-mediator  (Mediator dispatch engine)

All other packages are fully independent.

Design patterns used¶

Pattern	Package
Specification	`python-technical-primitives`
Repository + Strategy	`sqlalchemy-async-repositories`
Factory Method	`sqlalchemy-async-repositories` (pagination)
Mediator	`gridflow-python-mediator`
CQRS	`python-cqrs-core`, `python-cqrs-dispatcher`
Pipeline behaviors	`gridflow-python-mediator`
Transactional outbox	`python-outbox-core`
Strategy (formatters)	`python-outbox-core`
CloudEvents	`python-outbox-core`