03 — System Architecture

flowchart TD
 subgraph Clients["Telegram clients"]
 U1["Marta's chat"]
 U2["Denys's chat"]
 NAPP["Nata — Coach Console Mini App"]
 end

 TG["Telegram Bot API"]
 U1 <--> TG
 U2 <--> TG
 NAPP <--> TG

 subgraph App["NataCoach app (Fly.io, single region)"]
 TGS["Self-hosted Bot API server (telegram-bot-api, 2 GB downloads)"]
 GW["Bot Gateway (grammY, webhook mode)"]
 MINI["Next.js Mini App server (Session Mode UI, Weekly Review, Coach Console)"]
 HS["Health Sync webhook receivers (Whoop, Garmin)"]
 ORCH["Orchestrator"]
 subgraph Pipelines["LLM pipelines (BullMQ workers)"]
 ML["Meal Lens"]
 SM["Session Mode engine"]
 FC["Form Check"]
 MB["Morning Brief generator"]
 DIST["Nightly distillation"]
 end
 Q["Redis + BullMQ queues"]
 end

 PG[("PostgreSQL — events, structured data")]
 S3[("S3-compatible storage — media + per-user wiki files")]
 CLAUDE["Claude API (Opus-tier + Haiku-tier)"]
 WHOOP["Whoop API v2"]
 GARMIN["Garmin Health API"]
 NATA["Nata (coach)"]

 TG <--> TGS
 TGS -->|"webhook POST /telegram"| GW
 GW --> ORCH
 MINI --> ORCH
 WHOOP -->|"OAuth + webhooks"| HS
 GARMIN -->|"push webhooks"| HS
 HS --> Q
 ORCH --> Q
 Q --> Pipelines
 Pipelines --> CLAUDE
 Pipelines --> PG
 Pipelines --> S3
 ORCH --> PG
 ORCH --> S3
 GW -->|"sendMessage / sendPhoto"| TGS
 NATA --> NAPP
 NAPP -->|"approvals, program edits, takeover"| ORCH

