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