IPrep Chatbot

A multi-tutor talking chatbot app that helps improve English communication and prepare for interviews using Claude Code subscription (not API).

Built similar to Paperclip's multi-company architecture, with complete tutor isolation:

• Each tutor has its own personality, skills, settings, and conversation history
• Upload documents (PDF, DOCX, XLSX, etc.) that are converted to markdown and stored per-tutor
• Use CLI commands to manage tutors, documents, conversations
• Beautiful React web UI for real-time chat
• All data stored locally, zero API costs

🎯 Features

Chat & Conversations

• 💬 Real-time chat with multiple AI tutors
• 📚 Persistent conversation history (per tutor)
• 🔄 Switch between tutors instantly
• 📤 Export conversations (Markdown, PDF, JSON)

Multi-Tutor System

• 🎓 English Coach — Grammar, fluency, communication
• 📝 Interview Prep — Practice interviews, techniques
• 💼 Client Communication — Professional interaction
• ➕ Create custom tutors with unique personalities

Document Management

• 📄 Upload documents (PDF, DOCX, XLSX, CSV, TXT, MD)
• 🔄 Auto-convert to markdown using markitdown
• 📁 Documents stored per-tutor (isolated)
• 💾 Export documents in multiple formats
• 🔍 Reference documents in chat

CLI Commands

• interview-prep start — Start server + open UI
• interview-prep create-tutor — Create new tutor
• interview-prep upload-doc — Upload document
• interview-prep export-chat — Export conversation
• interview-prep backup — Backup all data
• ...and 20+ more commands

Architecture

• ✅ Subscription-based — Uses Claude Code CLI (not API, no token costs)
• ✅ Multi-tenant — Complete isolation per tutor
• ✅ Local-first — Everything runs on your machine
• ✅ CLI-first — Run from terminal, optional web UI

🚀 Quick Start

Prerequisites

# Install Node.js 18+
node --version

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Authenticate (one-time)
claude /login

Installation

# Clone repository
git clone <repo-url>
cd interview-prep

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Initialize (first-time setup)
npm run cli init

# Start the app
npm start

Browser opens: http://localhost:3000

📖 Documentation

| File | Purpose | | ------------------------ | ------------------------------------------------------------------------------------- | | CLAUDE.md | Project vision, decisions, architecture overview | | FEATURES.md | Complete feature list with table of contents | | PROJECT_STRUCTURE.md | Full directory layout and organization | | CLI_REFERENCE.md | All CLI commands with examples | | 01-plan.md | Technical specification (process adapter, session manager) | | docs/ | Detailed architecture docs (CLI design, multi-tenant approach, subscription strategy) |

Start reading here:

1. CLAUDE.md — Understand the vision (5 min)
2. FEATURES.md — See what you're building (15 min)
3. CLI_REFERENCE.md — Learn the commands (10 min)

🏗️ Architecture

┌─────────────────────────────────────────┐
│         Web UI (React)                   │
│   http://localhost:3000                  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│    Express Server (localhost:3000)       │
│   • REST API endpoints                   │
│   • Session management                   │
│   • Document conversion                  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│     Tutor Manager                        │
│   • Load MD-based configs                │
│   • Inject system prompts                │
│   • Switch contexts                      │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  Claude Process Adapter                  │
│   • Spawn child processes                │
│   • stdin/stdout communication           │
│   • Session continuity                   │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│  Claude Code CLI (Your Subscription)     │
│   • $20/month subscription               │
│   • Unlimited usage, zero API costs      │
└─────────────────────────────────────────┘

📂 Project Structure

interview-prep/
├── CLAUDE.md                    # Vision & decisions
├── FEATURES.md                  # Feature list
├── CLI_REFERENCE.md             # Command reference
├── PROJECT_STRUCTURE.md         # Directory layout
├── package.json                 # Dependencies
├── .env.example                 # Environment template
│
├── src/                         # Backend code
│   ├── cli.js                   # CLI entry point
│   ├── server.js                # Express setup
│   ├── cli/commands/            # All CLI commands
│   ├── managers/                # Business logic
│   ├── adapters/                # Claude adapter
│   ├── routes/                  # API endpoints
│   ├── services/                # Utilities
│   └── database/                # SQLite setup
│
├── tutors/                      # Tutor configs
│   ├── english-coach/           # Example tutor
│   │   ├── settings.md
│   │   ├── skills.md
│   │   ├── system-prompt.md
│   │   └── documents/           # User uploads
│   │       ├── originals/       # Original files
│   │       ├── markdown/        # Converted MD
│   │       └── metadata.json    # Document index
│   ├── interview-prep/
│   ├── client-communication/
│   └── ...
│
├── frontend/                    # React UI
│   ├── src/
│   │   ├── components/          # React components
│   │   ├── hooks/               # Custom hooks
│   │   ├── context/             # State management
│   │   └── styles/
│   └── index.html
│
├── database/                    # SQLite (generated)
│   └── chatbot.db
│
├── logs/                        # App logs
│   ├── app.log
│   └── errors.log
│
└── backups/                     # Backup files

