# The Shared Platform

The shared platform is the foundation layer every Oshun product (V1–V9) and
every capability domain is built on top of. It is the answer to a simple
structural question: when nine products and several dozen domains all need
identity, persistence, validated contracts, logging, eventing, generation
control, and a backend-for-frontend, where does that code live so it is written
**once** and composed everywhere, rather than re-implemented per product? The
answer is three real library trees and a gateway tier: `libs/shared/` (the
domain-agnostic `@oshun/*` infrastructure, 50 packages), `libs/oshun/` (the
domain service/orchestration libraries, 49 packages), `libs/contracts/` (the Zod
contract surface, 23 contract domains under `libs/contracts/src/`), and the BFF
apps (`apps/*/bff`, fronted by `@oshun/bff` at `apps/oshun/bff/` with ~1,780
TypeScript files). This page is the map of that foundation; each section below
links to the in-depth page for one slab of it.

The platform exists so the **one-canonical-home** rule (§5 of the docs-center
proposal) holds at the code level, not just the documentation level: a product
space documents what is _specific_ to it and references the shared foundations
it composes; it never re-documents — or re-implements — identity, the event bus,
or the contract validator. The platform is where "shared" stops being an
aspiration and becomes an importable package with a version, a test suite, and
an owner.

## What ships, honestly

The platform is the most code-complete surface in the repository, because every
product depends on it and the dependency is load-bearing rather than
aspirational. The `@oshun/*` infrastructure libraries (`libs/shared/`) are real,
tested, domain-agnostic packages — `@oshun/logging`, `@oshun/errors`,
`@oshun/database`, `@oshun/cache`, `@oshun/event-bus`, `@oshun/config`,
`@oshun/identity` — imported across the monorepo (see the worked imports in
`libs/shared/README.md`). The domain-orchestration libraries (`libs/oshun/`) are
the service layer that turns substrate primitives into product behaviour:
`memory-iris`, `evidence-sophia`, `embodiment-psyche`,
`generation-control-isis`, `persona-policy-lilith`, and the six customer domains
(`domain-tara`, `domain-arete`, `domain-veritas`, `domain-nyx`, `domain-nisaba`,
`domain-metis`). The contract surface (`libs/contracts/src/`) is the single Zod
source of truth every boundary validates against, re-exported through
`libs/contracts/src/index.ts`.

Honesty where it is due: not every BFF is at the same maturity. `@oshun/bff`
(`apps/oshun/bff`, ~1,780 files) is the deep, production-shaped gateway;
`apps/lilith/bff` (~300 files) and `apps/kalika/bff` (8 files) are smaller,
domain-scoped gateways, and `apps/urania/bff` is a scaffold. The platform pages
label these distinctions rather than implying uniform depth, in keeping with the
repository's no-stub culture and the docs center's implemented / spec-only /
provider-gated status convention.

## The layered model

The platform is best read as a stack. Each layer depends only on the layers
below it, which is what keeps the dependency graph acyclic and the foundations
reusable.

```mermaid
flowchart TB
  S[Product surfaces · V1–V9 apps, UE clients, shells]
  B["BFF & gateway tier · @oshun/bff, @lilith/bff, @kalika/bff"]
  O["Domain orchestration · libs/oshun (domain-*, memory-iris, evidence-sophia, …)"]
  C["Contracts · libs/contracts/src (Zod, the validated boundary)"]
  I["Shared infrastructure · libs/shared (@oshun/* — logging, db, cache, event-bus, identity, config)"]
  D[(Persistence · Postgres · Redis · object store)]
  S --> B --> O
  O --> C
  O --> I
  B --> C
  I --> D
```

Reading the stack top to bottom:

- **Surfaces** — the product apps, Unreal clients, and shared shells. They hold
  no business logic that belongs to a domain; they call the BFF.
- **BFF & gateway** — the backend-for-frontend tier that composes domain
  orchestration for a specific surface, enforces auth/session, and shapes
  responses. Detailed in [BFF & Gateway](./bff-gateway.md).
- **Domain orchestration** (`libs/oshun/`) — the service layer where a substrate
  primitive (Iris memory, Sophia grounding, Psyche runtime) becomes a product
  capability. Detailed in [Domain Orchestration](./oshun-domain-libraries.md).
