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