# Oshun V1 — Architecture

> **Brand & release scope (2026-08-04).** The consumer product is **Lilith**
> (app + assistant persona) operated by **Oshun Synthetics LTD**; app domain
> `lilith.oshunsynthetics.com`, company site `oshunsynthetics.com` — see
> [`V1/BRAND.md`](./BRAND.md). **V1 launch surfaces are the customer web app and
> PWA only; the native mobile apps and watch companions described below ship
> with V1.1.** Their architecture sections remain accurate but are V1.1
> deliverables.

Status: V1 launch architecture (scope: Oshun V1 only)  
Source: `V1/features.md` (product surface scope), `V1/TODOS.md` (implementation
source of truth)  
Audience: Engineering, architecture, and platform leads building V1  
Date: 2026-05-11 (originated) · 2026-06-24 (refined, decomposed into
`architecture/` pages, and audited against code — see
[`AUDIT_2026-06-24.md`](./AUDIT_2026-06-24.md))

## Purpose

This document describes the runtime, package, and integration architecture that
Oshun V1 must ship behind. It is grounded in the V1 feature map
([`V1/features.md`](./features.md)) and the V1 backlog
([`V1/TODOS.md`](./TODOS.md)), and is anchored to the packages that actually
exist under `apps/oshun/`, `apps/metis/`, `libs/oshun/`, `libs/contracts/`,
`libs/openapi/`, and `libs/shared/`. Where a section names a package, that
package is either present in the workspace today or is named here because V1
requires it to exist. The external dependency registry lives at
[`V1/DEPENDENCIES.md`](./DEPENDENCIES.md).

The root-level [`ARCHITECTURE.md`](../ARCHITECTURE.md) describes the broader
Oshun monorepo (Yemaya, Maya, Iris, Maat, Cybele, Saraswati, Brigid, and other
domains that are out of V1 scope). V1 is a strict subset: six customer-facing
domains, six platform substrates (five product substrates plus the Aje payment
substrate), six cross-domain support subsystems (Aja, Yemaya, and Themis, plus
the Studio-only Bellona, Hathor, and Neith), four operator product surfaces, and
the foundations they share.

## Cross-Reference Convention

This document and its companion feature doc use a consistent reference notation
so a reader can always tell which artifact a citation points at.

- A bare `§N` or `§N.M` resolves to a numbered section of the V1 execution
  backlog, [`V1/TODOS.md`](./TODOS.md) — e.g., `§ 25` is the Living Scenes
  backlog section.
- `deps§N` resolves to a numbered section of the V1 dependency registry,
  [`V1/DEPENDENCIES.md`](./DEPENDENCIES.md).
- `arch§"<anchor>"` resolves to a named section of this document by its heading
  anchor.
- `features§"<anchor>"` resolves to a named section of
  [`V1/features.md`](./features.md) by its heading anchor.

The architecture and feature documents use named heading anchors (the
lowercased, hyphenated heading text). The backlog and dependency registry use
numbered sections. Within this document a cross-reference to another section is
written as `arch§"..."` or as a Markdown link; a bare `§N` always points at the
backlog, never at a section of this document.

## How this document is organized

> **This architecture reference has been decomposed into focused pages under
> [`architecture/`](./architecture/README.md).** This file remains the canonical
> hub: it preserves every section heading (so existing `arch§"…"` and
> `ARCHITECTURE.md#…` anchors keep resolving) and, under each, links to the
> in-depth page that expands it. Start at the
> [architecture page index](./architecture/README.md). The product feature map
> is in [`features.md`](./features.md) / [`features/`](./features/README.md);
> the 2026-06-24 review/audit ledger is in
> [`AUDIT_2026-06-24.md`](./AUDIT_2026-06-24.md).

## V1 Product Promise

The Product Promise is the contract V1 makes to everyone who touches it —
customers, learners, readers, operators, creators, and the institutions that
adopt Oshun as a tenant. It states what the product _is_ (one coherent
customer-admin-assistant-platform system, centered on Tara, spanning a set of
customer-facing domains over a set of platform substrates) and, just as
importantly, how it behaves when things go wrong. It sits at the very top of the
V1 architecture: every surface, domain, substrate, and route described in the
sibling pages exists to keep one of these promises. This page expands the
promise from `../ARCHITECTURE.md` and reconciles its framing language against
what the code in `libs/oshun/` actually encodes, because the honest version of
the promise — including the domain _tiering_ the prose used to flatten — is the
version engineering has to ship.

