phaseflow/IMPLEMENTATION_PLAN.md

PhaseFlow Implementation Plan

This file is maintained by Ralph. Run ./ralph-sandbox.sh plan 3 to generate tasks.

Current Status: Feature Complete

Test Coverage: 1014 unit tests (51 files) + 180 E2E tests (12 files) = 1194 total tests

All P0-P5 items are complete. The project is feature complete.

---

Architecture Summary

Tech Stack

Layer	Choice
Framework	Next.js 16 (App Router)
Runtime	Node.js 24
Database	PocketBase
Validation	Zod
Testing	Vitest + jsdom + Playwright
Linting	Biome

Critical Business Rules

1. Override Priority: flare > stress > sleep > pms (enforced in order)
2. HRV Unbalanced: ALWAYS forces REST (highest algorithmic priority, non-overridable)
3. Phase Limits: Strictly enforced per phase configuration
4. Token Expiration Warnings: Email at 14 days and 7 days before expiry
5. ICS Feed: Generates 90 days of phase events for calendar subscription

---

Completed Implementation

Library Files (12 files, 250+ tests)

File	Tests	Key Functions
cycle.ts	22	getCycleDay, getPhase, getPhaseConfig, dynamic phase boundaries
nutrition.ts	17	getNutritionGuidance, getSeedSwitchAlert, phase-specific guidance
email.ts	32	sendDailyEmail, sendPeriodConfirmationEmail, sendTokenExpirationWarning
ics.ts	33	generateIcsFeed, 90-day events, period prediction feedback, CATEGORIES
encryption.ts	14	AES-256-GCM encrypt/decrypt
decision-engine.ts	24	getTrainingDecision, getDecisionWithOverrides, 8 priority rules
garmin.ts	33	fetchHrvStatus, fetchBodyBattery, fetchIntensityMinutes, token validation
pocketbase.ts	10	createPocketBaseClient, isAuthenticated, getCurrentUser, loadAuthFromCookies
auth-middleware.ts	12	withAuth() wrapper, structured logging, IP logging
middleware.ts	12	Next.js page protection, redirects
logger.ts	16	Pino JSON output, log levels, child loggers
metrics.ts	33	Prometheus metrics, counters, gauges, histograms

API Routes (21 endpoints, 350+ tests)

Route	Tests	Purpose
POST /api/auth/logout	5	Session logout
GET /api/user	4	User profile
PATCH /api/user	17	Update preferences
POST /api/cycle/period	13	Log period start with prediction tracking
GET /api/cycle/current	10	Current cycle state
GET /api/today	24	Daily snapshot with decision
POST/DELETE /api/overrides	14	Override management
POST/DELETE /api/garmin/tokens	15	Token storage
GET /api/garmin/status	11	Connection status
POST /api/cron/garmin-sync	32	Daily data sync
POST /api/cron/notifications	20	Email notifications
GET /api/calendar/[userId]/[token].ics	11	ICS feed
POST /api/calendar/regenerate-token	9	Token regeneration
GET /api/history	19	Daily log history
GET /api/period-history	18	Period log history
PATCH/DELETE /api/period-logs/[id]	16	Period log management
GET /api/health	14	Health check
GET /metrics	15	Prometheus metrics

Pages (8 pages, 230+ tests)

Page	Tests	Features
Dashboard (/)	28	Decision card, data panel, nutrition, overrides, mini calendar
Login (/login)	32	OIDC + email/password, rate limiting
Settings (/settings)	34	Preferences, logout
Settings/Garmin	27	Token management, status
Calendar (/calendar)	23	Month view, ICS subscription
History (/history)	26	Daily log table
Period History	27	Period log table, edit/delete
Plan (/plan)	16	Phase overview, training reference

Components (10 components, 200+ tests)

Component	Tests	Purpose
DecisionCard	19	Status display with color coding
DataPanel	29	Biometrics display, HRV color coding, progress bar
NutritionPanel	16	Seeds, carbs, keto guidance
OverrideToggles	18	Override buttons
DayCell	32	Calendar day with phase colors, period indicator
MiniCalendar	23	Dashboard calendar widget
OnboardingBanner	16	Setup prompts
MonthView	31	Full calendar with navigation, keyboard nav
PeriodDateModal	22	Period input modal
Skeletons	29	Loading states with shimmer

E2E Tests (12 files, 180 tests)

File	Tests	Coverage
smoke.spec.ts	3	Basic app functionality
auth.spec.ts	14	Login, protected routes
dashboard.spec.ts	40	Dashboard display, overrides, accessibility
settings.spec.ts	26	Settings form, validation, persistence
garmin.spec.ts	12	Garmin connection, expiry warnings
period-logging.spec.ts	19	Period history, logging, modal flows
calendar.spec.ts	30	Calendar view, ICS feed, content validation
decision-engine.spec.ts	8	Decision priority chain
cycle.spec.ts	11	Cycle tracking
history.spec.ts	7	History page
plan.spec.ts	7	Plan page
health.spec.ts	3	Health/observability

---

E2E Test Enhancement Opportunities

These are optional enhancements to improve E2E coverage. Not required for feature completeness.

New Test Files (Lower Priority)

File	Tests	Description
notifications.spec.ts	3	Notification preferences
dark-mode.spec.ts	2	System preference detection
mobile.spec.ts	4	Mobile viewport behavior

Existing File Extensions

File	Additional Tests	Focus Area
auth.spec.ts	+6	OIDC flow, session persistence
calendar.spec.ts	+4	Responsive behavior, accessibility
settings.spec.ts	+1	Error recovery on failed save
garmin.spec.ts	+4	Token refresh, network error recovery

---

Notes

1. TDD Approach: Write failing tests first, then implement
2. Auth First: P0 items unlock all other work
3. No Mock Mode: Use real data and APIs only
4. ABOUTME Comments: All files start with 2-line ABOUTME
5. Commit Format: Descriptive message + Claude footer
6. Never use --no-verify: All commits go through pre-commit hooks

---

Revision History

• 2026-01-13: Added 5 settings persistence E2E tests (notification time, timezone, multi-field persistence)
• 2026-01-13: Added 5 period-logging E2E tests (modal flow, future date restriction, edit/delete flows)
• 2026-01-13: Added 5 Garmin E2E tests (expiry warnings, expired state, persistence, reconnection)
• 2026-01-13: Condensed plan after feature completion (reduced from 1514 to ~170 lines)
• 2026-01-12: Fixed spec gaps (email format, HRV colors, progress bar, emojis)
• 2026-01-11: Completed P5.1-P5.4 (period history, toast, CI, E2E)