NataCoach — Canonical Design Brief

This is the governing document for the NataCoach design docs. Every other doc follows the naming canon, decisions, personas, and style rules defined here. If a doc contradicts this brief, the doc is wrong.

1. What we are building (one paragraph)

NataCoach scales Nata — a real personal fitness coach — to many clients through Telegram, without losing the feeling of being personally coached by her. Each client talks to one bot (@NataCoachBot) in their own private chat. The bot runs their training sessions interactively, reads their meal photos and gives coach-grade feedback, syncs their wearable data (Whoop, Garmin), reviews their exercise videos, and remembers everything in a per-user Wiki Brain (a Karpathy-style LLM-maintained wiki). Nata authors the training and food programs, supervises the AI through the Coach Console, and sees analytics across all clients (pilot: 10 users). The prime directive: the user does less — the system proposes, the user confirms.

2. The original request (verbatim intent, for coverage checks)

The owner asked for a system + product design (documentation and visualization only, no implementation) with:

1. Scale Nata's expertise via Telegram; each user has a personal LLM wiki brain (Karpathy method: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
2. Nata as admin sees analytics/statistics across all users (~10 users).
3. Data collection: (a) connect health apps — user gets a link, authorizes e.g. Whoop or Garmin, we ingest data; (b) user uploads food photos → calculate macros → coach-grade feedback on how good the meal was for that person.
4. Nata sets the training program and food program; feedback on meals is relative to that program (what was good/bad, what to replace).
5. Interactive training bot: user starts a training, is told each next exercise per their program, gets instructions, and gives feedback on how easy/hard it was.
6. UX principle: the user does less. E.g. we propose the weights for each set (user can adjust), we propose macros from the photo.
7. Users can upload a training video for form feedback.
8. Owner floated "subfolders / different chats with different people, adding the bot to each" — we are free to contradict and design better.
9. Deliverable: explain how we understood it, visualize heavily (graphs/diagrams), include 1–2 fully visualized example users, and improve on the concept where we can.

3. Naming canon (use these exact names everywhere)

4. Locked product decisions (including corrections to the original concept)

