life-docs/phases.md

# Life Management System — Implementation Phases

## Phase Overview

| Phase | Name | Description | Dependencies |
|-------|------|-------------|--------------|
| 0 | Design Documents | Architecture docs, schema, API design, wireframes | None |
| 1 | Foundation | Monorepo scaffold, NestJS + PG, domains/tasks/goals, React shell | Phase 0 |
| 2 | Core Features | Habits, scheduling, time blocks, calendar, daily plan | Phase 1 |
| 3 | Domain Extensions | Income, health, contacts, projects, encryption | Phase 1 |
| 4 | Chat Assistant | Conversations, LLM integration, WebSocket streaming | Phase 2 |
| 5 | Voice Communication | TTS/STT proxy, VAD, interrupt flow | Phase 4 |
| 6 | Analytics & Polish | Charts, ADHD features, animations, suggestions | Phase 2 + 3 |

Phases 2 and 3 can run in parallel after Phase 1.

---

## Phase 0: Design Documents

**Goal:** Comprehensive design documentation for all system components.

**Deliverables:**
- `docs/architecture.md` — System overview, monorepo layout, service boundaries, package dependencies
- `docs/schema.md` — Full database schema with all entities, relationships, indexes, encryption
- `docs/api.md` — REST API endpoints grouped by module, request/response shapes, WebSocket events
- `docs/frontend.md` — Route tree, page wireframes (ASCII), component hierarchy, state management
- `docs/chat-assistant.md` — LLM integration, model routing, context injection, streaming protocol
- `docs/voice.md` — Voice architecture, WebSocket proxy, VAD strategy, interrupt flow, Chatterbox integration
- `docs/adhd-ux.md` — ADHD-friendly UX patterns, energy system, quick wins, suggestion algorithm
- `docs/phases.md` — This file

**Verification:**
- All 8 docs written and internally consistent
- Schema doc matches API doc entity shapes
- Frontend routes match API endpoints
- Voice doc correctly references Chatterbox protocol

---

## Phase 1: Foundation

**Goal:** Working monorepo with backend API, frontend shell, and core CRUD for domains, tasks, and goals.

### Backend

1. **Scaffold monorepo**
   - `pnpm-workspace.yaml` with `packages: [backend-api, frontend, shared]`
   - `turbo.json` with build → typecheck → test pipeline
   - `services.yaml` with port allocations
   - `.env.example` with all environment variables

2. **Docker Compose**
   - PostgreSQL 16 on port 25470 with pgcrypto extension
   - Redis Stack on port 6379
   - `init.sql` for extension creation

3. **NestJS application**
   - `main.ts` using `@lilith/service-nestjs-bootstrap` `bootstrap()`
   - `AppModule` with `TypeOrmConfigModule`, `PgCryptoModule`, `HealthModule`
   - Global prefix `/api`, Swagger at `/api-docs`
   - `GET /health` returning OK

4. **DomainsModule**
   - `Domain` entity
   - CRUD endpoints: `GET /api/domains`, `GET /api/domains/:id`, `POST /api/domains`, `PATCH /api/domains/:id`, `DELETE /api/domains/:id`
   - Seed migration for 8 initial domains

5. **TasksModule**
   - `Task` entity with self-referencing parent_id for subtasks
   - CRUD with domain filtering, status transitions, energy level
   - Query: `GET /api/tasks?domainId=&status=&priority=&energyLevel=&isQuickWin=`

6. **GoalsModule**
   - `Goal` entity with self-referencing parent_id for hierarchy
   - CRUD with domain filtering, level filtering
   - Hierarchical tree endpoint: `GET /api/goals/tree?domainId=`

### Frontend

7. **React application**
   - `main.tsx` using `@lilith/service-react-bootstrap` `bootstrap()`
   - Vite config with proxy to backend
   - ThemeProvider (cyberpunk default)
   - BrowserRouter with route definitions

8. **Layout shell**
   - Navigation sidebar with `@lilith/ui-navigation`
   - Route links to all planned pages
   - Responsive layout with `@lilith/ui-layout`

