# Kuan Yin — Deployment Guide

> Technical doc 32.16.1.8. Operational substrate is specified in §32.17 and the
> infra artifacts under `../../deploy/` (when provisioned).

Kuan Yin libraries are pure TypeScript packages built by Nx
(`@nx/esbuild:esbuild`, ESM, `bundle: false`). They are consumed by the BFF /
service layer rather than deployed as standalone processes; the deployable unit
is the service that imports `@kuanyin/sdk-api` and the engines.

## Build

```bash
# Per-library (bypasses Nx project-graph issues from worktrees):
cd libs/kuanyin/<lib> && npx tsup            # or npx tsc --noEmit to verify
# Via Nx when the graph is healthy:
pnpm nx build kuanyin-<lib>
```

## Runtime topology (target)

- **Stateless engine calls** scale horizontally behind the gateway; the engines
  are deterministic and hold no per-request state.
- **Postgres** (domain-isolated `kuanyin` DB, pgvector) for persistence.
- **Redis** for the real-time shield cache and rate-limit token buckets.
- **Message queue** for the event bus + dead-letter.
- **Model serving** for the six families, with edge nodes for latency-critical
  intent/toxicity paths.

## Environment

Validate configuration at boot with `validateKuanYinEnv` (see
`09-configuration.md`). The service must fail fast if required secrets, database
URLs, or model endpoints are missing.

## Rollout

- **Canary / blue-green** for the gateway and model servers; model deployment
  goes through the evaluation gate (`07-model-documentation.md`) first.
- **Feature flags** gate new friction interventions and model versions so they
  can be ramped per community.
- **Rollback** restores the previous model version
  (`model versioning and rollback`) and gateway image; engine packages are
  versioned semver so a downstream service can pin a known-good release.

## Multi-region

Latency-critical analysis deploys to regional edge nodes (`routeToRegion`
selects the lowest-RTT node); persistence and analytics run in the primary
region with read replicas. Privacy controls (data residency, retention) are
enforced per region — see `13-privacy-implementation.md`.

For the monitoring and alerting that must accompany any deployment, see
`14-monitoring.md`; for incident handling, `15-incident-response.md`.