- **Contracts** (`libs/contracts/`) — the Zod schemas every boundary validates
  against, so a payload is the same shape in the BFF, the domain lib, and the
  test. Detailed in [Contracts](./contracts.md).
- **Shared infrastructure** (`libs/shared/`) — the domain-agnostic `@oshun/*`
  packages every layer above composes. Detailed in
  [Shared Libraries](./shared-libraries.md).
- **Persistence** — the shared Postgres/Redis/object-store foundation and the
  residency, migration, and deletion machinery on top of it. Detailed in
  [Persistence & Data](./persistence-data.md).

Identity threads through every layer (the BFF authenticates, the domain libs
authorize, the data layer enforces residency), which is why it gets its own
page: [Auth & Identity](./auth-identity.md).

## Why three library trees, not one

A reasonable question is why `libs/shared`, `libs/oshun`, and `libs/contracts`
are separate trees rather than one `libs/`. The split encodes a dependency
direction the build enforces:

- `libs/shared/` is **domain-agnostic**. Nothing in it imports a domain. You
  could lift `@oshun/logging` or `@oshun/event-bus` into an unrelated product
  and it would carry no Oshun-specific knowledge. This is what makes it safe for
  every domain to depend on.
- `libs/contracts/` is **domain shapes without behaviour**. It is the vocabulary
  — the `tara`, `veritas`, `iris`, `events` schema namespaces — that both sides
  of every boundary agree on. It depends on nothing but Zod and the shared
  primitives, so it can be imported by a UE-adjacent TypeScript client, the BFF,
  and a Vitest spec alike without dragging in a database driver.
- `libs/oshun/` is **domain behaviour**. It composes the shared infrastructure
  and the contracts into the actual product services (`domain-tara`,
  `memory-iris`, `generation-control-isis`). It is allowed to depend on both
  trees below it; they are not allowed to depend on it.

The result is the acyclic foundation the diagram above shows: a change to a
domain service cannot ripple _down_ into the shared infrastructure, and a
contract change is a single, type-checked edit that every consumer sees at once.

## How a request actually moves through the platform

A concrete trace makes the layering tangible. Consider a customer opening their
Tara ritual feed:

1. The surface (the consumer shell) issues an authenticated request to the BFF.
2. `@oshun/bff` validates the session (auth/identity), then calls the Tara
   domain orchestration in `libs/oshun/domain-tara`.
3. `domain-tara` composes substrate calls — it may read memory through
   `memory-iris`, ground a claim through `evidence-sophia`, or check a tone gate
   through `persona-policy-lilith` — and assembles a result.
4. Every payload crossing those boundaries is parsed against a Zod schema from
   `libs/contracts/src/tara` (re-exported at `libs/contracts/src/index.ts`), so
   a malformed shape fails loudly at the boundary rather than silently
   downstream.
5. Persistence reads/writes go through `@oshun/database` and `@oshun/cache`,
   under the residency and deletion rules the data layer owns.
6. The BFF shapes the validated result for the surface and returns it;
   cross-cutting concerns (logging, metrics, tracing) are emitted through the
   `@oshun/*` observability libraries at every hop.

No step in that trace reinvents identity, validation, persistence, or
observability — each is a shared foundation the request borrows.

## Where to go next

- **[Shared Libraries](./shared-libraries.md)** — the `@oshun/*` infrastructure:
  the foundation, observability, data, eventing, and security layers.
- **[Domain Orchestration](./oshun-domain-libraries.md)** — `libs/oshun`: the
  service layer that turns substrates into product capabilities.
- **[Contracts](./contracts.md)** — the Zod contract surface and how the
  boundary validation works.
- **[BFF & Gateway](./bff-gateway.md)** — the backend-for-frontend tier.
- **[Persistence & Data](./persistence-data.md)** — the shared database,
  migration, residency, and deletion foundations.
- **[Auth & Identity](./auth-identity.md)** — the unified identity, session,
  consent, and authorization model.

Every product space references these foundations rather than restating them; the
[systems catalog](../../docs-center/systems/index.html) carries a code-linked
entity node for each underlying package, and the
[coverage report](../../docs-center/meta/coverage.html) tracks the platform
alongside the nine products and the capability domains.