Canonical reference: the full, maintained guide lives at Cross-Domain Integration Guide. This page is a stable entry point that orients you and links onward — it does not duplicate the detail, so there is a single source of truth to keep current.
Why this page exists#
Oshun is a domain-driven system of bounded contexts: each domain (Iris, Lilith, Yemaya, Isis, Sophia, Hathor, Bellona, Tara, Veritas, Psyche, Nyx, Aja, Aphrodite, and the library-only domains) owns its own data and capabilities and exposes them only through well-defined interfaces. The hard part of working across that boundary is choosing the right coupling: a synchronous call when you need an answer now, an event when you are announcing a fact, and a shared contract so neither side hand-rolls the payload shape. This page points you at the guide that makes those choices concrete.
What the canonical guide covers#
The reference guide is the deep treatment:
- Integration principles — domain ownership, well-defined interfaces, and why domains never reach into each other's databases.
- Communication patterns — synchronous REST/gRPC for request/response versus the asynchronous event bus (Redis Streams) for announcing facts, and when each is correct.
- Domain clients & data contracts — how a consumer talks to a domain through
its generated client, and how the shared Zod/contract types in
libs/contracts/keep producer and consumer in lockstep. - Event-driven integration — event schemas, producers/consumers, and common integration scenarios end-to-end.
- Error handling, testing, and anti-patterns — degradation behavior across a boundary, how to test an integration without standing up every domain, and the coupling mistakes (chatty sync calls, shared databases, leaked internals) to avoid.
When to use it#
Read the canonical guide before wiring one domain to another — adding a new cross-domain call, emitting or consuming a new event, or designing a contract that two domains share. To see the actual runtime dependency edges between domains, walk the systems entity catalog, whose "depends on / used by" graph is generated from the package manifests.
This consolidated stub preserves the historical docs/guides/ entry point so
inbound links keep resolving, while the maintained content lives in one place.