Docs / readme.md · mirrored from the repo

Namaste Ji — documentation map

The index for every design/ops doc in the repo. Architecture & technical decisions live here; business research, roadmap, and planning live in Notion (hub “Namaste Ji 🌅”). Repo entry points for agents: ../CLAUDE.md → ../AGENTS.md.

Most docs carry a status banner (design/brainstorm vs operational) and a decisions log with stable IDs (D-*, DS-*, CP-*, AK-*, AP-*, OR-*, BO-*, CI-*, FL-*, FE-*, SEC-*, P-*). Cite IDs when referencing a decision.

Start here (the meta layer)

Doc	What it gives you
SYSTEM-DESIGN.md	One consolidated view of how everything fits — the planes, the end-to-end content flow, the spine, the feedback loops
PRINCIPLES.md	The first principles (product · engineering · agent · distribution · security) that recur across every doc
FRAMEWORKS.md	The tech stack + the recurring code patterns (ports/adapters, versioned Zod contracts, the Kernel, isomorphic serving) and why each was chosen
GLOSSARY.md	The domain + system vocabulary in one place
ARCHITECTURE.md	The foundational two-plane design, Control DO, observability, auth (decisions `D1–D8`)

The planes (deep design)

Doc	Owns
CREATIVE-PLANE.md	Agent org, the brief/strategy contract, content lifecycle, eval/Judge, ingest (`CP-*`)
CONTENT-PRODUCTION.md	Execution half: Content Director → Creator (batch), Heimdall QA, publish gate
DISTRIBUTION.md	Catalog → users: feed algorithm, anti-virality, novelty/rarity, edge logistics (`DS-*`)
BACK-OFFICE.md	Control-plane platform: local mesh, ports, RBAC, Secrets Store, environments (`BO-*`)
FRONTEND.md	The consumer app plane: RN+Expo universal (web-first), feed client, auth funnel, i18n, push, UX (`FE-*`) — plan/status: FRONTEND-PLAN.md; app styling: consumer/STYLE-GUIDE.md
EVENTS-AND-ANALYTICS.md	Interaction events & analytics: state/stream/features split, Pipelines→Iceberg lake, feature pipeline, DPDP compliance architecture (`EV-*`)
FEED-SERVING.md	Feed serving & personalization: three-loop architecture, per-user slates + buffering, multi-interest user vectors + negatives, LLM slow brain, phased build (`FS-*`)
NOTIFICATION-SERVICE.md	Push/notification substrate

Agents

Doc	Owns
agents/AGENT-PLATFORM.md	The platform: substrate, ports, manifest schema, memory, reflection (`AP-*`)
agents/AGENT-KERNEL.md	The reusable agent anatomy — one shape every agent instantiates (`AK-*`)
agents/AGENT-KERNEL-RUNTIME.md	The kernel’s runtime implementation notes
agents/ORCHESTRATION.md	Multi-agent topology: subagents-as-tools, online/offline planes (`OR-*`)
agents/CREATIVE-HEAD.md	The first/reference Kernel instance (VP Content)
agents/CALENDAR-SEED-PLAYBOOK.md	Events-calendar seeding playbook

Back-office console (surfaces)

Doc	Owns
console/DESIGN-PATTERNS.md	Reusable object-presentation patterns (classify shape → apply contract)
console/CONTENT-SURFACES.md	Production/staging/Heimdall/DLQ IA + wireframes
console/AGENT-HUB.md	Agent hub surface
console/FEED-LAB.md	The recommendation/feed-algorithm playground (`FL-*`) + mockup

Operations & platform

Doc	Owns
INFRASTRUCTURE.md	Cloudflare substrate: resources, purpose, setup, account pinning
CI-CD.md	Build/deploy strategy: CI-as-deployer, path-scoped, staging/prod (`CI-*`)
RUNNING-LOCALLY.md	Full local runbook (Docker Compose mesh)
LOCAL-LLM.md	Local LLM + AI-Gateway parity path
CLAUDE-CODE-SETUP.md	Configuring Claude Code / agentic dev for this repo
SECURITY-ISO27001.md	Security posture + ISO 27001 readiness (`SEC-*`)

Product & brand

Doc	Owns
BRAND.md · brand/ · brand-tokens.json	Brand system + tokens
ROADMAP.md	Technical roadmap (business roadmap → Notion)
SHOWCASE.md	The public showcase: two-door story site (See it / Build it), the open read-only console, the Guide (founder avatar, playable tour), the starter kit; hosting + PR ladder (`SH-*`)