# Cross-Domain Integration

> **Canonical reference:** the full, maintained guide lives at
> **[Cross-Domain Integration Guide](../reference/cross-domain-integration.md)**.
> 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](../reference/cross-domain-integration.md) 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](../../docs-center/systems/index.html), 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._