# Kalei System Architecture Plan Version: 1.0 Date: 2026-02-10 Status: Proposed canonical architecture for implementation ## 1. Purpose and Scope This document consolidates the existing Kalei docs into one implementation-ready system architecture plan. In scope: - Phase 1 features: Mirror, Kaleidoscope (Turn), Lens, Gallery, subscriptions. - Phase 2 features: Spectrum analytics (weekly/monthly insight pipeline). - Mobile-first architecture (iOS/Android via Expo) with optional web support. - Production operations for safety, privacy, reliability, and cost control. Out of scope: - Pixel-level UI specs and brand copy details. - Provider contract/legal details. - Full threat model artifacts (to be produced separately). ## 2. Inputs Reviewed - `docs/app-blueprint.md` - `docs/kalei-infrastructure-plan.md` - `docs/kalei-ai-model-comparison.md` - `docs/kalei-mirror-feature.md` - `docs/kalei-spectrum-phase2.md` - `docs/kalei-complete-design.md` - `docs/kalei-brand-guidelines.md` ## 3. Architecture Drivers ### 3.1 Product drivers - Core loop quality: Mirror fragment detection and Turn reframes must feel high quality and emotionally calibrated. - Daily habit loop: low friction, fast response, strong retention mechanics. - Phase 2 depth: longitudinal Spectrum insights from accumulated usage data. ### 3.2 Non-functional drivers - Safety first: crisis language must bypass reframing and trigger support flow. - Privacy first: personal reflective writing is highly sensitive. - Cost discipline: launch target under ~EUR 30/month fixed infrastructure. - Operability: architecture must be maintainable by a small team. - Gradual scale: support ~50 DAU at launch and scale to ~10k DAU without full rewrite. ## 4. Canonical Decisions This plan resolves conflicting guidance across current docs. | Topic | Decision | Rationale | |---|---|---| | Backend platform | Self-hosted API-first modular monolith on Node.js (Fastify preferred) | Matches budget constraints and keeps full control of safety, rate limits, and AI routing. | | Data layer | PostgreSQL 16 + Redis | Postgres for source-of-truth relational + analytics tables; Redis for counters, rate limits, caching, idempotency. | | Auth | JWT auth service in API + refresh token rotation + social login (Apple/Google) | Aligns with self-hosted stack while preserving mobile auth UX. | | Mobile | React Native + Expo (local/native builds) | Fastest path for iOS/Android while keeping build pipeline under direct control. | | AI integration | AI Gateway abstraction with provider routing | Prevents hard lock-in and supports quality/cost strategy across open-weight model backends and optional hosted fallbacks. | | AI default | Open-weight Qwen/Llama family via vLLM (Ollama locally) for Mirror/Turn/Safety-sensitive paths at launch | Keeps model stack open-source-first while preserving routing flexibility. | | AI cost fallback | Route low-risk generation (Lens/basic content) to lower-cost providers when budget thresholds hit | Preserves core quality while controlling spend. | | Billing | Self-hosted entitlement authority (direct App Store + Google Play server APIs) | Keeps billing logic in-house and avoids closed SaaS dependency in core authorization path. | | Analytics/monitoring | PostHog self-hosted + GlitchTip + centralized app logs + cost telemetry | Open-source-first observability stack with lower vendor lock-in. | ## 5. System Context ```mermaid flowchart LR user[User] --> app[Expo App] app --> edge[Edge Proxy] edge --> api[Kalei API] api --> db[(PostgreSQL)] api --> redis[(Redis)] api --> ai[AI Providers] api --> billing[Store Entitlements] api --> push[Push Gateway] api --> obs[Observability] app --> analytics[Product Analytics] ``` ## 6. Container Architecture ```mermaid flowchart TB subgraph Client turn[Turn Screen] mirror[Mirror Screen] lens[Lens Screen] spectrum_ui[Spectrum Dashboard] profile_ui[Gallery and Profile] end subgraph Platform gateway[API Gateway and Auth] turn_service[Turn Service] mirror_service[Mirror Service] lens_service[Lens Service] spectrum_service[Spectrum Service] safety_service[Safety Service] entitlement_service[Entitlement Service] jobs[Job Scheduler and Workers] ai_gateway[AI Gateway] cost_guard[Usage Meter and Cost Guard] end subgraph Data postgres[(PostgreSQL)] redis[(Redis)] object_storage[(Object Storage)] end subgraph External ai_provider[Open-weight models via vLLM or Ollama] store_billing[App Store and Play Billing APIs] push_provider[APNs and FCM] glitchtip[GlitchTip] posthog[PostHog self-hosted] end turn --> gateway mirror --> gateway lens --> gateway spectrum_ui --> gateway profile_ui --> gateway gateway --> turn_service gateway --> mirror_service gateway --> lens_service gateway --> spectrum_service gateway --> entitlement_service mirror_service --> safety_service turn_service --> safety_service lens_service --> safety_service spectrum_service --> safety_service turn_service --> ai_gateway mirror_service --> ai_gateway lens_service --> ai_gateway spectrum_service --> ai_gateway ai_gateway --> ai_provider turn_service --> cost_guard mirror_service --> cost_guard lens_service --> cost_guard spectrum_service --> cost_guard turn_service --> postgres mirror_service --> postgres lens_service --> postgres spectrum_service --> postgres entitlement_service --> postgres jobs --> postgres turn_service --> redis mirror_service --> redis lens_service --> redis spectrum_service --> redis cost_guard --> redis jobs --> redis entitlement_service --> store_billing jobs --> push_provider gateway --> glitchtip gateway --> posthog spectrum_service --> object_storage ``` ## 7. Domain and Service Boundaries ### 7.1 Runtime modules - `auth`: sign-up/sign-in, token issuance/rotation, device session management. - `entitlements`: direct App Store + Google Play sync, plan gating (`free`, `prism`, `prism_plus`). - `mirror`: session lifecycle, message ingestion, fragment detection, inline reframe, reflection. - `turn`: structured reframing workflow and saved patterns. - `lens`: goals, actions, daily focus generation, check-ins. - `spectrum`: analytics feature store, weekly/monthly aggregation, insight generation. - `safety`: crisis detection, escalation, crisis response policy. - `ai_gateway`: prompt templates, model routing, retries/timeouts, structured output validation. - `usage_cost`: token telemetry, per-user budgets, global spend controls. - `notifications`: push scheduling, reminders, weekly summaries. ### 7.2 Why modular monolith first - Lowest operational overhead at launch. - Strong transaction boundaries in one codebase. - Easy extraction path later for `spectrum` workers or `ai_gateway` if load increases. ## 8. Core Data Architecture ### 8.1 Data domains - Identity: users, profiles, auth_sessions, refresh_tokens. - Product interactions: turns, mirror_sessions, mirror_messages, mirror_fragments, lens_goals, lens_actions. - Analytics: spectrum_session_analysis, spectrum_turn_analysis, spectrum_weekly, spectrum_monthly. - Commerce: subscriptions, entitlement_snapshots, billing_events. - Safety and operations: safety_events, ai_usage_events, request_logs, audit_events. ### 8.2 Entity relationship view ```mermaid flowchart LR users[USERS] --> profiles[PROFILES] users --> auth_sessions[AUTH_SESSIONS] users --> refresh_tokens[REFRESH_TOKENS] users --> turns[TURNS] users --> mirror_sessions[MIRROR_SESSIONS] mirror_sessions --> mirror_messages[MIRROR_MESSAGES] mirror_messages --> mirror_fragments[MIRROR_FRAGMENTS] users --> lens_goals[LENS_GOALS] lens_goals --> lens_actions[LENS_ACTIONS] users --> spectrum_session[SPECTRUM_SESSION_ANALYSIS] users --> spectrum_turn[SPECTRUM_TURN_ANALYSIS] users --> spectrum_weekly[SPECTRUM_WEEKLY] users --> spectrum_monthly[SPECTRUM_MONTHLY] users --> subscriptions[SUBSCRIPTIONS] users --> entitlement[ENTITLEMENT_SNAPSHOTS] users --> safety_events[SAFETY_EVENTS] users --> ai_usage[AI_USAGE_EVENTS] ``` ### 8.3 Storage policy - Raw reflective content remains in transactional tables, encrypted at rest. - Spectrum dashboard reads aggregated tables only by default. - Per-session exclusion flags allow users to opt out entries from analytics. - Hard delete workflow removes raw + derived analytics for requested windows. ## 9. Key Runtime Sequences ### 9.1 Mirror message processing with safety gate ```mermaid sequenceDiagram participant App as Mobile App participant API as Kalei API participant Safety as Safety Service participant Ent as Entitlement Service participant AI as AI Gateway participant Model as AI Provider participant DB as PostgreSQL participant Redis as Redis App->>API: POST /mirror/messages API->>Ent: Check plan/quota Ent->>Redis: Read counters Ent-->>API: Allowed API->>Safety: Crisis precheck alt Crisis detected Safety->>DB: Insert safety_event API-->>App: Crisis resources response else Not crisis API->>AI: Detect fragments prompt AI->>Model: Inference request Model-->>AI: Fragments with confidence AI-->>API: Validated structured result API->>DB: Save message + fragments API->>Redis: Increment usage counters API-->>App: Highlight payload end ``` ### 9.2 Turn (Kaleidoscope) request ```mermaid sequenceDiagram participant App as Mobile App participant API as Kalei API participant Ent as Entitlement Service participant Safety as Safety Service participant AI as AI Gateway participant Model as AI Provider participant DB as PostgreSQL participant Cost as Cost Guard App->>API: POST /turns API->>Ent: Validate tier + daily cap API->>Safety: Crisis precheck alt Crisis detected API-->>App: Crisis resources response else Safe API->>AI: Generate 3 reframes + micro-action AI->>Model: Inference stream Model-->>AI: Structured reframes AI-->>API: Response + token usage API->>Cost: Record token usage + budget check API->>DB: Save turn + metadata API-->>App: Stream final turn result end ``` ### 9.3 Weekly Spectrum aggregation (background) ```mermaid sequenceDiagram participant Cron as Scheduler participant Worker as Spectrum Worker participant DB as PostgreSQL participant AI as AI Gateway participant Model as Batch Provider participant Push as Notification Service Cron->>Worker: Trigger weekly job Worker->>DB: Load eligible users + raw events Worker->>DB: Compute vectors and weekly aggregates Worker->>AI: Generate insight narratives from aggregates AI->>Model: Batch request Model-->>AI: Insight text AI-->>Worker: Validated summaries Worker->>DB: Upsert spectrum_weekly and monthly deltas Worker->>Push: Enqueue spectrum updated notifications ``` ## 10. API Surface (v1) ### 10.1 Auth and profile - `POST /auth/register` - `POST /auth/login` - `POST /auth/refresh` - `POST /auth/logout` - `GET /me` - `PATCH /me/profile` ### 10.2 Mirror - `POST /mirror/sessions` - `POST /mirror/messages` - `POST /mirror/fragments/{id}/reframe` - `POST /mirror/sessions/{id}/close` - `GET /mirror/sessions` - `DELETE /mirror/sessions/{id}` ### 10.3 Turn - `POST /turns` - `GET /turns` - `GET /turns/{id}` - `POST /turns/{id}/save` ### 10.4 Lens - `POST /lens/goals` - `GET /lens/goals` - `POST /lens/goals/{id}/actions` - `POST /lens/actions/{id}/complete` - `GET /lens/affirmation/today` ### 10.5 Spectrum - `GET /spectrum/weekly` - `GET /spectrum/monthly` - `POST /spectrum/reset` - `POST /spectrum/exclusions` ### 10.6 Billing and entitlements - `POST /billing/webhooks/apple` - `POST /billing/webhooks/google` - `GET /billing/entitlements` ## 11. Security, Safety, and Compliance Architecture ### 11.1 Security controls - TLS everywhere (edge proxy to API origin and service egress). - JWT access tokens (short TTL) + rotating refresh tokens. - Password hashing with Argon2id (preferred) or bcrypt with strong cost factor. - Row ownership checks enforced in API and optionally DB RLS for defense in depth. - Secrets in environment vault; never in client bundle. - Audit logging for auth events, entitlement changes, deletes, and safety events. ### 11.2 Data protection - Encryption at rest for disk volumes and database backups. - Column-level encryption for highly sensitive text fields (Mirror message content). - Data minimization for analytics: Spectrum reads vectors and aggregates by default. - User rights flows: export, per-item delete, account delete, Spectrum reset. ### 11.3 Safety architecture - Multi-stage crisis filter: 1. Deterministic keyword and pattern pass. 2. Low-latency model confirmation where needed. 3. Hardcoded crisis response templates and hotline resources. - Crisis-level content is never reframed. - Safety events are logged and monitored for false-positive/false-negative tuning. ## 12. Reliability and Performance ### 12.1 Initial SLO targets - API availability: 99.5% monthly (Phase 1), 99.9% target by Phase 2. - Turn and Mirror response latency: - p50 < 1.8s - p95 < 3.5s - Weekly Spectrum jobs completed within 2 hours of scheduled run. ### 12.2 Resilience patterns - Idempotency keys on write endpoints. - AI provider timeout + retry policy with circuit breaker. - Graceful degradation hierarchy when budget/latency pressure occurs: 1. Degrade Lens generation first (template fallback). 2. Keep Turn and Mirror available. 3. Pause non-critical Spectrum generation if needed. - Dead-letter queue for failed async jobs. ## 13. Observability and FinOps ### 13.1 Telemetry - Structured logs with request ID, user ID hash, feature, model, token usage, cost. - Metrics: - request rate/error rate/latency by endpoint - AI token usage and cost by feature - quota denials and safety escalations - Tracing across API -> AI Gateway -> provider call. ### 13.2 Cost controls - Global monthly AI spend cap and alert thresholds (50%, 80%, 95%). - Per-user daily token budget in Redis. - Feature-level cost envelope with model routing: - Turn/Mirror: quality-first lane - Lens/Spectrum narrative generation: cost-optimized lane as needed - Prompt caching for stable system prompts. ## 14. Deployment Topology and Scaling Path ### 14.1 Phase 1 deployment (single-node) ```mermaid flowchart LR EDGE[Caddy or Nginx Edge] --> NX[Nginx] NX --> API[API + Workers] API --> PG[(PostgreSQL)] API --> R[(Redis)] API --> AIP[AI Providers] ``` ### 14.2 Phase evolution ```mermaid flowchart LR p1[Phase 1 single VPS API DB Redis] --> p2[Phase 2 split DB keep API monolith] p2 --> p3[Phase 3 separate workers and scale API] p3 --> p4[Phase 4 optional service extraction] ``` ### 14.3 Trigger-based scaling - Move DB off app node when p95 query latency > 120ms sustained or storage > 70%. - Add API replica when CPU > 70% sustained at peak and p95 latency breaches SLO. - Split workers when Spectrum jobs impact interactive endpoints. ## 15. Delivery Plan ### 15.1 Phase A (Weeks 1-4): Platform foundation - API skeleton, auth, profile, entitlements integration. - Postgres schema v1 and migrations. - Mirror + Turn endpoints with safety pre-check. - Usage metering and rate limiting. ### 15.2 Phase B (Weeks 5-8): Product completion for launch - Lens flows and Gallery history. - Push notifications and daily reminders. - Full observability, alerting, and incident runbooks. - Beta load testing and security hardening. ### 15.3 Phase C (Weeks 9-12): Spectrum baseline (Phase 2 readiness) - Vector extraction pipeline and aggregated tables. - Weekly batch jobs and dashboard endpoints. - Data exclusion controls and reset workflow. - Cost optimization pass on AI routing. ## 16. Risks and Mitigations | Risk | Impact | Mitigation | |---|---|---| | Reframe quality variance by provider/model | Core UX degradation | Keep AI Gateway abstraction + blind quality harness + model canary rollout. | | Safety false negatives | High trust and user harm risk | Defense-in-depth crisis filter + explicit no-reframe crisis policy + monitoring and review loop. | | AI cost spikes | Margin compression | Hard spend caps, per-feature budgets, degradation order, model fallback lanes. | | Single-node bottlenecks | Latency and availability issues | Trigger-based scaling plan and early instrumentation. | | Sensitive data handling errors | Compliance and trust risk | Encryption, strict retention controls, deletion workflows, audit logs. | ## 17. Decision Log and Open Items ### 17.1 Decided in this plan - Self-hosted API + Postgres + Redis is the canonical launch architecture. - AI provider routing is built in from day one. - Safety is an explicit service and gate on all AI-facing paths. - Spectrum runs asynchronously over aggregated data. ### 17.2 Open decisions to finalize before build start - Final provider mix at launch: - Option A: Qwen-first on all features via vLLM. - Option B: Qwen for Turn/Mirror and smaller open-weight model for Lens/Spectrum narratives. - Exact hosting target for Phase 2 DB scaling (dedicated VPS vs managed Postgres). - Regional crisis resource strategy (US-first or multi-region at launch). --- If approved, this document should become the architecture source of truth and supersede conflicting details in older planning docs.