erDiagram
 users ||--o{ integrations : "connects"
 users ||--o{ metrics : "has daily"
 users ||--o{ programs : "assigned"
 programs ||--o{ program_days : "contains"
 program_days ||--o{ exercises : "prescribes"
 users ||--o{ sessions : "trains"
 program_days ||--o{ sessions : "instantiates"
 sessions ||--o{ sets : "logs"
 exercises ||--o{ sets : "performed as"
 users ||--o{ meals : "photographs"
 meals ||--o{ meal_items : "decomposes into"
 users ||--o{ events : "emits"
 users ||--o{ wiki_pages : "owns"
 users ||--o{ approvals : "generates"
 users ||--o{ alerts : "triggers"

 users {
 uuid id PK
 bigint tg_user_id UK
 text display_name
 text timezone
 text goals
 text contraindications
 text status
 timestamptz created_at
 }
 integrations {
 uuid id PK
 uuid user_id FK
 text provider
 bytea access_token_enc
 bytea refresh_token_enc
 text scopes
 text status
 timestamptz connected_at
 }
 metrics {
 uuid id PK
 uuid user_id FK
 date day
 text source
 text kind
 numeric value_num
 jsonb value_json
 text dedupe_key UK
 timestamptz ingested_at
 }
 programs {
 uuid id PK
 uuid user_id FK
 text program_type
 int version
 text status
 date starts_on
 text coach_notes
 }
 program_days {
 uuid id PK
 uuid program_id FK
 int day_index
 text focus
 jsonb targets_json
 }
 exercises {
 uuid id PK
 uuid program_day_id FK
 int slot
 text name
 int sets_planned
 text rep_range
 int rest_sec
 text cues
 text substitution_group
 }
 sessions {
 uuid id PK
 uuid user_id FK
 uuid program_day_id FK
 timestamptz started_at
 timestamptz completed_at
 text state
 numeric readiness_score
 numeric volume_kg
 numeric rpe_avg
 }
 sets {
 uuid id PK
 uuid session_id FK
 uuid exercise_id FK
 int set_index
 numeric proposed_weight_kg
 numeric actual_weight_kg
 int reps
 numeric rpe
 text flag
 }
 meals {
 uuid id PK
 uuid user_id FK
 timestamptz eaten_at
 text photo_s3_key
 text status
 int kcal_est
 int protein_g
 int carbs_g
 int fat_g
 text confidence
 text score
 }
 meal_items {
 uuid id PK
 uuid meal_id FK
 text name
 int portion_est_g
 int kcal
 int protein_g
 int carbs_g
 int fat_g
 }
 events {
 bigint seq PK
 uuid user_id FK
 timestamptz ts
 text event_type
 jsonb payload
 text source
 text dedupe_key UK
 }
 wiki_pages {
 uuid id PK
 uuid user_id FK
 text path
 text title
 text s3_key
 int version
 text updated_by
 text summary
 timestamptz updated_at
 }
 approvals {
 uuid id PK
 uuid user_id FK
 text draft_type
 text draft_content
 text status
 text decided_by
 int latency_s
 timestamptz created_at
 timestamptz decided_at
 }
 alerts {
 uuid id PK
 uuid user_id FK
 text severity
 text kind
 text message
 text status
 timestamptz created_at
 timestamptz ack_at
 }

sequenceDiagram
 participant M as Marta (Telegram)
 participant T as Telegram Bot API
 participant G as Bot Gateway (grammY)
 participant Q as BullMQ meal-lens
 participant W as Meal Lens worker
 participant P as Postgres
 participant S as S3
 participant C as Claude API
 participant N as Nata (Coach Console)

 M->>T: sends lunch photo (13:42)
 T->>G: webhook POST (update_id 8812031)
 G->>G: verify secret token, dedupe update_id
 G->>S: store photo media/marta/2026-08-09/meal-1342.jpg
 G->>Q: enqueue meal-lens job
 G->>T: "Looking at your lunch... " (ack < 1 s)
 Q->>W: job picked up
 W->>P: load active food program + today's meal totals
 W->>S: load wiki excerpt (nutrition-patterns.md, coaching-playbook.md)
 W->>C: Opus-tier vision call (photo + context)
 C-->>W: items + macros JSON + feedback draft
 W->>P: insert meal (status proposed), meal_items, event meal.analyzed
 W->>W: deterministic compare vs day targets (protein gap 48 g)
 W->>P: autonomy dial says draft mode - insert approval (pending)
 P-->>N: approval appears in queue (push)
 N->>P: approve with 1-word edit (14 s)
 P->>Q: enqueue outbox send
 Q->>G: deliver approved feedback
 G->>T: message + buttons "✓ Looks right" / "Adjust"
 T->>M: coach feedback with proposed macros
 M->>T: taps "✓ Looks right"
 T->>G: callback query
 G->>P: meal status confirmed, event meal.scored

sequenceDiagram
 participant GA as Garmin push service
 participant H as Health Sync receiver
 participant Q as BullMQ health-sync
 participant W as Normalizer worker
 participant P as Postgres
 participant B as Morning Brief generator
 participant C as Claude API
 participant G as Bot Gateway
 participant D as Denys (Telegram)

 GA->>H: POST /webhooks/garmin (sleep summary, 05:58)
 H->>H: verify signature, check dedupe_key
 H->>Q: enqueue normalize job (raw payload attached)
 H-->>GA: 200 OK (< 300 ms)
 Q->>W: job picked up
 W->>P: upsert metrics (sleep_minutes 348, hrv_ms 41, rhr_bpm 56)
 W->>P: append event sleep.recorded (dedupe_key garmin:sleep:2026-08-09:denys)
 W->>W: rule check - sleep 5h48m below 6h30m threshold
 W->>Q: promote briefs job for Denys (flag low_recovery)
 Q->>B: 06:30 local - build Morning Brief
 B->>P: load metrics, today program_day (Zone 2 40 min), wiki flags
 B->>C: Opus-tier persona call (propose cut to 30 min easy)
 C-->>B: brief draft
 B->>P: autonomy dial - auto-send with audit (log approval auto_sent)
 B->>G: send brief 30-45 min after detected wake (fallback 07:15)
 G->>D: "Short night (5h48) - let's cut Zone 2 to 30 min today. OK?" ✓ / keep 40
 D->>G: taps ✓
 G->>P: event brief.confirmed, session plan adjusted

sequenceDiagram
 participant CR as BullMQ cron (02:30 per user)
 participant W as Distillation worker
 participant P as Postgres
 participant S as S3 wiki bucket
 participant C as Claude API (Batches)
 participant N as Nata (alerts)

 CR->>W: distill job (user marta, watermark seq 48211)
 W->>P: fetch events where seq > 48211 (37 events today)
 W->>S: write raw/2026-08-09-events.md (immutable)
 W->>S: read index.md + affected pages (training-history.md, recovery-patterns.md, nutrition-patterns.md)
 W->>C: Opus-tier ingest call - update pages, fix cross-refs, flag contradictions
 C-->>W: revised page bodies + index summaries + contradiction list
 W->>W: validate - no raw/ edits, page size caps, links resolve
 W->>S: write new page versions (bucket versioning keeps history)
 W->>P: bump wiki_pages versions, updated_by distiller
 W->>S: append log.md entry "[2026-08-09] ingest - 37 events, 3 pages updated"
 W->>S: update index.md
 W->>P: advance watermark to seq 48248, event wiki.distilled
 alt contradiction found
 W->>P: insert alert (kind wiki_contradiction, severity low)
 P-->>N: shows in Console next morning
 end
 alt LLM or validation failure after 3 retries
 W->>W: move job to dead-letter queue
 W->>P: alert (kind pipeline_failure) - wiki untouched, last good version stands
 end