📄 **Full detail:** [V1 Product Promise](./architecture/product-promise.md)

## Subsystem Glossary

This glossary fixes the vocabulary used everywhere in V1 — package names, route
prefixes, surface tables, and admin taxonomy all inherit from these names. It
serves engineers and architects who need to know which lib or app a name
resolves to, and product/governance leads who need to know what each subsystem
is _responsible for_. It sits beside the V1 Product Promise at the top of the
architecture docs: the promise says what V1 is, this glossary names the parts.
Every name below was verified against a real `package.json` or directory under
`libs/` and `apps/`; where the prose and the code disagree on framing (tiering,
surface counts), the code wins and the discrepancy is called out.

📄 **Full detail:** [Subsystem Glossary](./architecture/glossary.md)

## High-Level Architecture

This page is the one-screen mental model of Oshun V1: how a request travels from
a client surface, through the shared shell and the single BFF, into the
customer-facing domains, down through the platform substrates and the shared
foundations, and finally to the data and runtime stores. It serves engineers and
platform leads who need to know _which box a thing lives in_ before opening any
single subsystem page, and it sits directly above the per-subsystem pages —
Product Surfaces, Customer-Facing Domains, the substrate pages, and Foundations
— that zoom into each layer. It is part of the V1 architecture set hubbed at
../ARCHITECTURE.md.

📄 **Full detail:**
[High-Level Architecture](./architecture/high-level-architecture.md)

## Product Surfaces

This page is the catalog of every place a human actually touches Oshun V1 — the
web app, the mobile apps, the operator consoles, the messaging channels, the
desktop companion, and the supporting service and content surfaces — and how
they are assembled from a small set of shared shell libraries rather than
rebuilt per surface. It serves engineers deciding _which app or lib a feature
belongs in_, and product/design leads who need the real inventory of what ships
and what is still gated. It sits one layer below the High-Level Architecture
(which shows the request path) and beside Customer-Facing Domains (which the
surfaces render); it is part of the V1 architecture set hubbed at
../ARCHITECTURE.md.

📄 **Full detail:** [Product Surfaces](./architecture/product-surfaces.md)

### Customer Web — `apps/oshun/web`

↳ Detailed in [Product Surfaces](./architecture/product-surfaces.md).

### Customer Mobile — `apps/oshun/mobile`

↳ Detailed in [Product Surfaces](./architecture/product-surfaces.md).

### Shared Consumer Shell — `libs/oshun/shell-*`

↳ Detailed in [Product Surfaces](./architecture/product-surfaces.md).

### Operator Surfaces

↳ Detailed in [Product Surfaces](./architecture/product-surfaces.md).

### Account

The account hub — `/profile` and `/settings` composing `ProfileSettingsPanel`
(`apps/oshun/web/src/components/ProfileSettingsPanel.tsx`) over the
authenticated `/v1/profile` + `/v1/preferences` projections in
`apps/oshun/bff/src/routes/profile.ts`, with seven specialization routes
(memory, persona, notifications, safety, telegram, data, billing) fronting the
Iris adapter, Lilith safety policy, consent/DSAR, and entitlement subsystems.
Architecture of the composed substrates:
[Iris](./architecture/substrate-iris.md),
[Lilith](./architecture/substrate-lilith.md),
[Trust, Safety, and Privacy](./architecture/trust-safety-and-privacy.md),
[Support, Billing, and Crypto](./architecture/support-billing-and-crypto.md).
Feature reference:
[Account, Profile, and Settings](./features/account-and-profile.md).

### Atelier

The customer generative workshop — eight `/atelier*` routes rendering the
five-room components in `apps/oshun/web/src/components/lilith/atelier.tsx`, with
fixture-backed room data (`lib/lilith-data/atelier-depth.ts`, planned per-room
BFF contracts named in its header), a real fail-closed casting seam
(`POST /v1/atelier/cast` → Stability SD3.5 via
`generation/image-provider-env.ts`, `503 provider_not_configured` without
credentials), and owner-scoped Postgres scene persistence
(`v1_atelier_atelier_scene`). Sits on the generation control plane:
[Isis](./architecture/substrate-isis.md),
[Generation Audience Tiers](./architecture/generation-audience-tiers.md).
Feature reference: [The Atelier — Five Rooms of Making](./features/atelier.md).

