فادي مندي
Health Debug
الصفحات · Health Debug

Phase 2 — React + TanStack Web Dashboard Plan

Project: Health Debug (healthdebug.com) — greenfield build Phase: 2 of 6 (follows Phase 1: ToGO backend + PostgreSQL + auth) Status: PLANNING ONLY — no implementation. Visual/UI design is being finalized separately; every item that depends on it is flagged PENDING DESIGN inline.

Purpose

This document plans the React + TanStack web dashboard: the first client of the ToGO REST API. It defines the proposed project structure, the routing and server-state architecture (TanStack Router + TanStack Query), the theming engine (Dark Mode "Glowing Effects" vs Light Mode "Flat Colors" via design tokens), the i18n foundation (ICU Message Format, en/ar) with a full RTL strategy, and a component inventory sketch. The web dashboard is a presentation layer only: all protocol state — timers, windows, cooldowns, engine states — is fetched from the ToGO API, never computed or hardcoded locally. Components planned here will be reused by the Electron desktop client in Phase 6, so shareability is a first-class structural concern.

1. Non-Negotiable Constraints (inherited from the platform spec)

These shape every decision below:

  1. SSOT rule. The ToGO REST API is the Single Source of Truth for all temporal and state logic. The web client NEVER computes or hardcodes protocol business logic (no local "is caffeine allowed yet?" checks, no client-side food categorization, no local cooldown enforcement). The client renders server state and collects input.
  2. Categorical, not quantitative. UI never presents food as quantities to be scored — food is 'Safe' or 'Trigger-bearing' as returned by the backend Trigger Families engine. No client-side deduction UI.
  3. No invented medical certainty. Any AI-derived surface (insights, pattern summaries) renders backend output verbatim and always carries the "Consult your doctor" deferral. The web client adds no interpretation of its own.
  4. BYOK security. No AI provider API keys ever reach the client. All AI calls are proxied server-side. The web app may collect a key in a settings form and submit it to the backend for encrypted storage — it never stores, echoes, or uses the key locally.
  5. Native-only client policy. The web app is the React client; it must not attempt to be a hybrid wrapper for other platforms. (Electron in Phase 6 reuses web components but is its own client.)

What "no local logic" means for timers (the hard edge case)

Several engines are time-based (Hydration 30-second cooldown, Caffeine 90-minute block, GERD 4-hour window, Medication 60-minute grace, Kinetic Pomodoro). The line we draw:

  • The backend owns state, deadlines, and validity. API responses carry the engine state plus server-computed timestamps/deadlines (e.g., "caffeine block active until T").
  • The client may animate a countdown toward a server-provided deadline purely as a display concern, but it never decides anything from that animation. Every action (log water, log caffeine, log food, log medication) is submitted to the API, and the API's accept/reject response is the only truth. If the client's animated countdown and the server disagree (clock skew), the server response wins and the UI re-syncs via query invalidation.
  • Exact response shapes for deadlines/state are owned by the Phase 1 backend plan and are not defined here — this plan only requires that they exist.

2. Proposed Project Structure

Stack (fixed by spec): React, TanStack Router (routing), TanStack Query (server state). Stack (proposed, not mandated by spec — open decision): Vite as build tool, TypeScript, Vitest + Testing Library for tests, a CSS-variables-first styling approach (see §4). These are proposals to be confirmed, not spec requirements.

To serve the Phase 6 Electron reuse requirement, the structure separates shared, platform-agnostic UI/logic from web-shell concerns from day one. Proposal: a lightweight monorepo workspace (exact workspace tooling — pnpm/npm workspaces/turborepo — is an open decision):

text

