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.

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.
• 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.
• 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.
• Shared infrastructure (libs/shared/) — the domain-agnostic @oshun/* packages every layer above composes. Detailed in Shared Libraries.
• Persistence — the shared Postgres/Redis/object-store foundation and the residency, migration, and deletion machinery on top of it. Detailed in Persistence & Data.

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.

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 — the @oshun/* infrastructure: the foundation, observability, data, eventing, and security layers.
• Domain Orchestration — libs/oshun: the service layer that turns substrates into product capabilities.
• Contracts — the Zod contract surface and how the boundary validation works.
• BFF & Gateway — the backend-for-frontend tier.
• Persistence & Data — the shared database, migration, residency, and deletion foundations.
• Auth & Identity — the unified identity, session, consent, and authorization model.

Every product space references these foundations rather than restating them; the systems catalog carries a code-linked entity node for each underlying package, and the coverage report tracks the platform alongside the nine products and the capability domains.