### Public Web and Distribution

↳ Detailed in [Product Surfaces](./architecture/product-surfaces.md).

## Customer-Facing Domains

The six customer-facing domains — **Tara, Arete, Veritas, Nyx, Nisaba, Metis** —
are the experiences members actually open: contemplative ritual, humane habit
coaching, grounded news, sky-watching, scholarly reading, and structured
learning. Each is a self-contained vertical with its own Zod contracts, a typed
read adapter consumed by the shell/admin/assistant, a BFF route prefix, and a
web surface tree, yet all six share one registry, one persistence boundary, and
one set of platform substrates (Sophia, Iris, Lilith, Psyche, Isis). This page
is the architectural reference for those six verticals; it sits below the
High-Level Architecture and beside Product Surfaces, and it deliberately
separates what is genuinely shipped from what is spec-described, provider-gated,
or planned.

📄 **Full detail:**
[Customer-Facing Domains](./architecture/customer-domains.md)

### Domain Registry

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

### Tara

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

### Arete

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

### Veritas

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

#### Editorial state machine

### Nyx

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

### Nisaba

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

### Metis

↳ Detailed in [Customer-Facing Domains](./architecture/customer-domains.md).

#### Adaptive learning loop

## Platform Substrates

Each of these has a dedicated page:
[Sophia — Grounding Substrate](./architecture/substrate-sophia.md) ·
[Iris — Assistant Memory Substrate](./architecture/substrate-iris.md) ·
[Psyche — Real-Time Runtime Substrate](./architecture/substrate-psyche.md) ·
[Lilith — Contemplative Policy Substrate](./architecture/substrate-lilith.md) ·
[Isis — Generation Control Substrate](./architecture/substrate-isis.md) ·
[Aje — Non-Custodial Payment Substrate](./architecture/substrate-aje.md) ·
[Cross-Domain Support](./architecture/cross-domain-support.md).

### Sophia

Sophia is the platform substrate that lets every Oshun domain _speak only when
grounded_: it turns a question plus retrieved sources into a cited answer,
scores the credibility of those sources, and refuses to fabricate synthesis it
cannot support. It is a **substrate, not a shell peer** — it has no consumer tab
of its own (its only direct surface is an operator/research workbench) and
instead backs Veritas, Metis, Tara, Arete, Nyx, Nisaba, Studio, and the
assistant through a stable evidence adapter. This page sits among the
platform-substrate deep-dives in the V1 architecture set hubbed at
../ARCHITECTURE.md, alongside Iris, Psyche, Lilith, Isis, and Aje.

📄 **Full detail:**
[Sophia — Grounding Substrate](./architecture/substrate-sophia.md)

#### Grounding pipeline

↳ Detailed in
[Sophia — Grounding Substrate](./architecture/substrate-sophia.md).

#### Ingestion pipeline + source lifecycle

### Iris

Iris is the V1 assistant **memory and identity substrate**: it decides what the
platform is allowed to remember about a member, under what consent, in which
scope, and — critically — what it is allowed to _say back_ to them during a
recall. It serves every customer-facing surface that needs continuity (the
assistant shell, Tara/Veritas/Nyx/Arete/Nisaba/Metis, Living Scenes, and the
operator support workbench) and it is the spine of every data-rights, consent,
suppression, and admin-inspection flow on the platform. This page sits among the
platform-substrate deep-dives in the V1 architecture set hubbed at
../ARCHITECTURE.md, alongside Sophia, Psyche, Lilith, Isis, and Aje.

📄 **Full detail:**
[Iris — Assistant Memory Substrate](./architecture/substrate-iris.md)

#### Memory recall resolution

### Psyche

