architecture-and-stack

name	architecture-and-stack
description	Cloudflare-first platform selection. Decision trees for Workers, D1, R2, KV, DO, Queues, Vectorize, Containers, Sandboxes, Flagship, Agent Memory, Workflows v2. Default stack, override conditions, auth, data patterns, reliability.
metadata	{"version":"2.0.0","updated":"2026-04-23"}
license	Rutgers
compatibility	{"claude-code":">=2.0.0","agentskills":">=1.0.0"}
submodules	["api-design-and-documentation.md","shared-api-pool.md","drizzle-orm-and-migrations.md","coolify-docker-proxmox.md","mcp-and-cloud-integrations.md","ai-technology-integration.md","auth-and-session-management.md","background-jobs-and-workflows.md","openapi-generation.md","cf-auto-provision.md","enterprise-multi-tenancy.md","heartbeat-polling.md"]

Submodules

File	Description
api-design-and-documentation.md	Hono v4.12.x RPC mode, error envelope, rate limiting, pagination, OpenAPI, versioning.
shared-api-pool.md	Centralized API key pool. Auto-integrates PostHog, Sentry, Postiz, all services.
drizzle-orm-and-migrations.md	Drizzle ORM v1.0 for D1/Neon. RQBv2, schema-first, auto migrations, type-safe queries.
coolify-docker-proxmox.md	Self-hosted services on Proxmox via Coolify API. Docker containers, env vars.
mcp-and-cloud-integrations.md	All MCP servers, cloud APIs, SaaS integrations. Secret discovery, AI API usage.
ai-technology-integration.md	AI APIs/models: GPT-4o vision, Workers AI edge inference, embeddings for RAG.
auth-and-session-management.md	Clerk auth: middleware, webhook sync, RBAC, protected routes, session tokens.
background-jobs-and-workflows.md	Inngest durable jobs, CF Workflows v2, CF Cron Triggers, CF Queues, email drips, fan-out.
openapi-generation.md	@hono/zod-openapi auto-generated specs, Swagger UI, client SDK codegen, versioning.
cf-auto-provision.md	Single-function CF project bootstrap: D1+KV+R2+DNS+routes+wrangler.toml+integrations via cf CLI.
enterprise-multi-tenancy.md	DB-per-tenant D1, RBAC/ABAC, audit logging (R2 WORM), SSO/SCIM, data residency, rate limiting, white-labeling.
heartbeat-polling.md	CF Workflows heartbeat polling for long-running container jobs — avoids 25min step timeout.

05 — Architecture and Stack

Default Stack

Need	Default	Override When
Hosting	CF Workers + Static Assets	Never
Backend	Hono v4.12.x on Workers	Complex GraphQL → Yoga
Frontend (simple)	Vanilla HTML/CSS/JS	>3 interactive pages
Frontend (complex)	Angular 21 + Ionic + PrimeNG + Nx	Simple marketing site
DB (simple)	D1 (SQLite, global read replication)	Joins >3 tables
DB (complex)	Neon PostgreSQL	D1 sufficient
Cache	KV / Upstash Redis	Atomic ops → D1
Storage	R2	S3-specific SDK
Auth (SaaS)	Clerk	Custom auth requested
Auth (self-hosted)	Authentik	Clerk for customer-facing
Payments	Stripe + Stripe Link	Non-card/crypto
Email (transactional)	Resend / CF Email Service	Bulk → Listmonk
Email (marketing)	Listmonk on Coolify	Simple → Resend
Runtime	Bun	Node.js for incompatible
Package Manager	pnpm	Legacy npm
Linting (TS)	ESLint + Prettier	Never Biome
Linting (Python)	Ruff + mypy	Never black+isort separately
Testing	Playwright v1.59+ + Vitest	Never Jest/Cypress
Analytics	GA4 via GTM + PostHog	Privacy-first → PostHog only
Errors	Sentry	PostHog errors sufficient
Validation	Zod	—
Search	AI Search (fka AutoRAG) + Vectorize	Simple → D1 LIKE
Queues	CF Queues	—
Realtime	Durable Objects + WebSocket (32MiB msg)	Simple polling
Scheduling	CF Cron Triggers (250 paid)	—
AI/ML	Workers AI (Unweight 22% compression)	Specific model → OpenAI/Anthropic via AI Gateway
Workflows	Inngest / CF Workflows v2	Simple cron → Cron Triggers
AI Agents	CF Agents SDK (Project Think on DO)	No agent needed
Agent Memory	CF Agent Memory (managed)	Custom → DO+SQLite
Sandboxes	CF Sandboxes (GA)	Simple → Dynamic Workers
Containers	CF Containers (GA)	Simple → Workers
Feature Flags	Flagship (sub-ms eval)	PostHog flags sufficient
IaC	cf CLI (3000 ops) + wrangler.jsonc	Multi-cloud → Pulumi
CI/CD	Workers Builds / GitHub Actions	Complex → GH Actions