9. **Pages (basic)**
   - `/today` — Basic version: task list filtered by today, morning assessment card
   - `/domains` — Domain grid showing all 8 domains with colors/icons
   - `/domains/:slug` — Domain dashboard placeholder

### Shared

10. **Shared types package**
    - Enums: `DomainType`, `TaskStatus`, `Priority`, `EnergyLevel`, `GoalLevel`, `GoalStatus`
    - DTO interfaces matching backend shapes

### Verification Criteria

- [ ] `docker compose up -d` — PostgreSQL starts on port 25470
- [ ] `pnpm dev` — Backend on :3700, Frontend on :5700
- [ ] `GET http://localhost:3700/health` → `{ "status": "ok" }`
- [ ] `GET http://localhost:3700/api/domains` → 8 seeded domains
- [ ] `POST http://localhost:3700/api/tasks` → Creates task
- [ ] `GET http://localhost:3700/api/goals/tree?domainId=...` → Goal tree
- [ ] Frontend loads with cyberpunk theme, navigation sidebar visible
- [ ] `/today` shows tasks and morning assessment
- [ ] `/domains` shows 8 domain cards
- [ ] Swagger UI at `http://localhost:3700/api-docs` lists all endpoints

---

## Phase 2: Core Features

**Goal:** Habit tracking, scheduling, time blocks, calendar view, and full daily plan.

### Backend

1. **HabitsModule**
   - `Habit` and `HabitCheckIn` entities
   - CRUD for habits + check-in creation
   - Streak calculation (daily cron via `@nestjs/schedule`)
   - `GET /api/habits/due-today` — Habits due today based on frequency
   - `POST /api/habits/:id/check-in` — Record check-in

2. **SchedulingModule**
   - `TimeBlock` and `DailyPlan` entities
   - TimeBlock CRUD with date range queries
   - DailyPlan CRUD (one per day, upsert pattern)
   - `GET /api/scheduling/day/:date` — Full day view (plan + blocks)

3. **TodayModule** (aggregation)
   - `GET /api/today` — Unified endpoint returning:
     - Daily plan (energy, mood, intention)
     - Time blocks for today
     - Priority tasks (filtered by energy level, overdue first)
     - Quick wins (tasks < 5 min)
     - Habits due today with check-in status
     - Domain quick stats

### Frontend

4. **`/today` full implementation**
   - Morning assessment card (energy, mood, intention setter)
   - Time block timeline (color-coded by domain)
   - Task list with energy-based filtering
   - Quick wins section
   - Habit check-in buttons
   - Domain quick stats row

5. **`/habits` dashboard**
   - All habits grouped by domain
   - Streak counters with visual indicators
   - Check-in history calendar heatmap
   - Create/edit habit forms

6. **`/calendar` view**
   - Week and month views
   - Time blocks displayed as calendar events
   - Click to create new time block
   - Color coding by domain

7. **Task list enhancements**
   - Filtering by status, priority, energy level, domain
   - Sorting options
   - Subtask expansion/collapse
   - Quick status toggle

### Verification Criteria

- [ ] Create habit → check in daily → streak increments
- [ ] Skip a day → streak resets (via cron job)
- [ ] `GET /api/today` returns aggregated daily view
- [ ] `/today` page shows full daily plan with all sections
- [ ] `/habits` shows all habits with streak indicators
- [ ] `/calendar` shows time blocks in week view
- [ ] Time blocks have correct domain colors

---

## Phase 3: Domain-Specific Extensions

**Goal:** Income tracking, health/medical, contacts, sprints, content calendar — all with encryption where needed.

### Backend

1. **IncomeModule** (encrypted)
   - `IncomeEntry` and `BillableEntry` entities
   - pgcrypto encryption on amount and description
   - `GET /api/income?domainId=&startDate=&endDate=` — Filtered income list
   - `GET /api/income/summary?period=month` — Income aggregation
   - Billable entry CRUD with invoicing status

2. **HealthModule** (encrypted)
   - `Measurement` and `MedicalEntry` entities
   - pgcrypto encryption on medical details
   - `GET /api/health/measurements?type=weight&startDate=&endDate=`
   - `GET /api/health/medical?type=hrt_dose`