Psyche is the V1 **real-time embodiment substrate**: it owns the contract for a
live text / voice / avatar session — the session envelope, server-mediated
turn-taking, interruption and barge-in, transcript synchronization, lip-sync and
expression coherence, latency budgeting, provider failover, and continuity under
reconnect or a safety crisis. It serves every surface where a member talks
_with_ an assistant in real time rather than reading a response (the live
assistant shell, the embodied teacher personas, conferencing, and the Living
Scenes frame stream), and it sits among the platform-substrate deep-dives hubbed
at ../ARCHITECTURE.md, alongside Sophia, Iris, Lilith, Isis, and Aje.

📄 **Full detail:**
[Psyche — Real-Time Runtime Substrate](./architecture/substrate-psyche.md)

### Lilith

Lilith is the V1 platform substrate that decides _how Oshun is allowed to speak_
in contemplative and spiritually-sensitive contexts: it sets the contemplative
tone, holds the line on teacher-persona safety, detects and frames crisis,
governs voice-quality and voice-abuse, and refuses unsafe medical / financial /
prophetic / boundary-crossing claims. Like Sophia, Iris, and Psyche, it is a
**substrate, not a shell peer** — it has no consumer tab of its own and instead
binds policy into the assistant, the persona/voice publish paths, Tara
invitations, and Living-Scenes renders through a single adapter. This page sits
among the platform-substrate deep-dives hubbed at ../ARCHITECTURE.md, alongside
Sophia, Iris, Psyche, Isis, and Aje.

📄 **Full detail:**
[Lilith — Contemplative Policy Substrate](./architecture/substrate-lilith.md)

#### Crisis recovery journey

### Isis

Isis is the V1 **governed-generation control plane** — the single, fail-closed
seam every generated artifact (image, video, audio, 3D mesh, texture, document)
must pass through before it can reach a customer-facing surface or land in the
data lake. It is a _substrate_, not a consumer tab: it has no shell of its own,
and instead binds workflow templates, model and provider registries, environment
promotion, provenance bundles, release gates, failover, and rollback into one
typed adapter that the BFF, the assistant, Living Scenes, Tara, Veritas, and the
operator admin surfaces all dispatch through. This page sits among the
platform-substrate deep-dives hubbed at ../ARCHITECTURE.md, alongside Sophia,
Iris, Psyche, Lilith, and Aje.

📄 **Full detail:**
[Isis — Generation Control Substrate](./architecture/substrate-isis.md)

### Aje

`Aje` is V1's blockchain and Web3 payment substrate — the library-only domain
(`libs/aje/`) that lets Oshun accept money without ever custodying customer
funds and without a centralized processor in the middle. Named for the Yoruba
orisha of wealth, commerce, and the marketplace, it serves the billing and
entitlement surfaces (a learner upgrades to a paid tier by paying in crypto)
through one Oshun-specific glue library, `libs/oshun/payments-bridge/`. This
page specifies what Aje ships, the five chains V1 contributes, and the bridge
that turns an on-chain confirmation into an Oshun entitlement — and it is candid
about where the wiring is real versus where it is spec-only or provider-gated.

📄 **Full detail:**
[Aje — Non-Custodial Payment Substrate](./architecture/substrate-aje.md)

## Cross-Domain Support

Beneath the six customer-facing verticals (Customer-Facing Domains) and the six
platform substrates sit a set of **cross-domain subsystems** — Aja, Yemaya,
Themis, Bellona, Hathor, and Neith. These are not first-class V1 customer
domains: a member never navigates to "Bellona" the way they open Tara or Metis.
They are launch-blocking _enablers_ — embodied-instruction services, rendering
substrates, integrity adjudicators, engine bridges, narrative authoring trees,
and inverse-modeling pipelines — that the shipping customer features and Oshun
Studio depend on. This page sits below the High-Level Architecture and beside
Customer-Facing Domains; it deliberately separates the thin adapter seam each
subsystem exposes from the large domain tree that lives behind it.

📄 **Full detail:**
[Cross-Domain Support](./architecture/cross-domain-support.md)

## Foundations

The foundation layer is the shared substrate every V1 surface stands on: the
contracts that define each object once, the persistence machinery that keeps
those contracts and the database in lockstep, the BFF middleware chain that
guards every write, and the queue/event/integration/identity plumbing that makes
the customer-facing domains and product surfaces interoperable. It serves
engineers across every domain — none of them re-implement idempotency,
residency, audit, or eventing — and it sits underneath the High-Level
Architecture, between the domain adapters and the raw infrastructure. The work
is tracked in TODOS § 1, and almost every piece below is real code with tests
already in the repo; where something is contract-level rather than a live
deployment, this page says so.

