docs/implementations-plan.md

 Here is Claude's plan:                                                                                                                    ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ PC Pal - Implementation Plan                                                                                                              
  
 Context

 PC Pal is an AI-powered IT tutor for elderly and beginner PC users, delivered via a web chat interface. The project addresses the gap     
 where 57M+ Americans aged 65+ struggle with basic computer tasks but existing solutions (YouTube, IT help desks, generic AI) fail to      
 teach lasting skills. PC Pal provides patient, step-by-step guidance with annotated visual screenshots, vocabulary simplification, and    
 persistent skill tracking.

 Delivery: Web UI (React) first. SMS (Twilio) and CollaborAITE integration planned for later.

 Timeline: v1 by Apr 14 | v2 by Apr 21 | v3 by Apr 28

 ---
 Tech Stack

 ┌──────────────────┬──────────────────────────────────────────────────────┐
 │    Component     │                        Choice                        │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Frontend         │ React (Vite)                                         │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Backend          │ Node.js + Express                                    │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ AI               │ Anthropic SDK (@anthropic-ai/sdk) with tool-use      │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Database         │ SQLite (v1/v2 via better-sqlite3), PostgreSQL for v3 │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Real-time        │ WebSocket (via ws or Socket.IO) for streaming chat   │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Image Processing │ Sharp (Node.js) for annotated screenshots (v2)       │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Scheduling       │ node-cron (v2+ for proactive messages)               │
 ├──────────────────┼──────────────────────────────────────────────────────┤
 │ Testing          │ Jest (backend), React Testing Library (frontend)     │
 └──────────────────┴──────────────────────────────────────────────────────┘

 ---
 Architecture - Message Flow

 React Chat UI (browser)
     |  WebSocket or POST /api/chat
     v
 Express Server (server/index.js)
     |
     v
 ConversationRouter (server/core/conversationRouter.js)
     |  lookup user, load/create session
     v
 SafetyMonitor (runs FIRST on every message)
     |  emergency/scam detection
     v
 TaskClassifier (Claude call)
     |  learn_skill | troubleshoot | follow_up | accessibility
     v
 AgentOrchestrator (Claude tool-use loop)
     |  system prompt with user profile, history, vocab level
     |  tools: get_next_step, complete_step, log_skill, flag_emergency
     v
 VocabularyFilter
     |  replace jargon, enforce sentence length
     v
 WebSocket/Response  →  React Chat UI

 ---
 Project Structure

 client/                          # React frontend (Vite)
   src/
     App.jsx                      # Main app with routing
     components/
       Chat/
         ChatWindow.jsx           # Main chat container
         MessageBubble.jsx        # Individual message display
         MessageInput.jsx         # Text input + send button
         StepIndicator.jsx        # "Step 2 of 5" progress bar
         VisualGuide.jsx          # Annotated screenshot display (v2)
       Onboarding/
         OnboardingFlow.jsx       # Name, OS, comfort level collection
       Layout/
         Header.jsx               # App header with user info
         Sidebar.jsx              # Skill history panel (v3)
     hooks/
       useChat.js                 # WebSocket connection + message state
       useUser.js                 # User profile state
     styles/
       globals.css                # Large fonts, high contrast, elderly-friendly
     main.jsx
   index.html
   vite.config.js

 server/                          # Node.js + Express backend
   index.js                       # Express app, WebSocket setup, DB init
   config.js                      # Environment variable loading
   db/
     database.js                  # SQLite connection + schema init
     schema.sql                   # Table definitions
   models/
     User.js                      # User CRUD operations
     Conversation.js              # Conversation CRUD
     Message.js                   # Message CRUD
     SkillEvent.js                # Skill event CRUD
     SafetyEvent.js               # Safety event CRUD
     StepSequence.js              # Step sequence CRUD
   core/
     agentOrchestrator.js         # Claude tool-use agent loop
     taskClassifier.js            # Message classification via Claude
     userProfileManager.js        # User profile logic + onboarding
     conversationState.js         # Session lifecycle + memory
     stepSequencer.js             # Numbered step management
     vocabularyFilter.js          # Jargon replacement + readability
     skillTracker.js              # Skill logging + reinforcement
     safetyMonitor.js             # Emergency + scam detection
     proactiveEngine.js           # Scheduled messages (v2)
     visualGuideGenerator.js      # Annotated screenshots via Sharp (v2)
   assets/
     vocabulary/
       basicSubstitutions.json    # Word replacement map
     screenshots/                 # Pre-captured OS screenshots (v2)
   routes/
     chat.js                      # POST /api/chat (REST fallback)
     users.js                     # GET/POST /api/users
     skills.js                    # GET /api/users/:id/skills (v3)
   __tests__/
     vocabularyFilter.test.js
     taskClassifier.test.js
     stepSequencer.test.js
     safetyMonitor.test.js
     conversationFlow.test.js

 package.json
 .env.example
 README.md

 ---
 Database Schema (SQLite)

 users

 CREATE TABLE users (
   id TEXT PRIMARY KEY,            -- UUID
   name TEXT,
   os_type TEXT,                   -- 'Windows 10', 'Windows 11', 'macOS', 'iPhone', 'Android'
   vocabulary_level TEXT DEFAULT 'basic',  -- basic | intermediate | standard
   accessibility_needs TEXT DEFAULT '[]',  -- JSON array
   comfort_level INTEGER DEFAULT 1,       -- 1-5
   onboarded INTEGER DEFAULT 0,           -- boolean
   created_at TEXT DEFAULT (datetime('now')),
   updated_at TEXT DEFAULT (datetime('now'))
 );

 conversations

 CREATE TABLE conversations (
   id TEXT PRIMARY KEY,
   user_id TEXT REFERENCES users(id),
   task_type TEXT,
   status TEXT DEFAULT 'active',          -- active | completed | abandoned
   context_summary TEXT,                  -- compressed older context
   started_at TEXT DEFAULT (datetime('now')),
   ended_at TEXT
 );

 messages

 CREATE TABLE messages (
   id TEXT PRIMARY KEY,
   conversation_id TEXT REFERENCES conversations(id),
   role TEXT NOT NULL,                     -- 'user' | 'assistant'
   body TEXT NOT NULL,
   created_at TEXT DEFAULT (datetime('now'))
 );

 step_sequences

 CREATE TABLE step_sequences (
   id TEXT PRIMARY KEY,
   conversation_id TEXT REFERENCES conversations(id),
   steps TEXT NOT NULL,                   -- JSON array of step objects
   current_index INTEGER DEFAULT 0,
   completed INTEGER DEFAULT 0
 );

 skill_events

 CREATE TABLE skill_events (
   id TEXT PRIMARY KEY,
   user_id TEXT REFERENCES users(id),
   skill_name TEXT NOT NULL,
   status TEXT DEFAULT 'started',         -- started | completed | abandoned
   practiced_at TEXT DEFAULT (datetime('now'))
 );

 safety_events

 CREATE TABLE safety_events (
   id TEXT PRIMARY KEY,
   user_id TEXT REFERENCES users(id),
   event_type TEXT NOT NULL,              -- emergency | scam_detected | distress
   trigger_text TEXT,
   created_at TEXT DEFAULT (datetime('now'))
 );

 ---
 Implementation Phases

 Phase 1 — v1 by April 14 (Core Chat Loop)

 Goal: User opens the web app, onboards (name + OS), and gets context-aware IT help from Claude with simplified vocabulary through a chat  
 interface.

 Steps:

 1. Project setup
   - Initialize Node.js project with package.json
   - Initialize React project with Vite in client/
   - Create .env.example with ANTHROPIC_API_KEY
   - Create server/config.js for env loading
   - Create server/db/database.js + schema.sql with all tables
   - Files: package.json, .env.example, server/config.js, server/db/*
 2. Express server + WebSocket
   - Express app in server/index.js with CORS, JSON parsing
   - WebSocket server (ws library) on same port for real-time chat
   - On WS connection: assign/lookup user session
   - On WS message: route through processing pipeline, send response back
   - REST fallback: POST /api/chat for non-WebSocket clients
   - File: server/index.js, server/routes/chat.js
 3. React chat UI
   - ChatWindow.jsx — scrollable message list + input
   - MessageBubble.jsx — styled differently for user vs assistant messages
   - MessageInput.jsx — large text input, prominent send button
   - useChat.js hook — manages WebSocket connection, message state, send/receive
   - Elderly-friendly CSS: minimum 18px font, high contrast, large click targets, simple layout
   - Files: client/src/components/Chat/*, client/src/hooks/useChat.js, client/src/styles/globals.css
 4. Onboarding flow
   - OnboardingFlow.jsx — large-button wizard: "What's your name?", "What computer do you use?" (Windows/Mac/iPhone/Android with icons),   
 "How comfortable are you with computers?" (1-5 scale)
   - Saves to users table via POST /api/users
   - Shown on first visit, skipped after (user ID stored in localStorage)
   - Files: client/src/components/Onboarding/OnboardingFlow.jsx, server/routes/users.js
 5. User profile manager
   - getOrCreateUser(id), updateProfile(id, fields)
   - Returns full user profile for system prompt injection
   - File: server/core/userProfileManager.js, server/models/User.js
 6. Task classifier
   - Single Claude call with classification prompt
   - Returns: learn_skill | troubleshoot | follow_up | accessibility | unknown
   - Also extracts: topic, urgency
   - File: server/core/taskClassifier.js
 7. Agent orchestrator
   - Build system prompt from user profile (name, OS, vocab level, skill history)
   - Claude messages API with tool-use: log_skill_started, flag_emergency
   - Load last 20 messages from DB as conversation history
   - Patient, elderly-appropriate tone in system prompt
   - Stream responses via WebSocket for real-time feel
   - File: server/core/agentOrchestrator.js
 8. Vocabulary filter
   - JSON config with word substitutions (browser→internet, attachment→file in the email, etc.)
   - filterResponse(text, vocabLevel) — applies substitutions
   - Sentence length enforcement: split sentences > 20 words
   - File: server/core/vocabularyFilter.js, server/assets/vocabulary/basicSubstitutions.json
 9. Conversation state
   - getOrCreateSession(userId) — find active session or start new
   - closeSession(sessionId) — mark completed
   - Timeout: abandon sessions inactive > 30 min
   - File: server/core/conversationState.js, server/models/Conversation.js
 10. Safety monitor (basic)
   - Emergency keyword regex: "fallen", "can't breathe", "chest pain", "help me", "911", "emergency"
   - On match: immediate response + log to safety_events
   - Display alert banner in chat UI
   - File: server/core/safetyMonitor.js
 11. Basic tests
   - Test vocabulary filter substitutions
   - Test safety monitor keyword detection
   - Test task classifier with mocked Claude responses
   - Files: server/__tests__/vocabularyFilter.test.js, server/__tests__/safetyMonitor.test.js

 ---
 Phase 2 — v2 by April 21 (Step Sequencer + Visual Guides + Skill Tracking)

 Goal: Multi-turn step-by-step walkthroughs with annotated screenshots displayed in chat.

 Steps:

 1. Step sequencer
   - createSequence(task, userId) — Claude generates numbered steps, stored in step_sequences
   - getCurrentStep(sessionId) — returns step text + "Step X of Y"
   - advanceStep(sessionId) — on user confirmation ("ok", "done", "got it", "next", "yes")
   - isConfirmation(text) — fuzzy match for elderly-friendly confirmations
   - File: server/core/stepSequencer.js
 2. Step UI component
   - StepIndicator.jsx — progress bar showing "Step 2 of 5"
   - Quick-reply buttons: "OK, done!", "I need help", "Go back"
   - File: client/src/components/Chat/StepIndicator.jsx
 3. Agent orchestrator v2 — add tool-use for steps
   - New tools: create_step_sequence, get_current_step, advance_step, send_visual_guide
   - Agent decides when to break a task into steps vs. quick answer
   - Update: server/core/agentOrchestrator.js
 4. Visual guide generator
   - Pre-captured base screenshots for top 10 tasks (Windows 10/11, macOS)
   - Sharp overlay: red circles, arrows, numbered callouts at JSON-defined coordinates
   - Serve annotated images via Express static route /assets/guides/
   - Display in VisualGuide.jsx component in chat
   - Files: server/core/visualGuideGenerator.js, server/assets/screenshots/, client/src/components/Chat/VisualGuide.jsx
 5. Skill tracker
   - logSkill(userId, skillName, status) — write to skill_events
   - getUserSkills(userId) — list all learned skills
   - getSkillsForReinforcement(userId) — skills not practiced in 7+ days
   - File: server/core/skillTracker.js
 6. Scam detection
   - Keyword patterns: gift cards, wire transfer, IRS, lottery, send money, Bitcoin
   - Warn user with prominent alert in chat
   - Update: server/core/safetyMonitor.js
 7. Context compression
   - After 20 messages in a session, call Claude to summarize older messages
   - Store summary in conversations.context_summary
   - Inject summary into system prompt for continuity
   - Update: server/core/conversationState.js
 8. Tests for v2 features
   - Test step sequencer (advancement, confirmation detection, boundary conditions)
   - Test full conversation flow (multi-turn mock)
   - Files: server/__tests__/stepSequencer.test.js, server/__tests__/conversationFlow.test.js

 ---
 Phase 3 — v3 by April 28 (Polish + Scaffolding Fade + Evaluation)

 Goal: Fade scaffolding, accessibility improvements, skill dashboard, deployment.

 Steps:

 1. Scaffolding fade logic
   - If user completed a skill 3+ times, agent offers: "Want to try this on your own first?"
   - On success: positive reinforcement. On failure: resume guided mode
   - Update: server/core/agentOrchestrator.js, server/core/skillTracker.js
 2. Accessibility improvements
   - Theme toggle: high contrast / large text / default
   - Keyboard navigation throughout
   - Larger step counts (more granular) for users with accessibility needs
   - Update: client/src/styles/globals.css, client/src/components/
 3. Skill history sidebar
   - Sidebar.jsx — shows all learned skills with dates and practice count
   - GET /api/users/:id/skills endpoint
   - Files: client/src/components/Layout/Sidebar.jsx, server/routes/skills.js
 4. Proactive messages (in-app)
   - node-cron job checks for skill reinforcement opportunities
   - Sends in-app notification: "Want to practice [skill] today?"
   - File: server/core/proactiveEngine.js
 5. Deployment
   - Build React → static files served by Express
   - Deploy to Railway or Render
   - Environment variables for secrets
   - Update: server/index.js (serve static), README.md
 6. Evaluation prep
   - Pre/post confidence survey component in React
   - Conversation log export endpoint: GET /api/conversations/:id/export
   - Skill completion rate metrics

 ---
 Key Design Decisions

 WebSocket for real-time chat: Streaming Claude responses token-by-token gives a natural chat feel. Fallback REST endpoint for
 reliability.

 SQLite for v1/v2: Zero setup, single file DB. Same query patterns transfer to PostgreSQL for production. better-sqlite3 is synchronous    
 but fast enough for a class project. If async needed, switch to sqlite3 with promises.

 Elderly-friendly UI defaults: 18px+ base font, high-contrast colors, large buttons, minimal navigation. No complex UI patterns — just a   
 chat window and onboarding wizard.

 Context compression at 20 messages: Bounds token cost while maintaining conversation continuity. Claude summarizes older messages into a  
 compact context string.

 Tool-use agent loop: Claude decides when to use tools (create steps, log skills, flag emergencies) rather than hardcoded routing. More    
 flexible and natural conversation flow.

 ---
 Verification Plan

 Local dev

 1. npm install in root and client/
 2. Set .env with ANTHROPIC_API_KEY
 3. npm run dev — starts Express (port 3001) + Vite dev server (port 5173) with proxy
 4. Open http://localhost:5173 in browser

 Automated tests

 - npm test — Jest tests for backend modules
 - Mock Claude API responses with Jest mocks
 - React Testing Library for component tests

 Manual QA checklist per version

 - Onboarding wizard collects name + OS + comfort level
 - Chat message sends and receives response
 - Vocabulary simplification in responses
 - Emergency keyword triggers safety alert
 - (v2) Step-by-step flow with progress bar and confirmation
 - (v2) Annotated screenshot displays in chat
 - (v2) Scam detection warning displays
 - (v3) Skill fade ("try on your own") after 3 completions
 - (v3) Skill history sidebar shows learned skills
 - (v3) Deployed and accessible via public URL