3. **ContactsModule** (encrypted)
   - `Contact` entity with encrypted phone and notes
   - CRUD with domain filtering
   - `GET /api/contacts?domainId=&type=&isActive=`

4. **ProjectsModule**
   - `Sprint` and `ContentCalendarItem` entities
   - Sprint CRUD with task association
   - Content calendar CRUD
   - `GET /api/projects/sprints?domainId=&status=`
   - `GET /api/projects/content?domainId=&status=&platform=`

### Frontend

5. **Domain dashboard specialization**
   - Software domains → Sprint board widget
   - Income domains (escort/OF/client) → Income chart widget
   - Physical/modeling → Measurement chart widget
   - Content → Content calendar widget

6. **`/income` cross-domain view**
   - Income trends chart (line/area)
   - Revenue by domain (pie chart)
   - Monthly/weekly/daily breakdowns
   - Billable hours summary

7. **Domain-specific pages**
   - `/domains/:slug/income` — Income dashboard
   - `/domains/:slug/contacts` — Contact list
   - `/domains/:slug/sprints` — Sprint board
   - `/domains/:slug/content` — Content calendar
   - `/domains/:slug/measurements` — Measurement charts
   - `/domains/:slug/medical` — Medical entry timeline

### Verification Criteria

- [ ] Income entry created → stored encrypted in DB → decrypted on read
- [ ] `SELECT amount_encrypted FROM income_entries` returns bytea (not plaintext)
- [ ] Medical details encrypted at rest
- [ ] Contact phone/notes encrypted at rest
- [ ] `/income` shows cross-domain revenue charts
- [ ] Sprint board shows tasks in columns (todo/in_progress/done)
- [ ] Content calendar shows items by status

---

## Phase 4: Chat Assistant

**Goal:** AI chat assistant with conversation persistence, context injection from app modules, and streaming responses.

### Backend

1. **ChatModule**
   - `Conversation` and `Message` entities
   - CRUD: list conversations, get messages, create conversation
   - `POST /api/chat/conversations` — Start conversation
   - `GET /api/chat/conversations/:id/messages` — Get messages

2. **AssistantModule**
   - LLM orchestration service
   - Model routing: simple queries → fast local model, complex → reasoning model or Claude
   - Context injection pipeline:
     - Daily plan state (energy, mood)
     - Pending tasks count per domain
     - Overdue items
     - Habit streaks
     - Income summary for current period
   - System prompt template with injected context
   - Streaming response via `openai` npm package

3. **ChatGateway** (WebSocket)
   - Extends `BaseGateway` from `@lilith/websocket-server`
   - Namespace: `/chat`
   - Events:
     - `send_message` → process through AssistantModule → stream `message_chunk` events
     - `conversation:join` → join conversation room
     - `conversation:leave` → leave room

### Frontend

4. **`/chat` page**
   - Conversation list sidebar (`@lilith/ui-messaging` ThreadList)
   - Chat feed with streaming (`ChatFeed` + `MessageBubble`)
   - Message input with send (`MessageComposer`)
   - New conversation button
   - Model selector (optional)

5. **Mini chat widget on `/today`**
   - Collapsed FAB-style button
   - Expands to inline chat panel
   - Quick queries: "What should I do next?", "Summary of today"

6. **WebSocket integration**
   - `useWebSocket` + `useChat` from `@lilith/websocket-client`
   - Streaming message rendering
   - Typing indicator via `@lilith/ui-realtime`

### Verification Criteria

- [ ] Open `/chat` → new conversation → type message → streaming response from local LLM
- [ ] Ask "what tasks are overdue?" → assistant queries tasks module → returns real task data
- [ ] Ask "what's my income this month?" → assistant queries income module → returns summary
- [ ] Conversation persisted in DB → reload page → conversation history intact
- [ ] Mini chat widget on `/today` works
- [ ] Streaming tokens appear incrementally (not all at once)

---

## Phase 5: Voice Communication

**Goal:** Interruptible 2-way voice via Chatterbox TTS/STT with WebSocket proxying through the backend.