1. One bot, N private chats — no folders, no per-person bot setup. A Telegram bot automatically has a separate private chat with every user who starts it. The "subfolder with different chats" idea is unnecessary: each client DMs @NataCoachBot; Nata's per-client view lives in the Coach Console, not in Telegram folders. Optional later: small "squad" group chats for community.
2. Chat-first, Mini App for rich moments. Everything works in plain chat (photos, buttons, voice). A Telegram Mini App opens for the workout runner, weekly charts, and Nata's Console — no separate app install, still inside Telegram.
3. Proactive, recovery-aware coaching. The bot opens conversations, not the user: Morning Brief from Whoop/Garmin recovery ("rough sleep — we'll cut today's volume 20%, ok?"), pre-workout nudge, instant meal feedback, Weekly Review. The user's job shrinks to: tap ✓, take photos, train.
4. Propose-confirm everywhere. Weights per set are proposed from history + today's recovery (progressive-overload engine); meal macros proposed from the photo; weekly weigh-in proposed from last trend. One tap confirms; editing is the exception, not the task.
5. Coach-in-the-loop with graduated autonomy. Early pilot: LLM drafts meal/training feedback, Nata approves from a queue (target < 30 s per item). Per-message-type autonomy dial: draft → auto-send with audit → fully autonomous. Safety-critical messages (pain, injury, medical) always escalate to Nata. Nata occasionally sends real voice notes — her authentic presence is the moat.
6. Event-sourced truth, distilled memory. Every fact (a set logged, a meal scored, a sleep record) is an immutable event in Postgres (+ raw/ in the user's wiki repo). A nightly distillation job updates the Wiki Brain (wiki/ pages, index.md, log.md per the Karpathy method). Analytics are computed from events (deterministic SQL), never from LLM output.
7. Safety rails. Pain/injury keywords pause programming and escalate; macros are labeled estimates; onboarding captures contraindications; medical-adjacent questions are deflected to professionals. Health data gets strict privacy treatment.

5. Karpathy LLM-wiki method (grounding for the Wiki Brain)

From the gist: an LLM incrementally builds and maintains a persistent wiki — a structured, interlinked collection of markdown files — instead of re-deriving knowledge per query. Three layers: raw/ (immutable originals the LLM reads but never edits), wiki/ (LLM-generated, cross-referenced markdown pages by entity/concept), and a schema doc (governs structure, conventions, workflows). Key files: index.md (catalog of every page with summaries, updated on each ingest) and log.md (append-only chronological record, e.g. ## [2026-08-09] ingest | ...). Workflows: ingest (read source → update pages → fix cross-refs → flag contradictions → log), query (search index → open pages → synthesize with citations; good answers get filed back as pages), lint (periodic health check: contradictions, stale claims, orphan pages, missing links). Governing principle: the human curates sources and asks questions; the LLM's job is everything else. In NataCoach, each user gets one such wiki; "sources" are their events, conversations, and Nata's edits — Nata's direct edits are ground truth.

6. Locked technical decisions

• Stack: TypeScript monorepo. grammY for the Bot API (webhook mode). Next.js Telegram Mini App (workout runner, Weekly Review, Coach Console). PostgreSQL for structured/event data. S3-compatible object storage for media + per-user wiki files (versioned; git-style history). Redis + BullMQ for async pipelines (Meal Lens, Form Check, Health Sync webhooks, nightly distillation).
• LLM: Claude API. Frontier model (Opus-tier, vision) for coach reasoning, Meal Lens, Form Check, distillation; Haiku-tier for routing/classification. All coach output flows through a persona layer built from Nata's tone guide + the user's Wiki Brain.
• Health Sync: Whoop API v2 (OAuth2; recovery, sleep, strain, workouts) and Garmin Health API (OAuth; push webhooks for dailies/sleep/activities) at launch. Apple Health via a bridge (e.g. Health Auto Export) in phase 2. Connect flow = deep link from chat → provider OAuth → webhook ingestion.
• Deploy (pilot, 10 users): single region, one VPS/Fly.io app + managed Postgres. Cost target: LLM spend < $2/user/day at pilot.
• Not building now: custom pose-estimation models (vision LLM + checklists first), barcode scanning, iOS/Android native apps, payments.

7. Personas (use these two everywhere)

Marta, 34 — Kyiv, marketing lead, 8 months postpartum, returning to strength training. 3×/week program (goal: first pull-up, energy). Wears Whoop. Time-poor; hates logging; cooks at home. Risk: overreaching on bad-sleep days (baby). Loves: one-tap flows, encouraging tone.

Denys, 41 — product manager, fat loss 96 kg → 88 kg. 4×/week hybrid (2 strength, 2 zone-2). Wears Garmin Forerunner. Travels ~1 week/month (hotel gyms, restaurants). Risk: travel weeks derail him; skips logging when eating out. Needs: travel adaptations, restaurant meal handling, blunt-but-kind tone.

8. Doc map

9. Style rules for all docs

• GitHub-flavored markdown. H1 title, then a one-line purpose in italics, then content.
• Diagrams: Mermaid in ```mermaid fences. Keep syntax conservative (flowchart TD/LR, sequenceDiagram, erDiagram, journey, gantt, stateDiagram-v2 only). No experimental syntax; quote node labels containing special chars.
• Tables for enumerable facts; prose for reasoning. Realistic sample chat transcripts in fenced blocks. Concrete numbers over vague claims (invent plausible ones and mark assumptions).
• Cross-link sibling docs with relative links, e.g. [Wiki Brain](08-llm-wiki-brain.md).
• Use the naming canon exactly. Personas are only Marta and Denys. English throughout.
• Depth target per doc: 150–400 lines. Complete, not padded.