📄 **Full detail:** [Foundations](./architecture/foundations.md)

### 1. Contracts — `libs/contracts/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 2. Adapters — `libs/oshun/domain-*` and substrate adapters

↳ Detailed in [Foundations](./architecture/foundations.md).

### 3. Persistence — `libs/oshun/persistence/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 4. OpenAPI and codegen — `libs/openapi/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 5. Idempotency, partial-failure, response normalization

↳ Detailed in [Foundations](./architecture/foundations.md).

### 6. Multi-tenant routing — `libs/shared/data-residency/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 7. Background-job substrate — `libs/shared/queue/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 8. Webhook and event-bus plumbing — `libs/shared/event-bus/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 9. Inbound integration plumbing — `libs/shared/inbound-integrations/`

↳ Detailed in [Foundations](./architecture/foundations.md).

### 10. Identity, auth, and audit

↳ Detailed in [Foundations](./architecture/foundations.md).

## Communication Patterns

This page describes how the parts of Oshun V1 talk to each other: the
synchronous request paths between client surfaces, the BFF, and per-domain
services; the asynchronous event bus and job queues that carry cross-domain side
effects; and the shared middleware contracts (idempotency, tenant routing,
residency, the partial-failure envelope, audit) that every write threads
through. It is the "plumbing" companion to Foundations and High-Level
Architecture, and it serves anyone wiring a new domain route, subscribing to a
new topic, or reasoning about what happens when a write half-succeeds.
Everything here maps to real code under `libs/shared/`, `libs/oshun/`,
`libs/contracts/`, `libs/openapi/`, and `libs/proto/`; where a capability is
contracts-level or provider-gated rather than deployed, that is called out
explicitly.

📄 **Full detail:**
[Communication Patterns](./architecture/communication-patterns.md)

### Synchronous

↳ Detailed in
[Communication Patterns](./architecture/communication-patterns.md).

### Request lifecycle through the BFF

↳ Detailed in
[Communication Patterns](./architecture/communication-patterns.md).

### Asynchronous

↳ Detailed in
[Communication Patterns](./architecture/communication-patterns.md).

### Cross-domain event examples (V1)

↳ Detailed in
[Communication Patterns](./architecture/communication-patterns.md).

### Example flow — Veritas claim retraction cascade

↳ Detailed in
[Communication Patterns](./architecture/communication-patterns.md).

## Data Architecture and Tenancy

How V1 stores data, isolates tenants, and routes every request to the right data
plane. This page is for engineers and operators who need to reason about _where_
a piece of data lives, _who_ is allowed to touch it, and _how_ the foundation
libraries enforce those boundaries. It sits in the Foundations layer of V1 —
below the Customer-Facing Domains and the substrates (Sophia, Iris, Psyche,
Lilith, Isis, Aje), and is the substrate the BFF request lifecycle runs on top
of.

📄 **Full detail:**
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md)

### Per-domain databases

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

### Shared cluster features

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

### Optional stores (per Docker dev profiles)

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

### Residency

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

### Tenancy

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

### Tenant, consent, and memory-scope model

↳ Detailed in
[Data Architecture and Tenancy](./architecture/data-architecture-tenancy.md).

## Living Scenes

Living Scenes is the V1 cross-cutting product surface that turns a stated
intention into a 4–8 minute, watermarked, re-renderable artifact the customer
keeps in a personal gallery. It serves contemplative customers (a Tara breath
arc), curious ones (a Nyx sky briefing, a Veritas grounded explainer, a Metis
lesson visualizer), and creators (an Arete living offering), and it sits
_across_ the platform substrates rather than inside any single one: Yemaya owns
the rendering substrate and the runtime, Psyche carries the live-direction
envelope, Isis governs generation, Lilith enforces tone, and Sophia grounds the
fact-bearing templates. This page is hubbed at ../ARCHITECTURE.md alongside the
substrate deep-dives (Yemaya/Psyche runtime, Isis, Lilith, Sophia). Product
scope: `V1/features.md` § Living Scenes. Backlog: §25.

