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#
# 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
kuanyinDB, 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.