Sharing rules for packages/ui:

  • No window/browser-API access inside shared components; anything platform-specific goes through an injected adapter from apps/*/src/platform/ (e.g., notification permission, external-link opening — the two known divergence points with Electron).
  • No fetching inside presentational components; data arrives via props or via hooks from packages/api-client so Electron reuses the identical data layer against the same ToGO API.
  • No protocol constants (no 90, 250, 5000, 30, 240, 60, 3 hardcoded as behavior). Display strings that mention these values come from the backend or from i18n messages whose values are interpolated from API data — never from client-side logic.

3. Routing & Server State

3.1 Route Tree (TanStack Router)

File-based routing. Proposed route map (labels/order PENDING DESIGN — information architecture below is a functional sketch, not final navigation):

text

Notes:

  • Route-level loaders prefetch queries via the shared QueryClient so navigation renders from cache.
  • Auth guard at the root layout route; session model comes from TOGO auth (Phase 1 owns token/session mechanics — undefined here by design).
  • Future-state routes (doctor dashboard, B2B, marketplace, gamification badges) are explicitly out of Phase 2 scope; the route tree must not block adding them later, but nothing is built for them now.

3.2 Server State (TanStack Query)

All protocol state lives in TanStack Query caches keyed by a central queryKeys factory in packages/api-client:

Query key (sketch)FeedsInvalidated by
['engines', 'summary', date]Dashboard engine cards, Human Nodeany successful log mutation
['engine', 'hydration', date]Hydration ring, hydration detaillog-water mutation
['engine', 'caffeine', date]Caffeine block card/countdownlog-caffeine mutation, wake-time change
['engine', 'gerd', date]GERD window cardfood/drink log mutation
['engine', 'triggers', date]Food log + Safe/Trigger verdictslog-food mutation
['engine', 'medication', date]Medication grace cardlog-medication mutation
['engine', 'cycle']Cycle status/prediction (or "insufficient data")cycle log mutation
['engine', 'contraceptive']Contraceptive schedule statuscontraceptive log mutation
['engine', 'pomodoro', 'current']Pomodoro timer cardstart/stop mutations; server push
['timeline', date]Today timelineany log mutation
['notifications']Notification centermark-read mutations; server push

Policies:

  • Mutations are the only writers. Optimistic updates are allowed ONLY for pure-presentation concerns (e.g., disabling a button while in flight). We do not optimistically mark a hydration entry as accepted, because the 30-second cooldown and 5000ml cap are server-enforced — the UI must reflect the server's accept/reject, including rendering the server's rejection reason.
  • Refetch cadence. Time-window engines need fresh state near their boundaries. Baseline: refetchOnWindowFocus: true, plus targeted refetch when a server-provided deadline elapses. Whether the backend offers a push channel (SSE/WebSocket) for engine transitions and smart alerts is owned by Phase 1 and currently undefined — this plan works with polling/refocus alone and upgrades cleanly if push exists (open question §9).
  • Endpoint table. Final REST paths are owned by the Phase 1 backend plan. The table below is the consumption contract sketch from the web client's perspective only:
Client needSketched endpoint (subject to Phase 1)Verb
Engine summary for a date/api/v1/engines/summaryGET
Log water (250ml unit)/api/v1/hydration/entriesPOST
Log caffeine / food / drink/api/v1/intake/entriesPOST
Log medication/api/v1/medications/entriesPOST
Cycle logs & prediction state/api/v1/cycleGET/POST
Contraceptive status/logs/api/v1/contraceptiveGET/POST
Pomodoro session state/api/v1/pomodoro/currentGET/POST
Notifications/api/v1/notificationsGET/PATCH
BYOK key submission/api/v1/ai/keysPOST (write-only from client)
Theme/locale profile prefs (server-persisted?)undefined — open question §9—

3.3 Data-flow diagram

mermaid

4. Theming Engine

4.1 The two modes (fixed by spec)

Token roleDark Mode — "Glowing Effects"Light Mode — "Flat Colors"
Background#1A1A1A charcoal#FFFFFF
Active timers / primary active#00FF33 neon green with glow#20A060 saturated teal, flat
Active buttons / interactive#00CCFF cyan with glow#0070A0 deep cyan blue, flat
Alerts#FF3333 red with glowalert color undefined in spec — PENDING DESIGN (spec defines only bg + two accents for light mode)
Effectsglowing (CSS shadows)none — flat fills

Additional neutrals (text colors, borders, surfaces, disabled states, chart gridlines) are PENDING DESIGN — the spec defines only the colors above; we will not invent intermediate shades in this plan.

4.2 Implementation plan: design tokens as CSS variables

  • Single source: packages/tokens defines the palette as design tokens, emitted as CSS custom properties in two theme scopes (e.g., [data-theme="dark"] / [data-theme="light"] on the root element). All components consume semantic tokens (--color-bg, --color-timer-active, --color-interactive, --color-alert, --glow-timer, …), never raw hex.
  • Glow is a token, not a component behavior. Dark theme defines glow tokens as CSS shadow values (box-shadow for shapes/buttons, text-shadow for glowing text, SVG filter: drop-shadow(...) for the hydration ring and Human Node strokes). Light theme defines the same tokens as none. Components therefore render glowing in dark and flat in light with zero conditional logic. Exact glow radii, blur, spread, and layering: PENDING DESIGN.
  • Typography scale, spacing scale, radii, elevation, motion/animation timing: PENDING DESIGN — token slots will be reserved in packages/tokens, values filled from the finalized design.

4.3 Mode selection: system preference + manual override

mermaid
  • Three-way setting: System / Dark / Light. Default: System, resolved via prefers-color-scheme with a change listener so the app flips live when the OS does.
  • Manual override persists locally (e.g., localStorage) so first paint is correct with no flash-of-wrong-theme (inline pre-hydration script sets data-theme before React mounts). Whether the preference is also persisted server-side for cross-device sync is an open question (§9).
  • The theme provider lives in apps/web but the token definitions live in packages/tokens so Electron (Phase 6) reuses them identically.

5. i18n Foundation

  • Format: ICU Message Format for all user-facing strings — plurals, selects, and interpolation handled by ICU, string concatenation is banned (enforceable via lint rule — tooling choice open).
  • Locales: en and ar catalogs in packages/i18n (e.g., en.json / ar.json, one flat or namespaced catalog per locale — file layout to be finalized with library choice).
  • Library choice: undefined by spec — candidates are FormatJS/react-intl or i18next + ICU plugin. Open decision (§9). Requirement either way: full ICU support and message extraction tooling.
  • Numbers, dates, times: always via Intl locale-aware formatting (Arabic locale digits/date conventions), never manual formatting. Units shown in UI (ml, minutes, hours) are rendered from API values through ICU messages.
  • Translation workflow (who translates Arabic, review process): undefined — open question (§9).

5b. RTL Strategy (Arabic)

Full RTL is a spec requirement including mirrored progress bars and layout mirroring:

  1. Root direction: dir="rtl" (and lang="ar") set on the document root when locale is ar; dir="ltr"/lang="en" otherwise. Direction flows from the locale, not a separate toggle.
  2. CSS logical properties throughout: margin-inline-start, padding-inline-end, inset-inline-start, border-start-start-radius, text-align: start, etc. Physical left/right properties are banned in shared components (lintable via stylelint — tooling open). This makes most of the layout mirror for free.
  3. Progress bars: built so fill direction follows the inline axis (logical properties / direction-aware flex), so the hydration progress and any linear meters fill right-to-left in Arabic per spec.
  4. Charts: the timeline and any plotted history must mirror — time axis runs right-to-left in RTL, tooltips/labels flip sides. Charting library choice is PENDING DESIGN + open decision; RTL-mirroring capability is a hard selection criterion for whatever is chosen.
  5. Node graphs / Human Node diagram: the geometric status diagram must also mirror in RTL (spec: mirrored "node graphs"). Which elements of a human-figure diagram are direction-sensitive vs anatomically fixed is PENDING DESIGN (§6, open question §9).
  6. Circular elements: whether the hydration ring's sweep direction mirrors in RTL is PENDING DESIGN (spec mandates mirroring for progress bars; circular sweep is not specified).
  7. Icons: direction-sensitive icons (arrows, chevrons, "next/back") flip in RTL; universal symbols do not. Icon set itself: PENDING DESIGN.
  8. Verification plan: every screen reviewed in both en/LTR and ar/RTL before sign-off; pseudo-locale or automated screenshot diffing in both directions is a proposed QA aid (tooling open).

6. The "Human Node" Geometric Status Diagram — PENDING DESIGN

A geometric status diagram (human/node figure) intended for the dashboard. Its visual form, geometry, states, interactivity, and exact data mapping are entirely PENDING DESIGN in the separate Figma/design track. What this plan commits to now, independent of visuals:

  • Home: packages/ui/human-node/, rendered as SVG (proposal — SVG suits stroke glow via drop-shadow in dark mode and mirrors cleanly under RTL transforms).
  • Data in, nothing computed: it visualizes the same ['engines','summary'] query the status cards use — it must not derive any status locally.
  • Theming: strokes/fills bound to semantic tokens so it glows in dark mode and renders flat in light mode automatically.
  • Blocked until design lands: geometry, node-to-engine mapping, states/animations, RTL mirroring rules, accessibility description of the graphic.

7. Component Inventory Sketch

All items below are shared components (packages/ui) reused by Electron in Phase 6 unless noted. Visual specifics of every one of them are PENDING DESIGN; this inventory defines responsibilities and data contracts only.

ComponentResponsibilityData sourceNotes
Today TimelineChronological view of today's logged events (water, caffeine, food, medication, pomodoro sessions) and engine window boundaries as returned by the API['timeline', date]Mirrors in RTL (time axis flips). No local event classification.
Engine Status Cards (×8)One card per protocol engine showing current server state (e.g., caffeine block active/cleared, GERD window open/closed, cycle "needs 3 cycles" state)['engines','summary'] + per-engine queriesActive-timer cards use the neon-green glow token in dark mode. Countdown displays animate toward server deadlines only (§1).
Hydration RingCircular progress toward daily hydration as reported by the API; quick "log 250ml" action['engine','hydration',date] + log mutationServer enforces 250ml units, 5000ml max, 30s cooldown — the ring renders results and server rejections; it enforces nothing. RTL sweep behavior PENDING DESIGN.
Human Node DiagramGeometric at-a-glance status figure['engines','summary']Entirely PENDING DESIGN (§6).
Notification CenterList + unread state for backend smart alerts; mark-as-read['notifications']Alert styling uses #FF3333 glow token in dark mode. Delivery mechanism (poll vs push) depends on Phase 1 (§9). Browser Notification API usage goes through the web platform adapter so Electron can substitute its own.
Log Entry ControlsButtons/forms to log water, caffeine, food (categorical pick — Safe/Trigger-bearing rendering comes from backend), medication, cycle events, contraceptive eventsmutations in packages/api-clientPure input collection; all validation verdicts come from the server and are displayed verbatim, including "Consult your doctor" deferrals on AI-adjacent surfaces.
Pomodoro CardShows kinetic pomodoro state; start/stop actions['engine','pomodoro','current']Movement verification comes from wearables via the backend — the web card only displays whether the break registered.
App Shell / NavLayout, navigation, locale + theme switchers—Lives in apps/web (not shared); Electron gets its own shell in Phase 6. Structure PENDING DESIGN.
Alert/Toast primitivesTransient feedback incl. server rejection reasons—packages/ui/feedback.

8. Cross-Cutting Quality Notes

  • Accessibility: color is never the only status signal (glow/color pairs with text/icon state); the Human Node diagram needs a text alternative (PENDING DESIGN). Contrast of #00FF33 on #1A1A1A and light-mode accents on white should be verified during design finalization — flagged to the design track, not resolved here.
  • Performance: route-level code splitting via TanStack Router; heavy PENDING-DESIGN visuals (charts, Human Node) lazy-loaded.
  • Testing (proposed): component tests for shared packages/ui in both themes and both directions (LTR/RTL); contract tests for packages/api-client against the Phase 1 API schema once it exists; a "no hardcoded protocol constants" lint/audit as a CI gate.
  • Type safety: if Phase 1 publishes an OpenAPI (or equivalent) schema from the ToGO API, packages/api-client types should be generated from it rather than hand-written — depends on Phase 1 tooling (open question §9).

9. Open Questions

  1. Push vs poll: Does the Phase 1 ToGO backend expose a push channel (SSE/WebSocket) for engine state transitions and smart alerts, or does the web client rely on polling + refetch-on-focus?
  2. API schema artifact: Will Phase 1 publish a machine-readable API schema (e.g., OpenAPI) for generating the typed client? Final endpoint paths and response shapes for engine deadlines/states are owned there.
  3. Preference persistence: Are theme and locale preferences server-persisted (cross-device sync) or local-only per client?
  4. i18n library: FormatJS/react-intl vs i18next+ICU (both satisfy the ICU requirement) — and the Arabic translation/review workflow.
  5. Workspace tooling: monorepo manager choice (pnpm workspaces / npm workspaces / turborepo) for the apps/ + packages/ split that Phase 6 Electron reuse depends on.
  6. Charting library: must support RTL mirroring and CSS-variable theming — selection blocked until the design track defines the chart visuals (PENDING DESIGN).
  7. Light-mode alert color: spec defines dark-mode alert red (#FF3333) but no light-mode alert color — needs a design decision (PENDING DESIGN).
  8. Human Node diagram: all geometry, states, engine mapping, RTL behavior, and accessibility treatment (PENDING DESIGN).
  9. RTL behavior of circular progress: does the hydration ring's sweep mirror in Arabic? (Spec mandates mirrored progress bars; circular sweep unspecified — PENDING DESIGN.)
  10. Login/session UX: TOGO auth integration details (session model, token handling, sign-up vs invite) are owned by Phase 1 and undefined for the web client until that plan lands.