📄 **Full detail:** [Living Scenes](./architecture/living-scenes.md)

### Conductor flow — intention to artifact

↳ Detailed in [Living Scenes](./architecture/living-scenes.md).

### Shareability matrix

↳ Detailed in [Living Scenes](./architecture/living-scenes.md).

### Composition flow and cinematographic technique selection

↳ Detailed in [Living Scenes](./architecture/living-scenes.md).

## Agentic AI Studio

The Agentic AI Studio is V1's **governed autonomy plane** — the registry,
run-envelope, budget, kill-switch, grant-resolver, hand-off, mode, and
champion-challenger machinery that lets agents do real work (research, drafting,
fact-checking, narration, course generation, support triage) without ever
escaping the platform's tone, grounding, entitlement, and cost guardrails. It
serves operators (who arm kill switches and promote challengers), creators and
customers (who invoke entitlement-gated pipelines), and every domain that wants
to ship an autonomous workflow. It sits beside the platform substrates hubbed at
../ARCHITECTURE.md and composes them: it grounds through Sophia, enforces tone
through Lilith, generates through Isis, and remembers through Iris.

📄 **Full detail:** [Agentic AI Studio](./architecture/agentic-ai-studio.md)

### AgentRun lifecycle

↳ Detailed in [Agentic AI Studio](./architecture/agentic-ai-studio.md).

### Multi-agent hand-off protocol

↳ Detailed in [Agentic AI Studio](./architecture/agentic-ai-studio.md).

## Generation Audience Tiers

Every AI generation in V1 — a curated devotional image, a narrated contemplative
arc, an instrumental ambient bed, a creator's raw ComfyUI graph, an operator's
RunPod dashboard — is gated by a single, deterministic **tier resolver** before
a pixel or sample is produced. This page documents the canonical tier taxonomy,
the 28 named generation surfaces and their per-tier allowlists, the enforcement
spine a request crosses (entitlements → Lilith → Isis → provider → provenance →
audit), and the real, provider-gated execution substrate behind it. It serves
product, platform, and operator readers who need to know exactly what a given
audience can do and where the fail-closed boundaries sit. It lives in the
generation-pipeline area alongside Agentic AI Studio and Living Scenes, and
rests on the Isis — Generation Control Substrate.

📄 **Full detail:**
[Generation Audience Tiers](./architecture/generation-audience-tiers.md)

### Generation request flow

↳ Detailed in
[Generation Audience Tiers](./architecture/generation-audience-tiers.md).

## Search, Discovery, and Knowledge Graph

Search and discovery are the cross-domain "find anything, then see what to do
next" surfaces of V1. They serve every member who opens the universal search
sheet or scrolls a mixed-domain recommendation rail, and they sit one layer
above the six customer domains (Tara, Veritas, Nyx, Arete, Nisaba, Metis) —
fanning queries out to each domain's data and blending the results back into one
ranked list inside the BFF. This page is candid about a split that the rest of
the V1 docs glossed over: there are **two** search stacks in this repo, and only
the simpler one ships. The live `/v1/search` and `/v1/recommendations` paths use
deterministic, lexical, domain-fan-out ranking over data the system actually
holds; a much richer signal/candidate/ranker stack
(`libs/oshun/search-discovery`) exists, is fully tested, and is **explicitly
retired from V1 scope**. Read this page as the description of what runs, with
the aspirational library called out honestly wherever it appears.

📄 **Full detail:**
[Search, Discovery, and Knowledge Graph](./architecture/search-discovery-knowledge-graph.md)

## Customer Curation

Customer Curation is the V1 **personal-knowledge layer**: the surfaces that let
a member keep, organize, annotate, share, and re-find anything they encounter
anywhere on the platform — a Veritas claim, a Nisaba passage, a Nyx sky event, a
Metis lesson, a Tara meditation transcript, an Arete habit, or a generated
artifact. It serves every customer-facing domain rather than belonging to any
one of them, and it is the substrate that Search and Recommendations read back
from (see Search, Discovery, and Knowledge Graph). This page sits among the
cross-cutting product-surface deep-dives in the V1 architecture set hubbed at
../ARCHITECTURE.md; product scope lives in `V1/features.md` § Customer Curation,
Notebooks, Collections, and Sharing, and the backlog is `V1/TODOS.md` § 17.

