Kuanyin Domain — Architecture

Named after Guanyin (觀音), the Bodhisattva of Compassion in East Asian Buddhist traditions — a guardian who remains accessible to guide all beings toward liberation rather than entering solitary nirvana.

Overview#

Kuanyin is the platform-wide ethics, safety, and moderation domain for the entire Oshun ecosystem. Unlike a traditional content-moderation service that focuses on detection and punishment, Kuanyin is designed as a compassion-first guidance system grounded in Buddhist philosophy: every user carries innate potential for wisdom and wholesome action, and the system's job is to create conditions for that potential to flourish.

The domain is implemented as 14 TypeScript libraries with no standalone applications or services. Consuming applications — Lilith, Aphrodite, Hathor, Yemaya, and the broader platform — embed these libraries directly. This library-only design means Kuanyin's moderation logic runs in-process inside the host application, with no extra network hop for every moderation decision.

The architecture reflects the full lifecycle of harm: prevention before content is posted (precognition), intervention during posting (mindful friction), community healing after an incident (community harmony), and restoration of the violating user to full participation (rehabilitation) — with a positive-reinforcement layer (merit and karma) running in parallel to reward wholesome behavior throughout.

Domain Architecture#

The diagram below shows how the 14 libraries are organized into horizontal layers, from the foundation at the bottom to the cross-domain ethics surface at the top. Data and behavior flow upward: consuming applications use the SDK/API or cross-domain integration layer and rely on the feature libraries, which in turn draw on the persistence and foundation layers.

+───────────────────────────────────────────────────────────────────────────+
│                      CROSS-DOMAIN ETHICS LAYER                           │
│                       kuanyin-cross-domain                               │
│   (aphrodite, lilith, hathor, yemaya, platform-wide integrations)        │
+───────────────────────────────────────────────────────────────────────────+
                                    |
+───────────────────────────────────────────────────────────────────────────+
│                       INTELLIGENCE AND ANALYTICS                         │
│                                                                          │
│   kuanyin-ai-ml-models          kuanyin-dharma-analytics                 │
│   (classifiers, analyzers,      (community health, individual paths,     │
│    predictors, generators)       predictive wellness, wisdom reports)    │
+───────────────────────────────────────────────────────────────────────────+
                                    |
+───────────────────────────────────────────────────────────────────────────+
│                          FEATURE LIBRARIES                               │
│                                                                          │
│  PREVENTIVE                  REACTIVE                 RESTORATIVE        │
│  kuanyin-precognition        kuanyin-mindful-friction  kuanyin-rehabilitation │
│  (intent analysis,           (pause/breathe, samma-   (shadow work,     │
│   emotional detection,        vaca, reframing,          empathy training, │
│   typing dynamics,            perspective shift,         restorative     │
│   behavioral patterns,        compassion nudges,         circles,        │
│   context awareness,          alt. expression)           reintegration)  │
│   cascade prediction)                                                    │
│                                                                          │
│  COMMUNITY                   CREATOR PROTECTION       REPUTATION         │
│  kuanyin-community-harmony   kuanyin-performer-        kuanyin-merit-karma │
│  (temperature, conflict,      protection               (accumulation,    │
│   raid defense, healing,      (shield, parasocial,     privilege tiers,  │
│   culture cultivation)        NCII/deepfake,           karma, achievements) │
│                               wellness, dashboard)                      │
+───────────────────────────────────────────────────────────────────────────+
                                    |
+───────────────────────────────────────────────────────────────────────────+
│                       RESTORATIVE INTEGRATION                            │
│                   kuanyin-concordia-restorative                          │
│    (restorative-circle safety pre-flight checklist, Phase 179.7.3)       │
+───────────────────────────────────────────────────────────────────────────+
                                    |
+───────────────────────────────────────────────────────────────────────────+
│                         PERSISTENCE LAYER                                │
│                         kuanyin-database                                 │
│    (25 table schemas, migrations, 15 repositories, seed data)            │
+───────────────────────────────────────────────────────────────────────────+
                                    |
+───────────────────────────────────────────────────────────────────────────+
│                          FOUNDATION LAYER                                │
│                         kuanyin-foundation                               │
│    (BuddhaNature interface, 74 harm categories, six-level severity,      │
│     constants, utilities, error types, environment schema)               │
+───────────────────────────────────────────────────────────────────────────+

Library Organization#

Kuanyin's 14 libraries fall into six roles: a shared foundation that everything else imports, a persistence layer, eight feature libraries that implement distinct behavioral concerns, two intelligence libraries, a public API surface, a UI component library, and a restorative-circle adapter.

Foundation: kuanyin-foundation#

The conceptual root of all Kuanyin libraries. Because every other library imports from it, kuanyin-foundation is built with @nx/esbuild:esbuild (ESM, bundle: false) for the fastest possible rebuild times.

Key exports:

• BuddhaNature interface — The philosophical core: numeric properties modeling a user's compassion, wisdom, mindfulness, karma, goodness, and awakening potential, plus identity and timestamp fields.
• RefugeStatus — Five-stage spiritual progress model (seeking → taking_refuge → established → deepening → realized) that tracks a user's engagement journey through the platform.
• HarmCategoryCode — A 74-code harm taxonomy organized across 10 domains (interpersonal, identity, safety, integrity, exploitation, manipulation, disruption, legal, platform, systemic).
• HarmCategorySeverity — Six-level scale (negligible → low → moderate → high → severe → critical) that determines which intervention systems activate.
• HarmCategoryDomain — The ten harm domains listed above.
• Constants — Ten configuration stores covering thresholds, timing, merit points, rehabilitation durations, performer protection, trust and community health, escalation, shadow work, karma decay, and comprehensive moderation settings.
• Utilities — Twelve lookup stores and 21 pure analysis functions covering everything from harm-potential scoring to restorative-circle scheduling.
• Errors — Domain-specific error hierarchy, a self-contained validation system, input sanitizers, and resilience primitives (rate limiter, circuit breaker, degradation handler).
• Env schema — 30 typed KUANYIN_* environment variables validated at startup.

Persistence: kuanyin-database#

Provides the data layer: 25 table schemas (all kuanyin_-prefixed), migration metadata, 15 typed repository classes, and development seed data. The schemas are modelled as readonly TypeScript interfaces backed by in-memory Map stores with snapshot-based reset; the migration SQL describes the PostgreSQL-backed deployment (a live database service is not wired up in this tree).

Feature Libraries#

Eight libraries, each implementing a distinct stage in Kuanyin's compassionate moderation lifecycle:

Intelligence: kuanyin-ai-ml-models#

Provides interfaces and implementations for the AI/ML models that power precognition, harm classification, and friction content generation. The intelligence layer is deliberately decoupled from the feature libraries: model implementations can be swapped (local model → external API → fine-tuned model) without touching any feature library code.

Public Surface: kuanyin-sdk-api#

The unified public API for consuming applications. Provides the createKuanyinClient() factory that applications use to integrate Kuanyin into their service. Abstracts the internal library structure behind a clean, stable API surface offering REST endpoints, a GraphQL layer, a TypeScript SDK, and a typed event system.

UI: kuanyin-ui-components#

Reusable UI component descriptors — not React components themselves, but typed configuration objects — for moderation interfaces: performer dashboards, community health displays, rehabilitation journey progress, and moderation transparency reports. Platform teams render these descriptors in their own component framework.

Restorative: kuanyin-concordia-restorative#

The restorative-circle safety pre-flight adapter (Phase 179.7.3). It is the only Kuanyin library built with @nx/js:tsc and the only one with runtime dependencies (zod, @concordia/contracts). Its circle-safety module defines seven circle kinds, eleven safety checks, the required-checks map per kind, and the canOpenCircle decision that keeps a circle closed until every required check has passed.

Dependency Model#

