# donroy26/icm-foundations-tutor architecture

> Architecture diagram of the GitHub repository donroy26/icm-foundations-tutor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/donroy26/icm-foundations-tutor
- Repository: https://github.com/donroy26/icm-foundations-tutor

## Overview

Foundation Companion offers two learning routes: a hands-on Claude Code tutor workflow and a no-install browser game that simulates building the same 11 lessons before exporting real workspace files. The graph emphasizes the sampled V2 runtime and its lesson, guided-action, quiz, simulated desktop, and workspace stages; it also preserves the documented V1 route. Several modules are represented from README capabilities and tree paths because their source was not sampled, so those connections are limited to documented behavior.

Main entry points: [`v2/js/engine.js`](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/engine.js) (Lesson loop), [`v2/js/main.js`](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/main.js) (Game boot), [`v2/js/vfs.js`](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/vfs.js) (Virtual filesystem), [`_tutor/INSTRUCTIONS.md`](https://github.com/donroy26/icm-foundations-tutor/blob/master/_tutor/INSTRUCTIONS.md) (V1 tutor guidance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning content"]
  node_v1tutor["V1 tutor guidance<br/>[INSTRUCTIONS.md]"]
  node_curriculum["11-lesson curriculum"]
  node_lessoncontent["Lesson content<br/>[content.js]"]
  node_directives["Build directives<br/>[directives.js]"]
end

subgraph group_runtime["Game runtime"]
  node_entry["Browser game entry<br/>[index.html]"]
  node_boot["Game boot<br/>[main.js]"]
  node_engine["Lesson loop<br/>[engine.js]"]
  node_guide["Teaching guide<br/>[guide.js]"]
  node_quiz["Checks and reflection<br/>[quiz.js]"]
  node_claudesim["Claude simulation<br/>[claudesim.js]"]
  node_audio["Audio feedback<br/>[audio.js]"]
end

subgraph group_workspace["Simulated workspace"]
  node_desktop["Desktop windows<br/>[windows.js]"]
  node_vfs[("Virtual filesystem<br/>[vfs.js]")]
end

subgraph group_persistence["Progress and export"]
  node_state[("Save and settings<br/>[state.js]")]
  node_xp["XP and achievements<br/>[xp.js]"]
  node_zip["Workspace download<br/>[zip.js]"]
end

node_learner(("Learner"))
node_browser(("Web browser"))
node_claude(("Claude Code"))

node_learner -->|"follows"| node_v1tutor
node_v1tutor -->|"routes through"| node_curriculum
node_learner -->|"prompts"| node_claude
node_claude -->|"reads project context"| node_curriculum
node_browser -->|"opens"| node_entry
node_entry -->|"loads"| node_boot
node_boot -->|"starts or resumes"| node_engine
node_engine -->|"reads lessons"| node_lessoncontent
node_engine -->|"runs beats"| node_directives
node_engine -->|"shows instruction"| node_guide
node_engine -->|"opens checks"| node_quiz
node_engine -->|"drives build actions"| node_desktop
node_engine -->|"runs scripted prompts"| node_claudesim
node_desktop -->|"reads and writes"| node_vfs
node_claudesim -->|"writes scripted effects"| node_vfs
node_engine -->|"saves progress"| node_state
node_boot -->|"loads save"| node_state
node_engine -->|"awards progress"| node_xp
node_boot -->|"downloads workspace"| node_zip
node_zip -->|"packages files"| node_vfs
node_engine -->|"plays feedback"| node_audio
node_learner -->|"plays lessons"| node_engine

click node_v1tutor "https://github.com/donroy26/icm-foundations-tutor/blob/master/_tutor/INSTRUCTIONS.md"
click node_curriculum "https://github.com/donroy26/icm-foundations-tutor/tree/master/_tutor/curriculum"
click node_lessoncontent "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/data/content.js"
click node_directives "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/data/directives.js"
click node_entry "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/index.html"
click node_boot "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/main.js"
click node_engine "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/engine.js"
click node_guide "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/guide.js"
click node_quiz "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/quiz.js"
click node_claudesim "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/claudesim.js"
click node_desktop "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/windows.js"
click node_vfs "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/vfs.js"
click node_state "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/state.js"
click node_xp "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/xp.js"
click node_zip "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/zip.js"
click node_audio "https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/audio.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v1tutor,node_curriculum,node_lessoncontent,node_directives,node_browser toneBlue
class node_entry,node_boot,node_engine,node_guide,node_quiz,node_claudesim,node_audio toneAmber
class node_desktop,node_vfs toneMint
class node_state,node_xp,node_zip toneRose
class node_learner,node_claude toneIndigo
```

## Components

### Learning content

- [V1 tutor guidance](https://github.com/donroy26/icm-foundations-tutor/blob/master/_tutor/INSTRUCTIONS.md): `_tutor/INSTRUCTIONS.md`
- [11-lesson curriculum](https://github.com/donroy26/icm-foundations-tutor/tree/master/_tutor/curriculum): `_tutor/curriculum`
- [Lesson content](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/data/content.js): `v2/js/data/content.js`
- [Build directives](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/data/directives.js): `v2/js/data/directives.js`

### Game runtime

- [Browser game entry](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/index.html): `v2/index.html`
- [Game boot](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/main.js): `v2/js/main.js`
- [Lesson loop](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/engine.js): `v2/js/engine.js`
- [Teaching guide](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/guide.js): `v2/js/guide.js`
- [Checks and reflection](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/quiz.js): `v2/js/quiz.js`
- [Claude simulation](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/claudesim.js): `v2/js/claudesim.js`
- [Audio feedback](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/audio.js): `v2/js/audio.js`

### Simulated workspace

- [Desktop windows](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/windows.js): `v2/js/windows.js`
- [Virtual filesystem](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/vfs.js): `v2/js/vfs.js`

### Progress and export

- [Save and settings](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/state.js): `v2/js/state.js`
- [XP and achievements](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/xp.js): `v2/js/xp.js`
- [Workspace download](https://github.com/donroy26/icm-foundations-tutor/blob/master/v2/js/zip.js): `v2/js/zip.js`

### Other components

- **Learner**
- **Web browser**
- **Claude Code**

## Connections

- Learner → V1 tutor guidance: follows
- V1 tutor guidance → 11-lesson curriculum: routes through
- Learner → Claude Code: prompts
- Claude Code → 11-lesson curriculum: reads project context
- Web browser → Browser game entry: opens
- Browser game entry → Game boot: loads
- Game boot → Lesson loop: starts or resumes
- Lesson loop → Lesson content: reads lessons
- Lesson loop → Build directives: runs beats
- Lesson loop → Teaching guide: shows instruction
- Lesson loop → Checks and reflection: opens checks
- Lesson loop → Desktop windows: drives build actions
- Lesson loop → Claude simulation: runs scripted prompts
- Desktop windows → Virtual filesystem: reads and writes
- Claude simulation → Virtual filesystem: writes scripted effects
- Lesson loop → Save and settings: saves progress
- Game boot → Save and settings: loads save
- Lesson loop → XP and achievements: awards progress
- Game boot → Workspace download: downloads workspace
- Workspace download → Virtual filesystem: packages files
- Lesson loop → Audio feedback: plays feedback
- Learner → Lesson loop: plays lessons