📄 **Full detail:** [Customer Curation](./architecture/customer-curation.md)

## Trust, Safety, Privacy, and Support

Trust, Safety, and Privacy is the governance spine of Oshun V1: the
deterministic policy logic that decides what content and behavior is allowed,
how fast a harm gets triaged, who may appeal, when a crisis frame is broadcast
across every surface, what a user has consented to, where their data may legally
live, and how a deletion or data-subject-access request is honored end-to-end.
It serves three distinct audiences at once — the **customers** whose safety and
privacy are at stake, the **operators** (trust-and-safety reviewers, support
agents, privacy operators) who work the queues, and the **regulators** whose
regimes the platform must satisfy. It sits among the governance pages hubbed at
../ARCHITECTURE.md, directly alongside its companion Support, Entitlements,
Billing, and the Aje Entitlement Bridge, and it is the policy half of the same
substrate that Lilith — Contemplative Policy Substrate supplies the
contemplative-tone half of.

📄 **Full detail:**
[Trust, Safety, and Privacy](./architecture/trust-safety-and-privacy.md)

### Trust and Safety

↳ Detailed in
[Trust, Safety, and Privacy](./architecture/trust-safety-and-privacy.md).

#### Crisis-frame cascade

↳ Detailed in
[Trust, Safety, and Privacy](./architecture/trust-safety-and-privacy.md).

### Privacy, Consent, Residency, DSAR

↳ Detailed in
[Trust, Safety, and Privacy](./architecture/trust-safety-and-privacy.md).

#### DSAR / deletion sequence

### Support, Entitlements, Billing

This page specifies how V1 supports customers, gates capabilities behind tiers,
and takes money — with crypto as the V1-primary rail. It serves three audiences:
support operators working cases and refunds, the entitlement and billing
engineers who wire payment settlement to product access, and the security
reviewers who need to know exactly which crypto-settlement claims are
**implemented** versus **provider-gated / aspirational**. It sits downstream of
the Aje payment substrate and upstream of the entitlement gate enforced at the
BFF; the connective tissue is the `@oshun/payments-bridge` library and the
`@oshun/billing-support` entitlement linkage.

📄 **Full detail:**
[Support, Entitlements, Billing, and the Aje Entitlement Bridge](./architecture/support-billing-and-crypto.md)
·
[Fiat Payments — Stripe Billing, Apple Pay, and Google Pay](./architecture/fiat-payments-and-wallets.md)

### Crypto Payment Substrate — Aje and the V1 Entitlement Bridge

↳ Detailed in
[Support, Entitlements, Billing, and the Aje Entitlement Bridge](./architecture/support-billing-and-crypto.md).

#### What Aje already provides

#### Five new chain modules added to Aje for V1

#### V1 entitlement bridge — `libs/oshun/payments-bridge/`

## Persona, Avatar, and Voice Packs

Every voice the customer hears, every face they see, and every persona they
converse with is governed by one **cross-cutting catalog with consent, lineage,
and lifecycle metadata**. This catalog is not a per-domain concern: a single
registry binds a persona's role and policy pack, its voice profile, its avatar
pack, and the consent artifacts that license its likeness, then enforces a
release gate before any of it reaches a member. This page sits beside
Cross-Domain Support and Trust, Safety, and Privacy; the product scope is
`V1/features.md` § Persona, Avatar, and Voice Packs and the backlog is §14.

📄 **Full detail:**
[Persona, Avatar, and Voice Packs](./architecture/persona-avatar-voice-packs.md)

## Oshun Studio — Authoring, Editorial, Curation

Oshun Studio is the operator- and creator-facing surface where every authored
artifact — Veritas stories, Nisaba editions, Metis lessons, Tara passages,
ritual scripts, persona/voice packs, and Living Scene scores — is drafted,
reviewed, curated, localized, versioned, and published. It is **not** a separate
application: it ships as a subroute tree under `apps/oshun/web/src/app/studio/`
(see the `V1/TODOS.md` audit snapshot, §16), backed by the real domain library
`@oshun/studio-authoring`. Studio builds on the platform substrates — Sophia
(grounding/evidence), Isis (generation control), Lilith (policy), and Iris
(memory) — and is consumed by customer-side creators and operator-side editors
alike. Product scope lives in `V1/features.md` § Content Authoring, Curation,
and Editorial Operations; backlog is §16.

