# Oshun V1 — Architecture (Page Index)

This directory holds the Oshun V1 architecture documentation, decomposed from
the single [`../ARCHITECTURE.md`](../ARCHITECTURE.md) hub into focused, in-depth
pages. The hub remains the canonical entry point and preserves every heading
anchor (so existing `arch§"…"` cross-references keep resolving); each page below
expands one section with far richer, code-grounded detail.

Companion documents: the product feature map lives in
[`../features/`](../features/README.md), the backlog in
[`../TODOS.md`](../TODOS.md), the dependency registry in
[`../DEPENDENCIES.md`](../DEPENDENCIES.md), and the 2026-06-24 review/audit
ledger in [`../AUDIT_2026-06-24.md`](../AUDIT_2026-06-24.md).

> **Cross-reference convention.** A bare `§N` / `§N.M` points at a section of
> the backlog [`../TODOS.md`](../TODOS.md); `deps§N` points at
> [`../DEPENDENCIES.md`](../DEPENDENCIES.md); page-to-page links are relative
> (`./<slug>.md`, or `../features/<slug>.md` for the companion).

## Architecture landscape

```mermaid
flowchart TB
  Surfaces[Member creator operator and channel surfaces] --> BFF[Oshun BFF and trusted edges]
  BFF --> Domains[Tara Arete Nyx Nisaba Veritas Metis]
  BFF --> Substrates[Sophia Iris Psyche Lilith Isis Aje]
  BFF --> Workbenches[Studio and governed workbenches]
  Domains --> Foundations[Contracts adapters identity tenancy events and audit]
  Substrates --> Foundations
  Workbenches --> Foundations
  Foundations --> Data[(Domain stores blobs queues search and graph projections)]
  Foundations --> External[Model media payment messaging and engine providers]
  Data --> Operations[Observability lifecycle backup restore and release]
  External --> Operations
```

The pages below zoom into each box and boundary. A line represents a governed
contract or effect path, not permission to reach around domain ownership or a
claim that every provider and later-release surface is deployed.

## Orientation

- [V1 Product Promise](./product-promise.md) — what V1 commits to shipping
  across customer, admin, assistant, and platform surfaces.
- [Subsystem Glossary](./glossary.md) — every domain and substrate name mapped
  to the real lib/app that owns it.
- [High-Level Architecture](./high-level-architecture.md) — the runtime
  topology: surfaces → BFF → domain adapters → substrates → data stores.
- [Product Surfaces](./product-surfaces.md) — the customer, operator, tenant,
  and public apps and the shared consumer shell.

## Customer Domains

- [Customer-Facing Domains](./customer-domains.md) — Tara, Arete, Veritas, Nyx,
  Nisaba, and Metis at the contract/data/event level, with their real
  availability tiers (active / beta / planned).

## Platform Substrates

- [Sophia — Grounding Substrate](./substrate-sophia.md) — grounded answers,
  evidence packs, citation trails, retrieval-vs-synthesis labeling.
- [Iris — Assistant Memory Substrate](./substrate-iris.md) —
  profile/session/notebook memory, consent, deletion/export, policy-controlled
  inspection.
- [Psyche — Real-Time Runtime Substrate](./substrate-psyche.md) —
  text/voice/avatar session envelope, turn-taking, transcript and lip-sync
  coherence.
- [Lilith — Contemplative Policy Substrate](./substrate-lilith.md) — tone
  policy, teacher-persona safety, crisis-aware behavior, spiritual-domain
  boundaries.
- [Isis — Generation Control Substrate](./substrate-isis.md) — workflow
  templates, model/provider registries, environment promotion, provenance,
  release gates, rollback.
- [Aje — Non-Custodial Payment Substrate](./substrate-aje.md) — library-only
  Web3 settlement, merchant invoices, per-chain providers, wallet management.
- [Cross-Domain Support](./cross-domain-support.md) — Aja, Yemaya, Themis plus
  the Studio-only Bellona, Hathor, and Neith substrates.

## Foundations, Data, and Communication

- [Foundations](./foundations.md) — contracts, adapters, persistence,
  OpenAPI/codegen, idempotency, multi-tenant routing, queues, event-bus,
  identity/audit.
- [Communication Patterns](./communication-patterns.md) — synchronous BFF
  request lifecycle, asynchronous events, and a worked cross-domain cascade.
- [Data Architecture and Tenancy](./data-architecture-tenancy.md) — per-domain
  databases, shared cluster features, residency, the tenant/consent/memory-scope
  model.
- [Security, Privacy, and Compliance](./security-privacy-compliance.md) — access
  control, operational hardening, and the compliance posture.

## Experiences and Systems

- [Living Scenes](./living-scenes.md) — the conductor/blend/composition pipeline
  that turns an intention into a shareable artifact.
- [Agentic AI Studio](./agentic-ai-studio.md) — the AgentRun lifecycle and the
  multi-agent hand-off protocol.
- [Generation Audience Tiers](./generation-audience-tiers.md) — who can generate
  what, and the surface boundaries between tiers.
- [Search, Discovery, and Knowledge Graph](./search-discovery-knowledge-graph.md)
  — retrieval, recommendations, and the concept graph.
- [Customer Curation](./customer-curation.md) — notebooks, collections, saved
  items, and sharing.
- [Persona, Avatar, and Voice Packs](./persona-avatar-voice-packs.md) — the
  persona/avatar/voice registry and its policy gates.
- [Oshun Studio](./oshun-studio.md) — the authoring, editorial, and curation
  workspace.
- [Messaging Channels](./messaging-channels.md) — the tier-aware channel
  abstraction (Telegram, WhatsApp, email/push/SMS, Discord/Slack).

## Governance, Operations, and Launch

- [Trust, Safety, and Privacy](./trust-safety-and-privacy.md) — abuse handling,
  review, consent, residency, and DSAR.
- [Support, Entitlements, Billing, and the Aje Entitlement Bridge](./support-billing-and-crypto.md)
  — entitlements, billing, and how crypto settlement maps to access.
- [Fiat Payments and Wallets](./fiat-payments-and-wallets.md) — V1.1 Stripe
  billing, Apple Pay, Google Pay, entitlement settlement, provider boundaries,
  webhook invariants, and operational requirements.
- [Observability, Design System, Testing, and Performance](./observability-and-quality.md)
  — release gates, the design system, and the testing/perf posture.
- [Content, Localization, Documentation, and Launch Readiness](./content-localization-and-launch.md)
  — the launch-locale set, content/docs, and launch gates.