Key reasoning: Hono over NestJS (native CF Workers, 12KB). Angular over React (Brian's background, signals stable). Neon over Supabase (multi-DB, lower cost). Drizzle over Prisma (5KB vs 40KB, edge-native, passed Prisma in downloads). ESLint over Biome (angular-eslint, typescript-eslint, massive plugin library).

CF-Only Assumption (DEFAULT)

Every feature MUST try CF-native first. Never reach for external services when CF has an equivalent. Template: megabytespace/saas-starter has stubs for all CF primitives. AI→Workers AI (not OpenAI). Cache→KV/Cache API (not Redis). DB→D1 (not Postgres). Storage→R2 (not S3). Queue→CF Queues (not SQS). Realtime→DO+WebSocket (not Pusher). Schedule→Cron Triggers (not external cron). Search→AI Search+Vectorize (not Algolia). Email→CF Email Service (not SES). Feature flags→Flagship (not LaunchDarkly). Sandbox→CF Sandboxes (not Docker). Only escape to external when CF primitive insufficient (complex joins→Neon, specific model→OpenAI/Anthropic via AI Gateway).

CF Platform Decision Trees

Run code: Static→Workers Static Assets. API→Workers(Hono). Long-running→Workers+Queues/Workflows v2. Stateful→DO. Container workload→CF Containers(GA). Scheduled→Cron Triggers. Browser→Browser Run(Live View+HitL). Sandboxed exec→Dynamic Workers(100x faster than containers). Full isolation→CF Sandboxes(GA, persistent shell+fs).

Store data: Config→KV. Relational simple→D1(global read replication, 1TB). Relational complex→Neon. Files→R2. Session→DO/KV. Search→AI Search(hybrid retrieval). Vectors→Vectorize. Messages→Queues. Cache→KV(CACHE binding, TTL). Versioned objects→Artifacts(git-compatible). Agent state→Agent Memory(managed).

Security: Bots→Turnstile. DDoS→always-on free. WAF→CF WAF. Auth→Clerk. Agent auth→Managed OAuth(RFC 9728). Rate limit→KV counters. Secrets→wrangler secret put. Admin→CF Access. Private networking→CF Mesh.

Feature management: Flags→Flagship(sub-ms eval). Rollout→percentage+cohort+property. Kill switch→instant disable.

Architecture Patterns

Marketing Site: Worker(Hono) → Static Assets + R2 images + KV config + GA4+GTM + Turnstile + Resend

SaaS App: Workers Static Assets(Angular 21+Ionic) → Workers API(Hono) → D1(global replicas)/Neon + R2 + KV + Queues + DO + Clerk + Stripe + Resend + Listmonk + Flagship + PostHog+Sentry+GA4 + Playwright+Vitest

API Service: Worker(Hono) → D1/Neon + KV(rate limit/cache) + R2 + Queues + Workers AI + Sentry + PostHog

AI Agent Service: Worker(Hono) → Agents SDK(Project Think) + Agent Memory + Dynamic Workers + Browser Run + AI Search + DO(stateful sessions)

Service Boundaries

Start monolith. Split when: different scaling needs, different deploy cadence, Worker size exceeded (10MB compressed paid), isolation required. Angular frontend = separate Worker. Webhook handlers = separate. Cron = shared via scheduled handler. Service bindings for zero-cost Worker-to-Worker RPC.

Auth: Clerk

User → Clerk widget → JWT → Worker middleware verifies → proceed. Metadata in D1 (Clerk ID as FK). Roles in D1, not Clerk metadata. Not needed for: public marketing, OSS docs, public APIs with rate limiting only.

Data: Drizzle ORM v1.0

Schema in TypeScript, type-safe queries, auto migrations. RQBv2 (363 commits, 9K+ tests). 10x faster introspection. D1 conventions: id=TEXT(ULID), created_at/updated_at=TEXT(ISO8601), deleted_at=TEXT(soft delete), explicit FKs, indexes on FKs+frequent columns. D1 batch API for transactions (no BEGIN support).

Neon when D1 isn't enough: >3 table joins, full-text search, jsonb, complex aggregations, RLS, >1TB. D1 global read replication eliminates most Neon arguments for read-heavy apps.

API Keys

All keys: project .env.local or get-secret KEY (chezmoi+age encrypted) GCP: ~/.config/emdash/gcp-service-account.json CF: get-secret CLOUDFLARE_EMAIL / get-secret CLOUDFLARE_API_TOKEN / get-secret CLOUDFLARE_ACCOUNT_ID

| Service | Env Var | Free Tier | |---------|---------|-----------|| | Cloudflare | CLOUDFLARE_API_TOKEN | Yes | | Stripe | STRIPE_API_KEY | Test free | | Resend | RESEND_API_KEY | 100/day | | PostHog | POSTHOG_API_KEY | 1M events/mo | | Sentry | SENTRY_AUTH_TOKEN | 5K errors/mo | | OpenAI | OPENAI_API_KEY | Pay-per-use | | Anthropic | ANTHROPIC_API_KEY | Pay-per-use | | Ideogram | IDEOGRAM_API_KEY | Pay-per-use | | Unsplash | UNSPLASH_ACCESS_KEY | 50 req/hr | | Pexels | PEXELS_API_KEY | 200 req/hr | | GA4 | GCP service account | Free | | Clerk | CLERK_SECRET_KEY | 10K MAU |

Reliability

Error handler: app.onError() → log + Sentry + JSON envelope. Retry: idempotent 3x exponential backoff, non-idempotent no retry. Health: GET /health (version+timestamp), /health/db, /health/services. D1 Time Travel: 30-day PIT recovery (paid), 7-day (free). D1→R2 daily backup workflow for 90+ day retention.

CF Infrastructure

Zone (megabyte.space): get-secret CLOUDFLARE_ZONE_ID. Deploy+purge always together (see CONVENTIONS.md).

Product	Free Limit	Paid Limit
Workers	100K req/day, 10ms CPU	Unlimited, 5min CPU
Static Assets	20K files/version	100K files/version
D1	5M rows read, 5GB	25B rows, 1TB
R2	10GB, 10M req/mo	Zero egress
KV	100K reads/day	10M reads/day
Queues	1M msg/mo	Pay-per-use
DO	100K req/day	Pay-per-use
Vectorize	5M vectors	Pay-per-use
Workers AI	10K neurons/day	Pay-per-use
WebSocket msg	32 MiB	32 MiB
Worker size	3MB compressed	10MB compressed
Cron Triggers	5	250
Containers	—	GA (DO-based)

Security headers, Turnstile, rate limiting, DNS management, wrangler.jsonc template — see CONVENTIONS.md.

AI Agent Patterns (CF Agents SDK + Project Think, April 2026)

Think class on DO: addressable entity with SQLite, zero compute when hibernated. Durable execution via Fibers (survives crashes). Dynamic Workers for sandboxed V8 isolates (100x faster, 100x more memory-efficient than containers). Execution ladder: Workspace → Dynamic Worker → npm resolution → headless browser → CF Sandbox(GA). Sub-agent coordination via Facets (colocated, typed RPC).

Agent Memory: managed persistent memory service — recall what matters, forget what doesn't. Browser Run: enhanced browser rendering with Live View, Human-in-the-Loop, CDP access, 4x concurrency. CF Email Service (public beta): native send/receive/process from agents. Managed OAuth: RFC 9728 agent authentication. CF Mesh: secure private networking for agents+Workers with scoped DB/API access. AI Search: dynamic instances with hybrid retrieval + relevance boosting (fka AutoRAG).

Code Mode MCP: 2 tools + <1K tokens (81% reduction vs traditional MCP). cf CLI: unified CLI covering ~3000 API operations.

Traffic reality: agentic actors = ~10% CF network (up 60% YoY). Design every API for human+agent consumers.