📄 **Full detail:**
[Oshun Studio — Authoring, Editorial, Curation](./architecture/oshun-studio.md)

### Editorial lifecycle

↳ Detailed in
[Oshun Studio — Authoring, Editorial, Curation](./architecture/oshun-studio.md).

## Messaging Channels

Messaging Channels is the V1 subsystem that takes an _outbound intent_ — a
ritual reminder, a grounded answer, a transactional receipt, a crisis hotline —
and decides **whether**, **on which channel**, **in which content variant**, and
**under whose consent and residency** it is allowed to reach a member, then
hands a normalized result back to the caller. It serves every customer-facing
domain that wants to leave the web app (Telegram chat and Mini Apps, WhatsApp,
email, push, SMS, Slack, Discord) plus the in-app message center, and it sits
between the domain runtimes and the real provider APIs in the V1 architecture
set hubbed at ../ARCHITECTURE.md. Product scope: `V1/features.md` § Messaging
Channels and Conversational Surfaces.

📄 **Full detail:** [Messaging Channels](./architecture/messaging-channels.md)

## Security, Privacy, and Compliance

This page is the consolidated security, privacy, and compliance surface for
Oshun V1: how identity is established, how authorization is scoped, how
sensitive actions are gated, where secrets live, how every artifact and mutation
is made provenance-bearing and tamper-evident, and how a user's right to
consent, export, and erasure is enforced down to the row. It serves engineers
building any customer domain (none of them re-implement auth, residency, or
audit) and operators running DSAR, moderation, and break-glass workflows. It
sits in the Foundations layer, underneath the High-Level Architecture and beside
Trust, Safety, and Privacy, and most of what follows is real code with tests
already in the repo.

📄 **Full detail:**
[Security, Privacy, and Compliance](./architecture/security-privacy-compliance.md)

## Observability, Evaluation, and Release Gates

This page covers the platform-quality spine that sits underneath every Oshun V1
surface: how the system is observed and evaluated, how its visual and
interaction language is encoded as code, how it is tested, and how its
performance is budgeted and enforced. These concerns are cross-cutting — they
serve every customer-facing domain (Tara, Veritas, Nyx, Arete, Nisaba, Metis),
the admin/Studio surfaces, and the substrates (Sophia, Iris, Psyche, Lilith,
Isis, Aje) — and they are where "is V1 ready to ship?" is actually answered. For
the most part this is implemented, tested code, not a spec: the i18n catalog,
analytics taxonomies and manifests, design tokens, the UI component library, and
the design-language audit modules are all real, sizeable, exercised libraries.
What remains genuinely operational — the launch drills, pen-test signoff, and
go/no-go gates — is described candidly as process in Content, Localization,
Documentation, and Launch Readiness.

📄 **Full detail:**
[Observability, Design System, Testing, and Performance](./architecture/observability-and-quality.md)

## Design System and Experience Quality

↳ Detailed in
[Observability, Design System, Testing, and Performance](./architecture/observability-and-quality.md).

## Testing, Accessibility, Performance

↳ Detailed in
[Observability, Design System, Testing, and Performance](./architecture/observability-and-quality.md).

## Content, Localization, and Documentation

This page covers the last mile before V1 ships: how strings and content are
localized, how the product is documented for customers and operators, and the
operational gates that must clear before general availability. It serves
everyone who touches a customer-visible artifact — the domain teams (Tara,
Veritas, Nyx, Arete, Nisaba, Metis), the Studio editorial/translation surface,
support, and launch operations — and it sits at the top of the quality stack, on
top of the observability, design-system, and testing machinery described in
Observability, Design System, Testing, and Performance.

📄 **Full detail:**
[Content, Localization, Documentation, and Launch Readiness](./architecture/content-localization-and-launch.md)

## Launch Readiness

↳ Detailed in
[Content, Localization, Documentation, and Launch Readiness](./architecture/content-localization-and-launch.md).

## Cross-References