# Kuan Yin - Compassionate Guardianship Platform

> Named after Kuan Yin (觀音) - Bodhisattva of Compassion, "She who hears the
> cries of the world"

A paradigm-shifting approach to platform moderation that moves beyond punitive
enforcement to transformative guardianship. Kuan Yin intercepts harmful intent
before it manifests, transforms moments of harm into opportunities for growth,
protects vulnerable community members (especially performers), and guides those
who cause harm toward rehabilitation and reintegration.

## Domain Philosophy

- **Buddha Nature**: Every user carries innate potential for wisdom and
  compassion
- **Samma Vaca**: Right Speech gates (truth, necessity, kindness) before posting
- **Restorative Justice**: Harm is addressed through healing, not punishment
- **Shadow Work**: Guided self-reflection for those who cause harm
- **Community Harmony**: Collective wellbeing as the north-star metric

## Libraries

| Library              | Package                         | Purpose                                                  |
| -------------------- | ------------------------------- | -------------------------------------------------------- |
| foundation           | `@kuanyin/foundation`           | Core types, constants, utilities, error handling         |
| database             | `@kuanyin/database`             | Prisma schemas, migrations, repositories, seeds          |
| precognition         | `@kuanyin/precognition`         | Intent analysis, emotional detection, typing dynamics    |
| mindful-friction     | `@kuanyin/mindful-friction`     | Samma Vaca gates, breathing pauses, reflection prompts   |
| performer-protection | `@kuanyin/performer-protection` | Creator shields, parasocial detection, hate raid defense |
| rehabilitation       | `@kuanyin/rehabilitation`       | Shadow work, restorative circles, reintegration pathways |
| merit-karma          | `@kuanyin/merit-karma`          | Karma accumulation, merit tiers, trust scores            |
| community-harmony    | `@kuanyin/community-harmony`    | Conflict detection, temperature monitoring, raid defense |
| dharma-analytics     | `@kuanyin/dharma-analytics`     | Community health metrics, transparency reports, wellness |
| ai-ml-models         | `@kuanyin/ai-ml-models`         | Intent classification, harm scoring, behavioral patterns |
| cross-domain         | `@kuanyin/cross-domain`         | Integration with Lilith, Yemaya, Hathor, Aphrodite       |
| sdk-api              | `@kuanyin/sdk-api`              | REST/GraphQL API, webhooks, SDK clients                  |
| ui-components        | `@kuanyin/ui-components`        | Moderation dashboards, friction UIs, analytics views     |

## Quick Start

```bash
# Install dependencies
pnpm install

# Run all kuanyin tests
pnpm nx run-many --target=test --projects=kuanyin-*

# Type check
cd libs/kuanyin/<library>
npx tsc --noEmit -p tsconfig.lib.json

# Run specific library tests
cd libs/kuanyin/<library>
npx vitest run
```

## Architecture

```
libs/kuanyin/
├── foundation/            # Core types, constants, utilities, errors
├── database/              # Prisma schemas, repositories, migrations
├── precognition/          # Pre-send intent & emotional analysis
├── mindful-friction/      # Intervention UX (breathing, reflection)
├── performer-protection/  # Creator safety shields
├── rehabilitation/        # Shadow work & restorative justice
├── merit-karma/           # Karma system & trust scoring
├── community-harmony/     # Community health & conflict detection
├── dharma-analytics/      # Metrics, reports, transparency
├── ai-ml-models/          # ML models for classification
├── cross-domain/          # Integration adapters
├── sdk-api/               # External API surface
└── ui-components/         # Frontend components
```

## Environment Variables

See `libs/kuanyin/foundation/src/env-schema.ts` for the complete environment
variable schema with validation.

Key variables:

| Variable                    | Required | Description                             |
| --------------------------- | -------- | --------------------------------------- |
| `KUANYIN_DATABASE_URL`      | Yes      | PostgreSQL connection string            |
| `KUANYIN_REDIS_URL`         | Yes      | Redis connection for real-time features |
| `KUANYIN_AI_MODEL_ENDPOINT` | No       | Custom AI model endpoint                |
| `KUANYIN_ENCRYPTION_KEY`    | Yes      | Encryption key for sensitive data       |
| `KUANYIN_WEBHOOK_SECRET`    | No       | Webhook signing secret                  |
| `KUANYIN_LOG_LEVEL`         | No       | Logging level (default: info)           |
