# 1975sg/stdio-noob architecture

> Architecture diagram of the GitHub repository 1975sg/stdio-noob, 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/1975sg/stdio-noob
- Repository: https://github.com/1975sg/stdio-noob

## Overview

stdio::noob is an Electron learning environment pairing a real terminal in an Alpine/QEMU guest with an AI tutor that guides but does not edit the learner’s work. The main journey is: start or resume a session, review syllabus progress, receive one-step guidance, run commands in the guest, and preserve progress for the next session. The documented curriculum spans sandboxing and Linux isolation through a from-scratch assembler/compiler bootstrap to a self-hosting GNU toolchain. The graph reflects documented capabilities; unsampled curriculum content is represented by its enclosing directory.

Main entry points: [`app/electron/main.js`](https://github.com/1975sg/stdio-noob/blob/main/app/electron/main.js) (Electron app), [`app/electron/preload.js`](https://github.com/1975sg/stdio-noob/blob/main/app/electron/preload.js) (PTY bridge), [`app/electron/session.js`](https://github.com/1975sg/stdio-noob/blob/main/app/electron/session.js) (Session coordinator), [`app/electron/state.js`](https://github.com/1975sg/stdio-noob/blob/main/app/electron/state.js) (Greeting and state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_electron["Electron app<br/>[main.js]"]
  node_terminal["Terminal pane<br/>[index.html]"]
  node_pty["PTY bridge<br/>[preload.js]"]
  node_tutorview["Tutor pane<br/>[main.js]"]
end

subgraph group_learning["Course guidance"]
  node_tutor["Prompt injection<br/>[tutor.js]"]
  node_prompt["Course rules"]
  node_syllabus["Course syllabus"]
  node_parser["Syllabus loader<br/>[parse.js]"]
  node_bootstrap["Bootstrap materials"]
end

subgraph group_guest["Guest session"]
  node_session["Session coordinator<br/>[session.js]"]
  node_vm["Guest launcher<br/>[vm.js]"]
  node_qemu["QEMU guest"]
  node_guestfs["SSH file access<br/>[guest-fs.js]"]
end

subgraph group_progress["Learner progress"]
  node_state["Greeting and state<br/>[state.js]"]
  node_memory["Learner memory"]
end

node_learner(("Learner"))
node_claude["Claude chat"]

node_learner -->|"starts session"| node_electron
node_learner -->|"types commands"| node_terminal
node_electron -->|"loads UI"| node_terminal
node_terminal -->|"sends input"| node_pty
node_pty -->|"forwards IPC"| node_electron
node_electron -->|"sends terminal data"| node_pty
node_electron -->|"loads tutor"| node_tutorview
node_tutorview -->|"opens chat"| node_claude
node_electron -->|"requests injection"| node_tutor
node_tutor -->|"builds prompt"| node_prompt
node_tutor -->|"inserts and sends"| node_tutorview
node_prompt -->|"references stages"| node_syllabus
node_prompt -->|"references progress"| node_memory
node_learner -->|"receives guidance"| node_claude
node_electron -->|"starts real session"| node_session
node_session -->|"launches guest"| node_vm
node_vm -->|"spawns guest"| node_qemu
node_qemu -->|"streams terminal"| node_pty
node_session -->|"reads and seeds files"| node_guestfs
node_guestfs -->|"transfers files over SSH"| node_qemu
node_session -->|"builds greeting"| node_state
node_state -->|"loads syllabus"| node_parser
node_parser -->|"parses milestones"| node_syllabus
node_state -->|"reads progress"| node_memory
node_state -->|"prints greeting"| node_pty
node_bootstrap -->|"supports hands-on stages"| node_learner

click node_electron "https://github.com/1975sg/stdio-noob/blob/main/app/electron/main.js"
click node_terminal "https://github.com/1975sg/stdio-noob/blob/main/app/electron/index.html"
click node_pty "https://github.com/1975sg/stdio-noob/blob/main/app/electron/preload.js"
click node_tutorview "https://github.com/1975sg/stdio-noob/blob/main/app/electron/main.js"
click node_tutor "https://github.com/1975sg/stdio-noob/blob/main/app/electron/tutor.js"
click node_prompt "https://github.com/1975sg/stdio-noob/blob/main/app/electron/curriculum-prompt.js"
click node_syllabus "https://github.com/1975sg/stdio-noob/tree/main/app/syllabus"
click node_parser "https://github.com/1975sg/stdio-noob/blob/main/app/syllabus/parse.js"
click node_bootstrap "https://github.com/1975sg/stdio-noob/tree/main/app/syllabus/assets/stage0"
click node_session "https://github.com/1975sg/stdio-noob/blob/main/app/electron/session.js"
click node_vm "https://github.com/1975sg/stdio-noob/blob/main/app/electron/vm.js"
click node_guestfs "https://github.com/1975sg/stdio-noob/blob/main/app/electron/guest-fs.js"
click node_state "https://github.com/1975sg/stdio-noob/blob/main/app/electron/state.js"
click node_memory "https://github.com/1975sg/stdio-noob/tree/main/noob-file-schema"

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_electron,node_terminal,node_pty,node_tutorview toneBlue
class node_tutor,node_prompt,node_syllabus,node_parser,node_bootstrap toneAmber
class node_session,node_vm,node_qemu,node_guestfs toneMint
class node_state,node_memory toneRose
class node_learner,node_claude toneIndigo
```

## Components

### App shell

- [Electron app](https://github.com/1975sg/stdio-noob/blob/main/app/electron/main.js): `app/electron/main.js`
- [Terminal pane](https://github.com/1975sg/stdio-noob/blob/main/app/electron/index.html): `app/electron/index.html`
- [PTY bridge](https://github.com/1975sg/stdio-noob/blob/main/app/electron/preload.js): `app/electron/preload.js`
- [Tutor pane](https://github.com/1975sg/stdio-noob/blob/main/app/electron/main.js): `app/electron/main.js`

### Course guidance

- [Prompt injection](https://github.com/1975sg/stdio-noob/blob/main/app/electron/tutor.js): `app/electron/tutor.js`
- [Course rules](https://github.com/1975sg/stdio-noob/blob/main/app/electron/curriculum-prompt.js): `app/electron/curriculum-prompt.js`
- [Course syllabus](https://github.com/1975sg/stdio-noob/tree/main/app/syllabus): `app/syllabus`
- [Syllabus loader](https://github.com/1975sg/stdio-noob/blob/main/app/syllabus/parse.js): `app/syllabus/parse.js`
- [Bootstrap materials](https://github.com/1975sg/stdio-noob/tree/main/app/syllabus/assets/stage0): `app/syllabus/assets/stage0`

### Guest session

- [Session coordinator](https://github.com/1975sg/stdio-noob/blob/main/app/electron/session.js): `app/electron/session.js`
- [Guest launcher](https://github.com/1975sg/stdio-noob/blob/main/app/electron/vm.js): `app/electron/vm.js`
- **QEMU guest**
- [SSH file access](https://github.com/1975sg/stdio-noob/blob/main/app/electron/guest-fs.js): `app/electron/guest-fs.js`

### Learner progress

- [Greeting and state](https://github.com/1975sg/stdio-noob/blob/main/app/electron/state.js): `app/electron/state.js`
- [Learner memory](https://github.com/1975sg/stdio-noob/tree/main/noob-file-schema): `noob-file-schema`

### Other components

- **Learner**
- **Claude chat**

## Connections

- Learner → Electron app: starts session
- Learner → Terminal pane: types commands
- Electron app → Terminal pane: loads UI
- Terminal pane → PTY bridge: sends input
- PTY bridge → Electron app: forwards IPC
- Electron app → PTY bridge: sends terminal data
- Electron app → Tutor pane: loads tutor
- Tutor pane → Claude chat: opens chat
- Electron app → Prompt injection: requests injection
- Prompt injection → Course rules: builds prompt
- Prompt injection → Tutor pane: inserts and sends
- Course rules → Course syllabus: references stages
- Course rules → Learner memory: references progress
- Learner → Claude chat: receives guidance
- Electron app → Session coordinator: starts real session
- Session coordinator → Guest launcher: launches guest
- Guest launcher → QEMU guest: spawns guest
- QEMU guest → PTY bridge: streams terminal
- Session coordinator → SSH file access: reads and seeds files
- SSH file access → QEMU guest: transfers files over SSH
- Session coordinator → Greeting and state: builds greeting
- Greeting and state → Syllabus loader: loads syllabus
- Syllabus loader → Course syllabus: parses milestones
- Greeting and state → Learner memory: reads progress
- Greeting and state → PTY bridge: prints greeting
- Bootstrap materials → Learner: supports hands-on stages