Eve library

Kuan Yin — Deployment Guide

Guide

Revision 1

On this page

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.