The layering below is conceptual, not a runtime import graph. In the current code every Kuanyin library except concordia-restorative is self-contained: each module re-declares the literal-union types and config shapes it needs and ships its own in-memory Map stores, with no cross-library @kuanyin/* imports. concordia-restorative is the only library with runtime dependencies (zod, @concordia/contracts).

                          conceptual layering
─────────────────────────────────────────────────────────────────────
  cross-domain ───────────────────────── platform-wide ethics surface
  sdk-api ─────────────────────────────── REST/GraphQL/event/SDK surface
  ai-ml-models · dharma-analytics ─────── intelligence & analytics
  precognition · mindful-friction ·
  community-harmony · performer-protection ·
  rehabilitation · merit-karma ────────── feature libraries
  concordia-restorative ───────────────── restorative-circle pre-flight
  database ────────────────────────────── persistence schemas
  foundation ──────────────────────────── shared taxonomy & primitives

Each library is built and tested independently. ui-components provides UI configuration descriptors that mirror the foundation and feature-library taxonomies.

Design Patterns#

Understanding these six architectural decisions will help you reason about why the libraries are shaped the way they are.

1. Compassion-First Architecture#

Every design decision in Kuanyin follows a harm-response hierarchy that prioritizes prevention over punishment:

1. Precognition — Can harm be prevented before it occurs?
2. Mindful Friction — If not, can the user be guided away from harm before posting?
3. Community Harmony — If harm occurred, how can the community heal?
4. Rehabilitation — How can the violating user be guided toward wholesome engagement?
5. Merit/Karma — What positive behaviors should be reinforced in parallel?

This ordering reflects the Buddhist principle of preventing harm (ahimsa) as more valuable than punishing it after the fact.

2. Non-Blocking Friction#

All friction patterns in kuanyin-mindful-friction implement a core architectural principle: friction slows but never blocks. After a pause, after a Right Speech prompt, after a rewrite suggestion — the user can always proceed with their original content. This is both a philosophical and a legal design choice:

• Philosophically: forcing a pause respects autonomy while creating space for reflection.
• Legally: blocking speech without a clear terms violation creates liability; friction creates documented evidence that the user had an opportunity to reconsider.

3. esbuild ESM Builds#

All Kuanyin libraries except concordia-restorative build with the @nx/esbuild:esbuild executor (ESM format, bundle: false) for fast, unbundled output. The libraries are predominantly self-contained pure TypeScript — types, constants, in-memory stores, and pure functions — which suits esbuild well. concordia-restorative is the exception: it builds with @nx/js:tsc because it depends on zod and @concordia/contracts, which require TypeScript's declaration-emit for workspace interop.

4. Domain-Specific Integration Modules#

Rather than requiring consuming domains to adapt to a generic moderation API, kuanyin-cross-domain provides domain-specific integration modules. The lilith-integration module is calibrated for adult content creator contexts. The aphrodite-integration module understands relationship and dating interaction patterns. Each module applies the same underlying Kuanyin capabilities with domain-appropriate thresholds and terminology — a hate-raid in a live streaming context is handled differently from consent coercion in a dating app, even though both route through the same underlying harm taxonomy.

5. Immutable Karma Ledger#

The karma and merit system uses an append-only event ledger rather than mutable scores. A user's current karma is always computed by summing the event ledger, never by reading a stored value. This design provides:

• Complete auditability of all karma changes, supporting dispute resolution.
• Ability to replay the karma ledger to reconstruct any historical state.
• Transparency to users about exactly what affected their karma and when.
• No possibility of silent karma manipulation — every change leaves a record.

6. Severity-Gated Interventions#

The intervention pipeline is gated by harm severity, so that the volume of low-severity events does not overwhelm the systems designed for high-severity ones:

• Negligible detections log only — no user-visible action.
• Low severity triggers soft friction — a brief pause.
• Critical severity (CSAM, imminent violence, terrorism) triggers immediate removal and emergency escalation, bypassing all queues.

This gate-based design ensures human review resources are reserved for the cases that need them, and that the most severe harms are never held in a queue.

Technology Stack#

The table below summarizes the technology choices and the rationale for each component.

All libraries define four Nx targets: build, lint, test, typecheck.

Build and Development#

The commands below cover the most common development tasks. Because Nx can fail in worktree environments with duplicate project names, the worktree-safe alternatives are listed alongside the standard Nx commands.

# Test a specific library
pnpm nx test kuanyin-foundation
pnpm nx test kuanyin-precognition

# Build all Kuanyin libraries
pnpm nx run-many --target=build --projects=tag:scope:kuanyin

# Typecheck
pnpm nx typecheck kuanyin-foundation

# Run all domain tests
pnpm nx run-many --target=test --projects=tag:scope:kuanyin

# Worktree-safe type check (use when Nx reports duplicate projects)
cd libs/kuanyin/foundation && npx tsc --noEmit

Service Topology#

Kuanyin has no standalone services. It is a pure library domain.

The domain requires PostgreSQL for persistence (via kuanyin-database). Consuming applications provision this database and pass the connection string through the KUANYIN_DATABASE_URL environment variable. There is no Kuanyin-specific HTTP server, event bus, or background worker — real-time capabilities, if needed, are implemented by the consuming application using the kuanyin-sdk-api client.

Cross-Domain Integration#

Kuanyin integrates with the rest of the Oshun platform through kuanyin-cross-domain. Each integration module is domain-specific rather than generic, because different domains have fundamentally different risk profiles and community norms. The boundary exists because Kuanyin owns the ethics taxonomy and intervention logic, while each domain owns its own content model and user relationships. What crosses the boundary is context: harm scores, severity assessments, intervention triggers, and behavioral patterns — not raw content.

The platform-wide-integration module ensures cross-domain behavioral correlation: harm patterns detected in one domain are visible when evaluating behavior in another. A user with a harassment pattern in Yemaya carries that context into their Aphrodite interactions — users cannot reset their moderation history simply by switching to a different part of the platform.

Domain Boundaries#

Understanding what Kuanyin owns — and explicitly does not own — prevents accidental duplication and keeps integrations clean.

Kuanyin provides:

• Platform-wide harm classification and severity assessment (74-category taxonomy across 10 domains)
• Predictive harm detection (precognition) before content is posted
• Mindful friction intervention patterns that slow but never block expression
• Community health monitoring and conflict resolution
• Performer and creator protection systems including NCII and deepfake defense
• Rehabilitation and restorative justice pathways
• Merit, karma, and achievement systems
• Dharma analytics and transparency reporting
• Domain-specific ethics integration for Aphrodite, Lilith, Hathor, and Yemaya

Kuanyin does not provide:

• Content delivery infrastructure (delegated to each domain's media system)
• Authentication or access control (delegated to consuming applications via @oshun/auth)
• Legal enforcement or law enforcement reporting (consuming applications are responsible for this)
• General user management (delegated to consuming applications)
• News fact-checking (Veritas domain)
• Governance and IP compliance (Themis domain)
• The broader Concordia restorative-mediation flow beyond the safety pre-flight checklist — full apology, restitution, and reintegration mediation remain planned (Phase 179)