# Health Debug — Master Plan & Execution Sequence

> **Document:** `docs/plan/00-MASTER-PLAN.md` (umbrella document, index `00`)
> **Project:** Health Debug — healthdebug.com
> **Status:** PLANNING ONLY — no implementation has started. See [Current Status](#current-status).
> **Last updated:** 2026-09-01

## Purpose

This is the umbrella planning document for the Health Debug platform: a greenfield, from-scratch build. It recaps the product vision, ecosystem, and business model; defines the six-phase execution sequence with per-phase goals, deliverables, dependencies, and exit criteria; indexes the sibling planning documents (01–12); records the current project status; and maintains a short risk register. Every sibling document is subordinate to this plan and to the two non-negotiable Core Opinions summarized below and detailed in `01-core-opinions-and-constraints.md`.

An older togo-based codebase exists at `github.com/fadymondy/health-debug`. It is **strictly reference only** — no code is carried forward; this build starts from zero.

---

## 1. Vision, Ecosystem & Business Model

### 1.1 Vision

Health Debug is a proactive health, self-care, and IoT-driven platform aimed at combating chronic lifestyle diseases: **Diabetes, Gout, Hypertension, Heart disease, and Kidney disease**. The primary audience is desk-bound professionals — programmers, engineers, and similar knowledge workers whose sedentary routines put them at elevated risk.

The platform fuses:

- **Behavioral tracking** (hydration, caffeine timing, pre-sleep eating, medication adherence, cycles, desk-time movement),
- **IoT sensor input** (wearables and health platforms via Apple HealthKit and Google Health Connect),
- **Biometric analysis**, and
- **Smart alerts** delivered across every device the user owns.

### 1.2 Ecosystem

Health Debug is an ecosystem, not a single app. It bridges four parties:

| Party | Role in the ecosystem |
|---|---|
| **Patients / end-users** | Track behavior, receive protocol enforcement and smart alerts. Free forever. |
| **Doctors** | (Future state) View patient data; prescribe "Medical Restrictions" that dynamically alter the user's Protocol Engines. |
| **B2B corporate health insurance** | (Future state) Corporate wellness / insurance integrations via dashboards and APIs. |
| **Wellness marketplaces** | (Future state) Marketplace APIs for partners: pharmacies, insurance, wellness clinics. |

### 1.3 Business model

- **Free for end-users** — the consumer product has no paywall.
- Revenue derives from the ecosystem side: doctor dashboards, B2B corporate health insurance, and wellness-marketplace partnerships (all future state — see `10-security-integrations-b2b.md`).

### 1.4 The Two Core Opinions (non-negotiable)

These are product-defining constraints. Breaking either one breaks the app. Full treatment in `01-core-opinions-and-constraints.md`.

1. **The Protocol is Categorical, Not Quantitative.** The system evaluates inputs by **what they are**, not **how much**. Food is strictly `Safe` or `Trigger-bearing`. There is no complex quantitative AI deduction logic for food — no calorie math, no dosage inference, no "a little bit is fine" reasoning.
2. **The App NEVER Invents Medical Certainty.** The AI is strictly prohibited from diagnosing, prescribing, or guessing drug categories. Its sole job is **behavioral pattern analysis**. Every final AI output must defer to: **"Consult your doctor."**

### 1.5 Architectural doctrine (summary)

- **Backend is the Single Source of Truth (SSOT).** All temporal logic and state logic (timers, windows, cooldowns, grace periods, predictions) lives in the ToGO REST API. Clients **never** compute or hardcode protocol business logic locally — they are presentation and sensor-collection layers only.
- **Each Protocol Engine is a ToGO plugin.** Every one of the 8 engines is packaged as its own plugin on the ToGO Microkernel's plugin registry — independently registrable, manageable, and testable, with the engine's protocol constants confined to its plugin (decided 2026-09-01; detail in `04-backend-togo.md`).
- **Native clients only, no hybrid.** Web = React + TanStack; Apple = native Swift; Google = native Kotlin; Desktop = Electron (Windows, Linux); plus a Chrome Extension (Manifest V3).
- **MCP is a first-class surface.** The platform fully supports the Model Context Protocol: a Health Debug MCP server (doubling as a terminal CLI) lets AI assistants and the terminal log protocol events and query engine state against the same ToGO API, under the same thin-client rules — no protocol logic, no AI keys (see `11-mcp-integration.md`).
- **Database discipline:** PostgreSQL (ToGO postgres image); **every column NOT NULL with a defined default**; migrations follow the **expand-contract** pattern strictly (sqlc + Atlas).
- **AI is BYOK and server-proxied.** User-provided keys (OpenAI, Anthropic, Google, Apple Intelligence) are encrypted in the backend; all AI calls are proxied server-side; **no API key ever reaches a client**.
- **i18n:** full RTL support for Arabic (including mirrored progress bars and layout), no string concatenation, ICU Message Format.

### 1.6 The 8 Protocol Engines (summary)

Backend state machines — full specifications, state diagrams, and schema sketches in `03-protocol-engines.md`:

| # | Engine | One-line rule |
|---|---|---|
| 1 | **Hydration Engine** | Water logged in 250ml units, max 5000ml/day, 30-second cooldown between entries. |
| 2 | **Caffeine Block** | No caffeine in the first 90 minutes post-wakeup. |
| 3 | **GERD Window** | 4-hour pre-sleep window allowing ONLY water, chamomile, anise. |
| 4 | **Trigger Families** | Food categorized into Gout, IBS-GERD, and Fatty Liver trigger families (categorical, per Core Opinion 1). |
| 5 | **Medication Grace** | 60-minute flexible window to log medications. |
| 6 | **Cycle Engine (Fertility)** | Requires 3 consecutive logged cycles before predicting; fails safe on irregularity. |
| 7 | **Contraceptive Security** | Differentiates daily pills, monthly injections, implants. |
| 8 | **Kinetic Pomodoro Engine** | Desk timer whose break only registers if wearables detect physical movement away from the screen. |

### 1.7 Visual identity (strict color spec)

Full design-system treatment is **PENDING DESIGN** (being finalized separately in Figma / Claude design), but the color spec itself is fixed:

| Mode | Background | Accent 1 | Accent 2 | Alert | Style |
|---|---|---|---|---|---|
| **Dark** | `#1A1A1A` charcoal | `#00FF33` neon green glow (active timers) | `#00CCFF` cyan (active buttons) | `#FF3333` red | Glowing effects |
| **Light** | `#FFFFFF` | `#20A060` saturated teal | `#0070A0` deep cyan blue | — (light-mode alert color: **PENDING DESIGN**, not yet specified) | Flat colors |

---

## 2. Execution Sequence — The Six Phases

The build proceeds strictly in this order. Each phase depends on the previous ones because the backend is the SSOT: no client can be built before the API it renders.

```mermaid
flowchart LR
    P1["Phase 1\nToGO Backend\n+ PostgreSQL + Auth"] --> P2["Phase 2\nReact Web Dashboard\n+ Theme/i18n Engine"]
    P2 --> P3["Phase 3\nChrome Extension"]
    P3 --> P4["Phase 4\nNative Apple Suite"]
    P4 --> P5["Phase 5\nNative Android Suite"]
    P5 --> P6["Phase 6\nElectron Desktop"]
```

> **Note on sequencing:** the phase order (3 → 4 → 5 → 6) is the specified execution sequence. Whether later client phases may overlap in practice is **undefined in the spec** — this plan treats them as strictly sequential until decided otherwise.
>
> **Phase 1.5 — MCP server & CLI:** immediately after the Phase 1 API exposes the hydration/today endpoints, the MCP server + terminal CLI ships as the thinnest possible client and doubles as an API smoke-test harness. See `11-mcp-integration.md`.

### Phase 1 — ToGO Backend + PostgreSQL + Auth

*Detailed plan: `04-backend-togo.md`, `03-protocol-engines.md`, `10-security-integrations-b2b.md`*

- **Goal:** Stand up the Single Source of Truth: the API-first Go backend on the ToGO Framework, with identity, database discipline, and the Protocol Engines as backend state machines.
- **Key deliverables:**
  - ToGO project scaffolding using the ToGO Microkernel (config, hooks, plugin registry).
  - TOGO auth for identity.
  - PostgreSQL via the ToGO postgres image; sqlc + Atlas toolchain wired up.
  - Schema foundations honoring the strict rules: every column NOT NULL with a defined default; expand-contract migrations only.
  - The 8 Protocol Engines implemented server-side as state machines, **each packaged as its own ToGO plugin** on the Microkernel plugin registry, starting with the **Hydration Engine** (first resume target — see [Current Status](#current-status)).
  - BYOK AI key storage (encrypted in backend) and the server-side AI proxy layer, honoring Core Opinion 2.
  - REST API surface for clients (endpoint catalog planned in `04-backend-togo.md`).
- **Dependencies:** None (first phase). UI design finalization is **not** a blocker for backend work, except where API response shapes are driven by screen needs — those spots are flagged **PENDING DESIGN** in the sibling docs.
- **Exit criteria:**
  - All 8 engines pass server-side state-machine tests (cooldowns, windows, grace periods, fail-safe behaviors).
  - Schema audit: zero nullable columns, zero columns without defaults; all migrations expand-contract compliant.
  - Auth flows working end-to-end against the API.
  - No protocol/temporal logic exists anywhere except the backend.

### Phase 2 — React Web Dashboard + Theme/i18n Engine

*Detailed plan: `05-web-dashboard.md`*

- **Goal:** First client: the web dashboard (React + TanStack) as a pure presentation layer over the Phase 1 API, plus the theme engine (dark/light per the strict color spec) and the i18n engine (ICU Message Format, full Arabic RTL).
- **Key deliverables:**
  - React + TanStack app skeleton consuming the ToGO REST API.
  - Theme engine implementing the strict color spec: dark mode (`#1A1A1A` / `#00FF33` glow / `#00CCFF` / `#FF3333`, glowing effects) and light mode (`#FFFFFF` / `#20A060` / `#0070A0`, flat colors).
  - i18n engine: ICU Message Format, no string concatenation, full RTL for Arabic including mirrored progress bars and layout mirroring.
  - Dashboard screens for the Protocol Engines — screen inventory and layouts are **PENDING DESIGN**.
- **Dependencies:** Phase 1 API. Screen implementation blocked on finalized Figma / Claude design output (**PENDING DESIGN**); the skeleton + theme/i18n engines are not blocked.
- **Exit criteria:**
  - Zero protocol business logic in client code (thin-client audit).
  - Both themes render per spec; RTL Arabic passes a full mirroring review (including progress bars).
  - All strings externalized in ICU Message Format; no concatenated strings.

### Phase 3 — Chrome Extension (Manifest V3)

*Detailed plan: `06-chrome-extension.md`*

- **Goal:** Bring protocol presence into the browser — the primary habitat of the desk-bound target audience.
- **Key deliverables:** Manifest V3 extension talking to the ToGO REST API; feature scope (which engines surface in the extension, e.g. desk-timer visibility) is **PENDING DESIGN** and detailed in `06-chrome-extension.md`.
- **Dependencies:** Phase 1 API; Phase 2 theme/i18n conventions (reused as patterns, not shared hybrid code).
- **Exit criteria:** Extension is presentation-only (thin-client audit); MV3-compliant; no API keys or protocol logic client-side.

### Phase 4 — Native Apple Suite (Swift)

*Detailed plan: `07-apple-suite.md`*

- **Goal:** Native Swift apps across the Apple ecosystem: **macOS, iOS, watchOS, CarPlay, Widgets**.
- **Key deliverables:**
  - Native Swift clients for each Apple surface.
  - **Apple HealthKit** integration: clients read sensor/biometric data on-device and push securely to ToGO (this unlocks wearable-verified breaks for the Kinetic Pomodoro Engine on Apple hardware).
  - Apple Intelligence as a BYOK AI provider option (still proxied server-side per the BYOK rule).
- **Dependencies:** Phase 1 API; finalized design (**PENDING DESIGN**) for all Apple surfaces.
- **Exit criteria:** HealthKit data flows on-device → ToGO securely; all surfaces are thin clients; watchOS movement data verifiably drives Kinetic Pomodoro break registration server-side.

### Phase 5 — Native Android Suite (Kotlin)

*Detailed plan: `08-android-suite.md`*

- **Goal:** Native Kotlin apps across the Google ecosystem: **Android, WearOS, Android Auto, ChromeOS**.
- **Key deliverables:**
  - Native Kotlin clients for each Google surface.
  - **Google Health Connect** integration: on-device reads pushed securely to ToGO (Kinetic Pomodoro wearable verification on WearOS).
- **Dependencies:** Phase 1 API; finalized design (**PENDING DESIGN**) for all Android surfaces.
- **Exit criteria:** Health Connect data flows on-device → ToGO securely; all surfaces are thin clients; WearOS movement data drives Kinetic Pomodoro break registration server-side.

### Phase 6 — Electron Desktop (Windows, Linux)

*Detailed plan: `09-desktop-electron.md`*

- **Goal:** Desktop presence for Windows and Linux via Electron (macOS desktop is covered natively in Phase 4).
- **Key deliverables:** Electron app consuming the ToGO REST API; desktop-specific surface scope is **PENDING DESIGN**.
- **Dependencies:** Phase 1 API; Phase 2 web patterns; finalized design (**PENDING DESIGN**).
- **Exit criteria:** Thin-client audit passes; theme/i18n parity with the web dashboard (including RTL).

### Out of sequence (future state — explicitly NOT in Phases 1–6)

Recorded for context in `10-security-integrations-b2b.md`; not scheduled:

- **Doctor & B2B dashboards** — doctors view patient data and prescribe "Medical Restrictions" (blocking certain foods, enforcing fasting, requiring tracked workouts) that dynamically alter the user's Protocol Engines.
- **Gamification** — badges for protocol compliance (e.g., a perfect GERD window).
- **Marketplace APIs** — for B2B partners: pharmacies, insurance, wellness clinics.

Phase 1 schema and engine designs should avoid decisions that would *preclude* these (e.g., engines should be parameterizable enough that a future "Medical Restriction" can alter them), but no future-state feature is built now. See the [Risk Register](#4-risk-register) on scope creep.

---

## 3. Document Index

All planning documents live in `docs/plan/`. This file (`00`) is the umbrella; read it first.

| # | File | Scope |
|---|---|---|
| 00 | `00-MASTER-PLAN.md` | This document — vision recap, phase sequence, index, status, risks. |
| 01 | `01-core-opinions-and-constraints.md` | The two non-negotiable Core Opinions; architectural doctrine (SSOT thin clients, NOT NULL + default schema rule, expand-contract migrations); the strict color spec; i18n/RTL rules. |
| 02 | `02-platform-divergences.md` | The five known legacy iOS/Android divergences, their legacy-era fixes, and how Phases 4–5 close them by design in the greenfield architecture. |
| 03 | `03-protocol-engines.md` | Full specs for the 8 backend Protocol Engines: states, transitions, timers, fail-safe behavior, schema sketches. |
| 04 | `04-backend-togo.md` | Phase 1 detail: ToGO Framework / Microkernel scaffolding, TOGO auth, PostgreSQL + sqlc + Atlas, REST API surface, BYOK AI proxy. |
| 05 | `05-web-dashboard.md` | Phase 2 detail: React + TanStack dashboard, theme engine, i18n/RTL engine. |
| 06 | `06-chrome-extension.md` | Phase 3 detail: Manifest V3 extension. |
| 07 | `07-apple-suite.md` | Phase 4 detail: Swift apps (macOS, iOS, watchOS, CarPlay, Widgets), HealthKit. |
| 08 | `08-android-suite.md` | Phase 5 detail: Kotlin apps (Android, WearOS, Android Auto, ChromeOS), Health Connect. |
| 09 | `09-desktop-electron.md` | Phase 6 detail: Electron for Windows and Linux. |
| 10 | `10-security-integrations-b2b.md` | BYOK key security and AI proxying, HealthKit/Health Connect data flow security, and the future-state doctor/B2B/marketplace ecosystem. |
| 11 | `11-mcp-integration.md` | Phase 1.5: the Health Debug MCP server + terminal CLI — tool catalog for logging/querying from AI assistants, auth, Core Opinion guardrails. |
| 12 | `12-legacy-reference-map.md` | Map of the legacy codebase kept at `E:\Sites\healthdebug` (reference only): where the old engines, API, schema, and clients live, plus extracted keys/config inventory. |
| 13 | `13-execution-modules-and-sessions.md` | How the build is worked session by session: the (module × surface) grid, session sizing, dependency order, done-criteria templates, and the **brain handoff protocol**. Per-module session cards in `sessions/`. |

---

## Current Status

**The project is PAUSED, pending UI design finalization.** The visual/UI design is being produced separately (in Figma / Claude design). No implementation work — backend or client — has started; this repository currently contains planning documents only.

**When work resumes, it resumes at Phase 1 with this first slice:**

1. **ToGO backend scaffolding** — ToGO Framework project + Microkernel (config, hooks, plugin registry), TOGO auth, PostgreSQL via the ToGO postgres image, sqlc + Atlas wired up.
2. **Hydration Engine schema** — the first Protocol Engine schema (250ml units, 5000ml daily max, 30-second entry cooldown), honoring the NOT-NULL-with-default rule and expand-contract migrations from the very first migration.
3. **React dashboard skeleton with theming/i18n** — the Phase 2 app shell brought up early alongside the backend: theme engine per the strict color spec and the i18n/RTL engine, with actual screens deferred until design is final (**PENDING DESIGN**).

Everything that depends on the finalized design is flagged **PENDING DESIGN** inline throughout this document set and must not be started before the Claude Design work lands.

**Design delivery is per-screen and gates client UI (added 2026-09-01).** The design is being produced in **Claude Design** (`claude.ai/design`), delivered **one screen at a time**. The **brand/logo** is the first ready piece (Claude Design project `8c9fc86c-f55b-4093-95cb-1eb412181a7e` — `Health Debug Brand.dc.html` + `assets/brand/hd-tile-dark.svg` + `support.js`). **Hard rule:** no client/app UI session (web, chrome, apple, android, desktop rendering) starts until its screen's design is delivered; when a screen lands, the matching core module is coded to kick it off. Backend/core modules (M0 foundation, engine plugins, MCP) are **not** design-gated and may proceed. The brand design will become the **single design-token + logo asset source** (replacing the legacy three-hand-maintained-token-file liability).

---

## 4. Risk Register

| # | Risk | Why it matters | Mitigation |
|---|---|---|---|
| R1 | **Thin-client discipline drift** | A client "helpfully" computing a timer, cooldown, or trigger verdict locally forks the SSOT and silently breaks protocol correctness across 6 client families. | Architectural rule stated in every client plan doc; per-phase exit criterion is an explicit thin-client audit (no temporal/state/protocol logic in client code); all such logic lives only in the ToGO API. |
| R2 | **Expand-contract discipline erosion** | One "quick" destructive migration breaks the migration guarantee and can strand deployed clients. | Atlas-managed migrations only; every migration reviewed against the expand-contract pattern; NOT NULL + defined default verified for every column before merge. |
| R3 | **RTL coverage gaps** | Arabic RTL is a first-class requirement including mirrored progress bars and layout mirroring; partial RTL is a broken product for RTL users. | ICU Message Format everywhere, no string concatenation, RTL review as an explicit exit criterion in every client phase (2, 3, 4, 5, 6). |
| R4 | **BYOK key security** | User-supplied AI keys (OpenAI, Anthropic, Google, Apple Intelligence) are high-value secrets; a key reaching a client or logs is a breach. | Keys encrypted at rest in the backend; ALL AI calls proxied server-side; no key ever serialized into any client payload; detailed in `10-security-integrations-b2b.md`. |
| R5 | **Scope creep from future-state B2B features** | Doctor dashboards, Medical Restrictions, gamification, and marketplace APIs are context, not scope; building toward them now delays Phases 1–6 and bloats the schema. | Future state is quarantined in `10-security-integrations-b2b.md`; Phases 1–6 build only what is specified; the only allowance is avoiding designs that would preclude future engine parameterization. |

---

## 5. Open Questions (blocked on user / pending design)

Genuinely undefined in the current spec — recorded here rather than invented:

1. **All screen inventories, layouts, and interaction flows** for every client — **PENDING DESIGN** (Figma / Claude design in progress).
2. ~~**Light-mode alert color**~~ — **RESOLVED 2026-09-01** by the imported brand kit: the light-mode bug/alert color is **`#C62230`** (see `brand/README.md` and `brand/tokens.css`).
3. **Whether later client phases (3–6) may overlap** or must be strictly sequential — the spec gives an order but not an overlap policy.
4. **Chrome extension feature scope** — which engines/surfaces appear in the extension is not yet specified.
5. **Trigger Families food catalog** — the three families (Gout, IBS-GERD, Fatty Liver) are defined, but the actual food-item categorization dataset and its sourcing are not yet specified.
6. **Definition of "movement away from the screen"** for the Kinetic Pomodoro Engine — which wearable signals/thresholds qualify is not yet specified (and per SSOT, the verdict must be computed server-side).