🎮 Usage Examples

Start the App

npm start

# Or with custom port
npm start -- --port 4000

# Development mode (hot reload)
npm run dev

Create a Tutor

npm run cli create-tutor

# Interactive setup:
# ? Tutor name: coding-coach
# ? Description: Helps with coding interviews
# ? Personality: friendly

Upload Documents

# Upload to English Coach
npm run cli upload-doc english-coach ~/resume.pdf

# Upload to Interview Prep
npm run cli upload-doc interview-prep ~/interview-notes.docx

# Batch upload
npm run cli upload-doc english-coach ~/file1.pdf ~/file2.docx

Export Conversation

# List conversations
npm run cli list-chats english-coach

# Export as markdown
npm run cli export-chat conv_123 markdown

# Export as PDF
npm run cli export-chat conv_123 pdf

Backup Everything

# Create backup
npm run cli backup

# Restore from backup
npm run cli restore ./interview-prep_backup_2026-04-11.zip

🔧 Development

Setup Development Environment

# Install dependencies
npm install

# Backend development (Node)
npm run dev

# Frontend development (React)
npm run dev:frontend

# Both in parallel (in separate terminals)
terminal 1: npm run dev
terminal 2: npm run dev:frontend

Running Tests

npm test

# Watch mode
npm test -- --watch

Code Quality

# Lint
npm run lint

# Format code
npm run format

📦 Tech Stack

| Layer | Technology | | ------------- | ------------------------------ | | CLI | Node.js + Commander.js + Chalk | | Server | Express.js | | Process | child_process.spawn() | | Database | SQLite + better-sqlite3 | | Documents | markitdown (Microsoft) | | Frontend | React 18 + Vite | | State | React Context API | | Styling | CSS3 + Responsive |

🔐 Security & Privacy

• ✅ No cloud dependency — Everything runs locally
• ✅ No API keys — Uses your Claude subscription
• ✅ All data local — Conversations stored in SQLite on your machine
• ✅ Documents isolated — Per-tutor storage, no cross-tutor access

📊 System Requirements

• Node.js 18.0.0 or higher
• Claude Code (installed globally: npm install -g @anthropic-ai/claude-code)
• Claude subscription (Claude Pro or Beta access)
• Disk space ~50 MB minimum (more for documents)
• OS — Windows, macOS, Linux

🐛 Troubleshooting

Claude Code not found

npm install -g @anthropic-ai/claude-code
claude /login
interview-prep health

Port already in use

npm start -- --port 4000

Database errors

npm run cli stop
rm database/chatbot.db
npm start

See CLI_REFERENCE.md for more troubleshooting tips.

🚦 Implementation Status

Phase 1: Core Infrastructure (In Progress)

• [ ] CLI setup and basic commands
• [ ] Claude process adapter
• [ ] Express server
• [ ] Database schema

Phase 2: Multi-Tutor & Documents

• [ ] Tutor management
• [ ] Document upload and conversion
• [ ] Document storage (per-tutor)

Phase 3: Frontend

• [ ] React UI
• [ ] Chat interface
• [ ] Tutor selector

Phase 4: Advanced Features

• [ ] Export (PDF, JSON)
• [ ] Backup/restore
• [ ] Analytics (future)

📝 License

MIT

🤝 Contributing

Contributions welcome! Please read our contributing guidelines.

📧 Support

• Docs — See docs/ folder
• CLI Help — interview-prep help [command]
• Issues — GitHub issues
• Discussions — GitHub discussions

🎯 Roadmap

Phase 1 (Current)

• ✅ Multi-tutor architecture
• ✅ CLI commands
• ✅ Document management
• ✅ Web UI

Phase 2

• 🔄 Voice input/output
• 🔄 User authentication
• 🔄 Analytics dashboard

Phase 3

• 🔄 Tutor creation UI
• 🔄 Mobile app
• 🔄 Cloud sync (optional)
• 🔄 Tutor marketplace

Last Updated: 2026-04-11

Questions? Read the documentation:

• What to build? → FEATURES.md
• How to run? → CLI_REFERENCE.md
• Architecture? → CLAUDE.md + docs/