Pages · Health Debug

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. 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.

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.
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

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).
- 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 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:

ToGO backend scaffolding — ToGO Framework project + Microkernel (config, hooks, plugin registry), TOGO auth, PostgreSQL via the ToGO postgres image, sqlc + Atlas wired up.
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.
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:

All screen inventories, layouts, and interaction flows for every client — PENDING DESIGN (Figma / Claude design in progress).
~~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).
Whether later client phases (3–6) may overlap or must be strictly sequential — the spec gives an order but not an overlap policy.
Chrome extension feature scope — which engines/surfaces appear in the extension is not yet specified.
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.
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).