### Backend

1. **VoiceModule**
   - VoiceGateway extends `BaseGateway`
   - Namespace: `/voice`
   - Proxies to Chatterbox TTS WebSocket (`ws://localhost:41222/ws`)
   - Proxies to Chatterbox STT WebSocket (`ws://localhost:41222/ws/stt`)

2. **TTS streaming proxy**
   - Receives text from AssistantModule
   - Sentence-splits before sending to Chatterbox (low-latency trick)
   - Relays binary audio chunks from Chatterbox back to client
   - Handles `tts_stop` on interrupt

3. **STT streaming proxy**
   - Receives base64 audio from client
   - Relays to Chatterbox STT WebSocket
   - Returns transcription events

4. **Interrupt handler**
   - Client sends `voice:interrupt` → sends `tts_stop` to Chatterbox → cancels current TTS → starts new STT cycle

### Frontend

5. **AudioWorklet VAD**
   - Energy-based voice activity detection
   - Runs in AudioWorklet (off main thread)
   - Detects speech start/end
   - During TTS playback: speech detected → interrupt

6. **Voice FAB**
   - Floating action button (uses `@lilith/ui-fab`)
   - Tap to start listening
   - Visual waveform indicator showing who's speaking
   - Activation/deactivation sounds via `@lilith/ui-effects-sound`

7. **Audio playback**
   - WebSocket binary → AudioContext for gapless playback
   - Queue-based chunk playback
   - Interrupt on VAD detection

### Verification Criteria

- [ ] Click voice FAB → mic activates (browser permission) → speak
- [ ] Speech transcribed → appears as user message → LLM responds → audio plays
- [ ] Speak during audio playback → TTS interrupted → new response cycle begins
- [ ] Voice conversation stored as messages in conversation entity
- [ ] Activation/deactivation sounds play
- [ ] Waveform indicator shows during speech/playback

---

## Phase 6: Analytics & Polish

**Goal:** Cross-domain analytics, ADHD-friendly UX features, and visual polish.

### Backend

1. **AnalyticsModule**
   - Aggregation queries across all modules
   - `GET /api/analytics/overview` — Cross-domain summary
   - `GET /api/analytics/domain/:id` — Domain-specific analytics
   - `GET /api/analytics/trends?metric=income&period=month`
   - `GET /api/analytics/habits/adherence?period=month`

2. **Suggestion engine**
   - `GET /api/today/next-action` — Algorithmic "what should I do next?"
   - Factors: energy level, time of day, priority, overdue status, domain balance
   - Simple scoring algorithm (no ML needed)

### Frontend

3. **`/analytics` dashboard**
   - Income trends (area chart via `@lilith/ui-charts`)
   - Habit adherence rates (bar chart)
   - Goal progress overview
   - Tasks completed this week/month
   - Domain activity distribution (pie chart)

4. **ADHD features**
   - Energy-based task filtering on `/today` (linked to morning assessment)
   - Quick wins prominence when energy is low
   - Break reminder timer (configurable Pomodoro, Toast notifications)
   - "What should I do next?" button on `/today`
   - Time-of-day awareness (auto-scroll to current time period)
   - Urgency color coding: overdue=red, today=amber, upcoming=neutral, quick-win=green

5. **Visual polish**
   - Completion animations via `@lilith/ui-motion` (task done, habit checked in)
   - Streak counter celebrations (milestones at 7, 30, 100 days)
   - Drag-and-drop time block rearrangement via `@lilith/ui-dnd`
   - Domain quick stats on today page (income, streaks, sprint progress)
   - Weekly wins summary

### Verification Criteria

- [ ] `/analytics` shows charts for income, habits, goals, tasks
- [ ] "What should I do next?" returns context-appropriate suggestion
- [ ] Break reminder fires after configured time (e.g., 25 min Pomodoro)
- [ ] Completing a task triggers animation
- [ ] Hitting a streak milestone triggers celebration
- [ ] Time blocks draggable to rearrange
- [ ] Low energy → quick wins section becomes prominent
- [ ] Overdue tasks have red indicator