System Architecture Diagrams (Definitive)
Diagram 1: Tripartite System Architecture
graph TD
A("THE STUDENT
(Human Learner/User)")
subgraph SM [STUDENT MODEL - Persistent]
B["- Concepts
- Mastery levels
- Confidence
- Struggles
- Breakthroughs
- Prerequisites
Type: ABSTRACT / CONCEPTUAL
Tool: student.py / JSON"]
end
subgraph WP [WORKSPACE PROTOCOL - Ephemeral]
C["- File contents
- Grep results
- Directory structure
- Git history
- Command outputs
Type: CONCRETE / CODE EVIDENCE
Tools: cat, grep, find, ls, git"]
end
D{"CLAUDE
(LLM Synthesis)"}
E("GROUNDED, CONTINUOUS
ADAPTIVE TUTORING")
A -->|Updates & Queries| SM
A -->|Investigates & Shares| WP
SM -->|Provides context| D
WP -->|Provides evidence| D
D --> E
style A fill:#000000,stroke:#58a6ff,stroke-width:3px,color:#ffffff
style SM fill:#222222,stroke:#8b949e,stroke-width:2px,stroke-dasharray: 5 5,color:#ffffff
style WP fill:#222222,stroke:#8b949e,stroke-width:2px,stroke-dasharray: 5 5,color:#ffffff
style D fill:#000000,stroke:#3fb950,stroke-width:3px,color:#ffffff
style E fill:#000000,stroke:#db61a2,stroke-width:3px,color:#ffffff
Figure 1: The tripartite system architecture. The Student Model provides persistent conceptual memory across all projects and sessions. The Workspace Protocol provides ephemeral concrete evidence from the current codebase. Claude synthesizes both contexts to deliver grounded, continuous tutoring. The student maintains full control over both information flows.
Diagram 2: Mandatory Two-Phase Protocol
sequenceDiagram
actor Student
actor Claude
rect rgb(20, 30, 45)
Note over Student, Claude: Phase 1: CONCEPTUAL CONTEXT (Student Model)
Student->>Claude: "I want to learn React Context API"
Claude-->>Student: REFUSES to teach until context loaded
Claude-->>Student: "Please run:
`student.py show 'React Context API'`
`student.py related 'React Context API'`"
Student->>Claude: [Runs commands, pastes output]
Note right of Claude: NOW HAS:
• Mastery: 45%
• Struggles logged
• Prerequisites known
end
rect rgb(45, 40, 20)
Note over Student, Claude: Phase 2: CONCRETE CONTEXT (Workspace Protocol)
Claude-->>Student: "What file are you confused about?"
Student->>Claude: "TestArea.tsx component"
Claude-->>Student: REQUESTS evidence (never assumes)
Claude-->>Student: "Run:
`cat packages/.../TestArea.tsx`"
Student->>Claude: [Runs command, pastes output]
Note right of Claude: NOW HAS:
• Actual file contents
• Line numbers
• Specific code pattern
end
rect rgb(20, 45, 30)
Note over Student, Claude: Phase 3: SYNTHESIS & INVESTIGATION
Claude-->>Student: "Your model shows you struggled with provider pattern.
Line 50 of TestArea.tsx is exactly that pattern..."
Claude-->>Student: Socratic question:
"What do you think useContext returns?"
Student->>Claude: "The theme object?"
Claude-->>Student: "Let's verify. Run:
`grep -r 'ThemeContext' src/`"
Note over Student, Claude: [Investigation continues...]
end
Figure 2: The mandatory two-phase protocol for session initialization. Claude refuses to teach until both conceptual context (Student Model) and concrete context (Workspace evidence) are loaded. This prevents both AI amnesia (teaching without memory) and assumption-based tutoring (teaching without evidence). The synthesis phase connects abstract struggles to specific code patterns.
Diagram 3: Separation of Concerns
graph TB
subgraph SM ["STUDENT MODEL (student.py)"]
direction TB
B1["WHAT IT TRACKS:
Abstract concepts
Self-assessed mastery
Subjective confidence
Logged struggles
Prerequisite graph"]
B2["CHARACTERISTICS:
Persistent across sessions
Portable across projects
Manually maintained
Simple JSON schema
Slow-changing"]
B3["DOES NOT:
Parse code
Track specific files
Store code snippets"]
B1 --- B2 --- B3
end
subgraph WP ["WORKSPACE PROTOCOL (Unix Tools)"]
direction TB
C1["WHAT IT PROVIDES:
Concrete file contents
Search results (grep)
Directory structure (ls)
Historical context (git)
Runtime output"]
C2["CHARACTERISTICS:
Ephemeral/session-specific
Project-specific
Always current
No custom tools
Fast-changing"]
C3["DOES NOT:
Store anything
Maintain state
Track concepts
Assess mastery"]
C1 --- C2 --- C3
end
subgraph CL ["CLAUDE (Integration Layer)"]
D["Bridges ABSTRACT to CONCRETE
Your logged struggle with provider pattern
maps to this code on line 50"]
end
SM -.->|Provides context| CL
WP -.->|Provides evidence| CL
style SM fill:#102030,stroke:#58a6ff,stroke-width:3px,color:#ffffff
style WP fill:#103020,stroke:#3fb950,stroke-width:3px,color:#ffffff
style CL fill:#302010,stroke:#f0a639,stroke-width:3px,color:#ffffff
style B1 fill:#152535,stroke:#58a6ff,stroke-width:2px,color:#ffffff
style B2 fill:#152535,stroke:#58a6ff,stroke-width:2px,color:#ffffff
style B3 fill:#152535,stroke:#58a6ff,stroke-width:2px,color:#ffffff
style C1 fill:#153525,stroke:#3fb950,stroke-width:2px,color:#ffffff
style C2 fill:#153525,stroke:#3fb950,stroke-width:2px,color:#ffffff
style C3 fill:#153525,stroke:#3fb950,stroke-width:2px,color:#ffffff
style D fill:#352515,stroke:#f0a639,stroke-width:2px,color:#ffffff
Figure 3: Separation of concerns between Student Model and Workspace Protocol. The Student Model tracks persistent conceptual knowledge that follows the learner across all projects and time. The Workspace Protocol provides ephemeral concrete evidence from the current project session. This architectural boundary enables both continuity (persistent model) and grounding (current code) without requiring complex integration or custom code parsing tools.
Diagram 4: Evidence-Based Investigation Loop
sequenceDiagram
actor Claude
actor Student
loop Iteration N
Claude->>Student: 1. REQUEST with rationale
"To understand X, let's find Y. Run: `grep -r 'pattern' src/`"
Student-->>Student: 2. EXECUTE command
Student->>Claude: 3. PROVIDE exact output
[Pastes grep results]
Note over Claude: 4. ANALYZE evidence
• Acknowledge what's seen
• Point out relevant parts
• Connect to Student Model
par Option A: Socratic Question
Claude->>Student: 5a. "What do you think happens on line 50?"
and Option B: Next Request
Claude->>Student: 5b. "Let's see that file: `cat src/components/TestArea.tsx`"
end
end
Note over Claude, Student: Process repeats in Iteration N+1
Figure 4: The evidence-based investigation loop. Claude requests concrete evidence with clear rationale, analyzes the output, then either asks Socratic questions or requests additional evidence. This tight feedback loop prevents assumptions, maintains focus, and models investigation methodology for the learner. The cycle repeats until sufficient context is gathered for grounded explanation.
Diagram 5: Session Timeline
sequenceDiagram
participant Time
participant Phase
participant Student
participant Claude
Note over Time,Claude: 0:00 - SESSION START
rect rgb(20, 30, 45)
Note over Time,Claude: 0:01 - Phase 1: Conceptual Context
Student->>Student: Run: python student.py show
Run: python student.py related
Student->>Claude: Paste output
Note right of Claude: Parse context:
• Mastery: 45%
• Struggles noted
• Prerequisites: 55%
end
rect rgb(45, 40, 20)
Note over Time,Claude: 0:02 - Phase 2: Workspace Context
Student->>Claude: Mention confusing file
Claude->>Student: Request workspace evidence
Student->>Student: Run: cat path/to/file
Student->>Claude: Paste output
Note right of Claude: Receive concrete code
end
rect rgb(20, 45, 30)
Note over Time,Claude: 0:03-0:30 - Phase 3: Investigation Loop
Claude->>Student: Ask Socratic questions
Student->>Claude: Answer questions
Claude->>Student: Request more evidence
Student->>Student: Run: grep ...
Student->>Claude: Paste output
Note right of Claude: Analyze
Bridge abstract ←→ concrete
Student->>Claude: Explain confusion
Claude->>Student: Request: cat other-file
Student->>Claude: Paste output
Student->>Claude: "OH! I get it now"
Note right of Claude: Validate insight
end
rect rgb(60, 30, 30)
Note over Time,Claude: 0:31 - Phase 4: Session End
Student->>Claude: Signal end: "Let's stop here"
Note right of Claude: Summarize learning
Claude->>Student: Generate commands:
python student.py update ...
python student.py breakthrough ...
python student.py struggle ...
end
rect rgb(60, 60, 60)
Note over Time,Claude: 0:33-0:35 - Model Update
Student->>Student: Copy-paste commands
Execute updates
Student->>Student: Verify: python student.py show
Note over Time,Claude: [Session complete]
end
Figure 5: Complete session timeline showing temporal flow of a typical 35-minute learning session. Student Model overhead (~2 minutes) occurs at start and end. Workspace commands blend into natural investigation workflow. Total overhead remains under 5% while providing both continuity (Student Model) and grounding (Workspace evidence). The session structure scaffolds metacognitive reflection while maintaining focus on concrete code exploration.