Docs / frameworks.md · mirrored from the repo

Frameworks, stack & patterns

Status: operational reference. The technologies the system runs on and the recurring code patterns we apply, with the why for each. Choices are Cloudflare-first (P-9); the deep rationale lives in BACK-OFFICE.md (BO-*) and ARCHITECTURE.md (D-*). Companion to SYSTEM-DESIGN.md and PRINCIPLES.md.

1. Runtime substrate (Cloudflare)

Layer	Tech	Role / notes
Durable orchestration	Cloudflare Workflows	GA durable execution: per-step retries, persisted state, `waitForEvent` for human gates. The orchestration spine (`BO-2`).
Stateful agents	Cloudflare Agents SDK (`agents`)	Each agent is a Durable Object (identity, SQLite state, WebSockets, scheduling, `agents/observability`). Avoid preview bits on the critical path.
Request handlers	Workers (+ Hono for services)	`console-api` and agents are Workers; Hono is the HTTP framework.
Frontend	React + Vite → Cloudflare Pages	`apps/console` (Direct Upload, CI-deployed). Consumer frontend TBD (Android-first).
Async fan-out	Queues	Pipeline render/embed have independent queues for independent backpressure; one shared DLQ.
Scheduling	Cron Triggers + Agents scheduled tasks	Rollout, prefetch, profile/playlist rebuilds, batch polling.
Research	Browser Rendering	Scraping/inspiration where needed.

2. Data & storage

Concern	Tech	Pattern
Metadata / control / audit	D1 (SQLite)	No ORM — typed access modules over raw prepared statements; the row shape is a JSON `payload` + a few promoted/indexed columns (see `@namaste-ji/catalog`). Parse payload → contract on read; keep indexed columns in sync on write.
Asset bytes	R2 + Cloudflare Images	Masters + device/network-sized variants; cache-first (P-7).
Operational config	KV (`@namaste-ji/config`)	Non-safety knobs; anything safety-shaped goes in the Control DO, not KV.
Vectors	Vectorize (cloud) / Qdrant (local)	Behind a `VectorIndex` port; one multimodal index (dim 1024) for retrieval/dedup/diversity/analysis.

3. Model & AI layer

Concern	Tech	Notes
Model interface	Vercel AI SDK (`ai`) behind `ModelPort` / `EmbedderPort`	Provider-agnostic `LanguageModel`/`EmbeddingModel`; our own interface so a provider swap is config (`BO-2`).
Routing/cost/cache/logs	AI Gateway	All production model calls route through it; BYOK (provider keys live in the gateway, not code).
Prompt registry + tracing + evals	Langfuse	Prompts resolved by `name@label` (cache + last-known-good fallback); resolved version logged in the trace. AI Gateway routes; Langfuse registers/traces — separate concerns (`AK-6`).
Text LLM (local)	Ollama (OSS models)	Local dev loop; behavioural parity, not identical to prod model.
Multimodal embeddings (local)	Infinity + `jina-clip-v2`	Ollama can’t embed images; Infinity is the local CLIP workhorse.
Multimodal embeddings (cloud)	Jina CLIP v2 / Cohere embed-v4 / Voyage or Workers AI	Behind `EmbedderPort`; Matryoshka-truncatable to the index dim.

Considered, not adopted: Mastra (great TS agent framework, but brings its own durable-workflow + memory model that overlaps Workflows + Agents-SDK-on-DO — we borrow its ideas, e.g. evals-first, not its runtime, BO-2).

4. Contracts, types & validation

Zod versioned contracts in @namaste-ji/shared are the interface between components: the brief, the Content Strategy (strategy@vN), FeedPolicy, OnboardingSignals. A downstream agent consumes one cold, so contracts are immutable + versioned + reproducible (CP-3, FL-2, P-13).
TypeScript everywhere (incl. infra — Alchemy is pure TS). @cloudflare/workers-types on Workers.

5. Control, auth & governance

Concern	Tech
Autonomy / gates / kill switch	Control Durable Object (policy engine, WebSocket broadcast)
BO auth	Cloudflare Access (perimeter SSO/MFA) + D1 RBAC (`@namaste-ji/rbac`) — coarse in Access, fine in app
Consumer auth	Better Auth on Workers (D1-native, phone-OTP + social, no per-MAU fee)
Secrets	Cloudflare Secrets Store (`secrets_store_secrets` bindings)
Experimentation	Statsig — deferred to the consumer/frontend plane; the BO uses KV + Control DO + `vars`

6. Infra, CI/CD & tooling

Concern	Tech
Infra as code	Alchemy (`infra/alchemy.run.ts`) — provisions CF backing resources; account hard-pinned
Deploy	GitHub Actions → Wrangler (CI-as-deployer, path-scoped; `wrangler` v4 on Node 22)
Local mesh	Docker Compose (Workers via `wrangler dev`/`workerd`, + Ollama/Infinity/Qdrant)
Monorepo	npm workspaces now → Turborepo `--affected` when the JS apps grow (`CI-2`)
Quality	typecheck + the `/code-review`, `/security-review`, `/simplify`, `/verify` skills; tests per-workspace where present

7. Recurring patterns (apply these, don’t reinvent)

Pattern	What it is	Where
Ports & adapters	Provider-agnostic interface (`ModelPort`/`EmbedderPort`/`VectorIndex`); local vs cloud adapters swap by config	BACK-OFFICE §2–4 (P-12)
Versioned Zod contracts	The typed, immutable interface between agents/stages	`@namaste-ji/shared` (P-13)
Agent Kernel + manifest	One agent shape; new agent = manifest + prompts, not a runtime	AGENT-KERNEL.md (P-19)
Subagent-as-tool + context firewall	Subagent burns context internally, returns distilled artifact + lineage	AK-4 (P-20)
Reflection loop	generate → critique → revise against a rubric, as a Workflow	AP §5
Isomorphic serving/sim	One `rank()` / `coldStartVector()` for both the Feed Lab and production	FEED-LAB.md (P-14)
JSON-payload + indexed-columns D1 rows	Store the contract as JSON, promote a few columns for querying	`@namaste-ji/catalog`
Object-presentation contracts	Classify an object’s shape → apply the matching list/detail/action pattern; server-authoritative collections; URL-state	console/DESIGN-PATTERNS.md
Markdown artifacts (YAML frontmatter)	Agent outputs are readable + diffable; machine fields in frontmatter	AK-7 (P-25)
IaC + CI-as-deployer	Alchemy owns resources; CI deploys only changed targets	CI-1/CI-4 (P-16)

8. Adoption stance

Core (committed): Agents SDK, Workflows, Workers/Pages/Hono, D1/R2/KV/Vectorize/Queues, Vercel AI SDK behind our ports, AI Gateway, Langfuse, Alchemy, Zod, Cloudflare Access + D1 RBAC.
Adopt-when-needed: Better Auth (consumer surface), Statsig (frontend plane), Turborepo (JS monorepo growth), Cloudflare State Store for Alchemy.
Borrowed, not adopted: Mastra’s ideas (evals-first), the funnel machinery of TikTok/IG/YT with an inverted objective (DIST §4).