# Vibe Coding Instructor - Technical Planning

## Technology Stack

### Frontend Framework
- **React** with TypeScript for the main interface
- **Vite** for fast development and bundling
- **Tailwind CSS** for styling and responsive design

### P5.js Integration
- **p5.js** for creative coding canvas
- **@p5-wrapper/react** for React integration
- **Monaco Editor** (VS Code editor) for code editing with syntax highlighting

### Local LLM Integration
- **Transformers.js** for running models in browser
- **ONNX.js** as fallback for model inference
- Consider **Ollama** with local API for development/testing

### State Management & Data
- **Zustand** for lightweight state management
- **IndexedDB** (via Dexie.js) for local data persistence
- **Immer** for immutable updates to learner progress

### Development Tools
- **TypeScript** for type safety
- **ESLint + Prettier** for code quality
- **Vitest** for unit testing
- **Playwright** for E2E testing

## System Architecture

### 1. Ontology System
```
/src/ontology/
├── concepts/           # P5.js concept definitions
├── learning-paths/     # Structured learning progressions
├── assessment/         # Progress tracking logic
└── constraints/        # Code complexity validators
```

**Key Components:**
- `ConceptGraph`: Dependency relationships between coding concepts
- `LearnerProfile`: Current understanding level and progress
- `ComplexityAnalyzer`: Validates generated code against learner level

### 2. Code Generation & Verification System
```
/src/code-generation/
├── prompts/           # LLM prompt templates
├── validation/        # Code complexity verification
├── explanation/       # Diff annotation generation
└── sandbox/          # Safe code execution environment
```

**Key Components:**
- `CodeGenerator`: LLM interface with context-aware prompting
- `ComplexityValidator`: Ensures code stays within learner bounds
- `DiffExplainer`: Generates educational annotations for code changes
- `SafeRunner`: Sandboxed P5.js execution environment

### 3. Browser Interface System
```
/src/interface/
├── editor/            # Monaco-based code editor
├── chat/             # LLM conversation interface
├── canvas/           # P5.js rendering area
├── diff-viewer/      # Interactive code change display
└── progress/         # Learning progress visualization
```

**Key Components:**
- `CodeEditor`: Monaco editor with P5.js intellisense
- `ChatInterface`: Conversation UI with message history
- `P5Canvas`: React wrapper for P5.js sketches
- `InteractiveDiff`: Clickable diff annotations
- `ProgressDashboard`: Visual learning progress tracker

## Development Phases

### Phase 1: Foundation (Week 1-2)
**Goal**: Basic React app with P5.js integration
- Set up Vite + React + TypeScript project
- Integrate P5.js with React wrapper
- Create basic three-panel layout (editor, chat, canvas)
- Implement simple code execution pipeline

**Deliverable**: Working P5.js code editor that can run sketches

### Phase 2: Ontology Core (Week 3-4)
**Goal**: Learning progression system
- Define initial P5.js concept ontology (shapes, colors, animation)
- Implement learner profile with progress tracking
- Create complexity analysis for basic P5.js constructs
- Build concept dependency graph

**Deliverable**: System that tracks which P5.js concepts learner knows

### Phase 3: LLM Integration (Week 5-6)
**Goal**: Code generation with constraints
- Integrate local LLM (start with simple model)
- Implement context-aware prompt generation
- Build code validation against learner level
- Create feedback loop for constraint violations

**Deliverable**: LLM that generates appropriate P5.js code for learner level

### Phase 4: Interactive Learning (Week 7-8)
**Goal**: Educational diff system
- Implement diff visualization with annotations
- Build explanation generation for code changes
- Add partial diff application capability
- Create interactive learning flow

**Deliverable**: Complete learning interface with guided code evolution

## Quick Iteration Strategy

### MVP Approach
1. **Start Simple**: Basic shapes and colors only (rect, ellipse, fill, stroke)
2. **Manual Ontology**: Hard-code initial concept relationships
3. **Mock LLM**: Use predefined responses for early testing
4. **Static Explanations**: Template-based diff annotations

### Rapid Prototyping Tools
- **Storybook** for component development
- **JSON Server** for mock API responses
- **Hot reloading** for instant feedback
- **Feature flags** for experimental features

### Testing Strategy
- **Unit tests** for ontology logic and validation
- **Integration tests** for LLM-code generation pipeline
- **User testing** with real learners early and often
- **A/B testing** for different explanation approaches

## Key Libraries & Dependencies

### Core Dependencies
```json
{
  "react": "^18.2.0",
  "typescript": "^5.0.0",
  "p5": "^1.7.0",
  "@p5-wrapper/react": "^4.3.0",
  "@monaco-editor/react": "^4.6.0",
  "zustand": "^4.4.0",
  "dexie": "^3.2.0",
  "@xenova/transformers": "^2.6.0"
}
```

### Development Dependencies
```json
{
  "vite": "^4.4.0",
  "vitest": "^0.34.0",
  "tailwindcss": "^3.3.0",
  "eslint": "^8.47.0",
  "prettier": "^3.0.0",
  "@storybook/react": "^7.4.0"
}
```

## Risk Mitigation

### Technical Risks
- **Local LLM Performance**: Start with cloud API, migrate to local gradually
- **P5.js Complexity**: Begin with subset of API, expand incrementally
- **Browser Storage Limits**: Implement data compression and cleanup

### Learning Design Risks
- **Overwhelming Complexity**: Very conservative initial concept set
- **Engagement**: Early user testing to validate learning flow
- **Progress Stagnation**: Multiple learning paths and difficulty levels

## Success Metrics

### Technical Metrics
- Code generation latency < 2 seconds
- Diff explanation accuracy > 90%
- Local model runs on average laptop
- Zero security vulnerabilities in sandbox

### Learning Metrics
- Learner progression through concept ontology
- Time to first successful code modification
- Retention rate after first session
- Concept understanding assessment scores