Docs / system-design.md · mirrored from the repo

System design — the consolidated view

Status: operational reference. One place to see how the whole system fits together, so you don’t have to reassemble it from the plane docs. This is the map; the deep docs are the territory (linked throughout). Foundational decisions live in ARCHITECTURE.md; the why is in PRINCIPLES.md; the how (stack) is in FRAMEWORKS.md.

1. What the system is

An agent-operated vernacular greeting & devotional app. Creative agents research → generate → QA content into a shared catalog; a distribution layer decides what each user sees, when, and whether it’s worth sending; a back-office control plane lets the founder supervise, approve, and flip parts between autonomous and manual. The content pipeline is itself a product surface (P-2).

2. End-to-end flow

flowchart LR
  subgraph Creative["Creative plane (agents)"]
    CH["Creative Head<br/>strategy + briefs"] --> CD["Content Director<br/>brief → shots"]
    CD --> CC["Content Creator<br/>render + embed (batch)"]
  end
  CC --> CAT[("Catalog spine<br/>D1 · R2 · Vectorize")]
  CAT --> H["Heimdall<br/>QA / Judge"] --> PUB{{"Publish gate<br/>(manual now)"}}
  PUB --> DIST["Distribution<br/>candidate→rank→diversify→pace"]
  DIST --> EDGE[("Edge<br/>KV playlists · R2 · Images")]
  EDGE --> APP["Consumer app<br/>daily ritual · share"]
  APP -->|"share-intent (aggregate)"| LOOP(("Feedback"))
  LOOP -->|"Loop A: serve-time"| DIST
  LOOP -->|"Loop B: mine the recipe"| CH
  BO["Back office<br/>monitor · approve · modes"] <--> Creative
  BO <--> CtlDO["Control DO<br/>mode · gate · audit"]
  CtlDO --> H
  Creative & DIST -.->|all model calls| AIG{{AI Gateway}}

The two loops are the heart of it (DIST §9): Loop A feeds share-intent/open/skip into serve-time ranking; Loop B aggregates share-intent by attribute and tells the Creative Head which directions to make more of — production amplification, never distribution amplification (P-4).

3. The two planes

Deliberately split (ARCHITECTURE §3, P-10):

• Execution plane (headless, on Cloudflare) — holds all agent/business logic. Workflows for durable orchestration, Agents SDK (Durable Objects) for stateful agents, Queues for fan-out, Cron for scheduling, all inference via AI Gateway.
• Control plane (the back office, its own app) — UI + a thin control API + the authoritative mode state. It must contain no business logic. Autonomy is governed by a Control Durable Object (globalMode, per-stage stageMode, thresholds, kill switch) that every workflow gate RPCs and that broadcasts mode changes over WebSocket.

4. The catalog spine — the single source of truth

Both agent types and the app read/write one spine (P-11, D8):

• D1 — metadata: content_assets, shots, batch jobs, lineage (typed access via @namaste-ji/catalog).
• R2 — the asset bytes (masters + Cloudflare Images variants).
• Vectorize — one multimodal (image+text) index (dim 1024) serving retrieval, dedup, diversity, taste, and catalog gap analysis (DIST DS-13). A raw-embedding copy is persisted alongside it for offline projection/clustering (FL-4).

Content carries temporal_class (timeless base-load vs time-bound event spikes, DIST DS-3), which drives ranking boosts, retirement, storage tiering, and the generation mix.

5. The agent runtime

Every agent is the Kernel instantiated by a manifest (AK-1) — see agents/AGENT-KERNEL.md:

• A bounded reflect loop (recall → plan → dispatch → merge → calibrated stop) inside one invocation.
• STM (orchestrator-owned working memory, projected read-only to subagents) + LTM (one MemoryPort store scoped by agent_id + domain).
• Subagent-as-tool + context firewall (P-20): subagents return distilled artifact + lineage.
• Control DO outer gate (ship vs escalate), Langfuse-versioned prompts, Markdown artifacts.
• Composed into a topology (orchestrator + subagents, online + offline Consolidation/Steward agents) by agents/ORCHESTRATION.md.

6. Distribution & the feed

Server-side, multimodal-embedding-backed, LLM as the offline brain (DIST §4, P-15):

• Fast path (per request): taste-vector kNN over Vectorize → eligibility filters → heuristic score (quality × context-right × novel-to-you × not-over-circulated) → MMR diversify → pace. No LLM in this loop.
• Slow brain (offline): LLMs infer/refresh preference profiles, tag/cluster content, curate — then distill to embeddings/rulesets the fast path reads cheaply.
• Cold-start is largely a non-problem: context (geo/locale/time/declared prefs) is a strong floor; behaviour refines as it accrues. The Feed Lab is where policies are tuned and simulated (Reels-style) before shipping, using the same rank() (P-14).

7. Runtime surfaces

• Back-office console (apps/console, React+Vite+Pages, same-origin Hono API on Workers, behind Cloudflare Access) — monitor, approve, drive the pipeline, and the Feed Lab. Object presentation follows console/DESIGN-PATTERNS.md.
• Consumer app (frontend TBD, Android-first) — the daily-ritual greeting feed + share.
• Notification service — NOTIFICATION-SERVICE.md.

8. Cross-cutting substrate

9. Subsystem → owning doc

10. Build order (from ARCHITECTURE §9)

1. Catalog data model (D1 + R2 + Vectorize) — the spine. 2. Control DO interface (modes + decisions + audit). 3. First creative Workflow (research → generate → review → gate). 4. Ops Console on top of 1–2. 5. Auth (Access for console; consumer auth when the app exists). Then the distribution serving path + Feed Lab once a diverse catalog exists.