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