# hpglcrm-afk/the-last-compiler architecture

> Architecture diagram of the GitHub repository hpglcrm-afk/the-last-compiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hpglcrm-afk/the-last-compiler
- Repository: https://github.com/hpglcrm-afk/the-last-compiler

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **single-page, fully self-contained, offline-capable web game** (pure **HTML/CSS/JavaScript**, no frameworks) intended to teach computational thinking via narrative-driven interactions. Architecturally, it’s not “frontend + backend”; it’s a **standalone client runtime** delivered as static files (in this repo: effectively **one entrypoint**).

- **Runtime components inside the browser** (UI, game state, story/progression logic, puzzle/learning modules)
- **Persistence** (if present: LocalStorage/IndexedDB; if not present, show “in-memory only” explicitly)
- **Optional external interactions** (likely none; emphasize offline)

##### File structure analysis (what the tree implies)
File tree:
- `index.html` — the entire app: markup + styles + scripts (per README “single file, fully self-contained”)
- `README.md` — product/stack description
- `GAME-DESIGN.md` — design spec / narrative mechanics (this is key for identifying “modules” even if code is all in one file)

##### Extract architecture hints from README
Key constraints:
- **No frameworks**
- **Offline**
- **Mobile-friendly**
- **Single file**
This implies:
- All code executes in **Browser JS runtime**
- No server APIs by default
- Any “save/progress” likely uses **Web Storage** or is ephemeral

##### Game Engine / Orchestrator (Core JS)
- Main loop or event dispatcher
- Screen/state router (e.g., intro → chapter → puzzle → result)
- Timing/animation handlers (requestAnimationFrame, setTimeout)

##### Narrative & Content Model
- Story nodes, dialogues, chapters
- ARIA/KAI state, world restoration milestones
- Content data representation (JSON-like objects, arrays, hardcoded constants)

##### Learning/Puzzle Modules
To the README’s concept list:
- Variables module
- Loops module
- Conditionals module
- Functions module
- Arrays module
- Objects module
- Recursion module
Each module likely has:
- Puzzle definition (inputs/expected)
- Validation/evaluation logic
- Hints/teaching scaffolding

##### State Management
- Current scene/chapter
- Player progress
- Puzzle completion flags
- Player decisions/branching variables
This as a “GameState” component that others read/write.

##### Persistence (Offline Save)
- If implemented: `localStorage` (common for single-file offline)
- Possibly: `IndexedDB` for richer saves
- If absent: explicitly show **No persistence (session only)**

##### Platform/Runtime Dependencies
- Browser DOM API
- Web Storage API
- Audio API (if sound exists)
- Touch input vs mouse/keyboard

- **User → UI Layer**
- taps/clicks/keyboard input

- **UI Layer → Game Engine**
- event handlers call engine actions (e.g., `onChoiceSelected`, `startPuzzle`, `advanceDialogue`)

- **Game Engine ↔ GameState**
- engine updates state; state drives what to render

- **Game Engine → Narrative Model**
- fetch next node/branch based on state

- **Game Engine → Puzzle Modules**
- start module; provide inputs; receive pass/fail + feedback

- **Puzzle Modules → GameState**
- write completion, unlock next story parts

- **GameState ↔ Persistence**
- load at startup; save after important transitions

- **UI Layer ← Game Engine**
- engine triggers “render”/DOM update with current view model

##### Architectural patterns/design principles
For accuracy, call out the pattern you observe in `index.html`:
- Likely **event-driven state machine** (common for narrative games)
- A **model-driven narrative graph** (nodes/edges) if branching exists
- **Module pattern** (functions grouped by concern)
- Separation between:
- content (story/puzzles data)
- engine (rules/flow)
- presentation (DOM/CSS)

##### Relevant technologies
- “Pure HTML/CSS/JS”
- “DOM rendering”
- “Offline (no network)”
- “localStorage” (if present)
- “Mobile-friendly (responsive CSS, touch events)” (if implemented)

- User
- “The Last Compiler (index.html)” inside “Browser”
- Optional: “Web Storage”
- No external services (explicitly show “None”)

- UI
- Engine
- Narrative content
- Puzzle modules broken out by concept
- State + Persistence
- Browser APIs

Example flow:
- Load page → initialize state → load save → render intro
- Player selects choice → engine resolves branch → updates state → renders next node
- Enter puzzle → validate attempt → feedback → unlock → autosave → continue

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram 1: Context / Container (single-file offline web app)
  %% =========================================================
  subgraph "Context (Offline, Single-Page Web Game)"
    U["Player (touch, mouse, keyboard)"]:::user

    subgraph "Browser (Device Runtime)"
      APP["The Last Compiler (Standalone Client Runtime)"]:::app
      DOM["DOM & CSSOM (Rendering Engine)"]:::browser
      INPUT["Input Events (Touch/Mouse/Keyboard)"]:::browser
      STORAGE[("Web Storage\n(localStorage / IndexedDB)\n(optional)")]:::storageOptional
      NET["Network / External APIs (None)"]:::externalNone
    end

    DIST["Distribution\nOpen index.html locally\nNo server/build pipeline"]:::note
  end

  U -->|"interacts"| APP
  INPUT -->|"dispatch events"| APP
  APP -->|"render UI"| DOM
  APP <-->|"save/load progress"| STORAGE
  APP -.->|"no calls"| NET
  DIST -.->|"describes constraints"| APP

  %% =========================================================
  %% Diagram 2: Component diagram (inside index.html logical modules)
  %% =========================================================
  subgraph "In-Browser Components (Logical Modules inside index.html)"
    UI["UI (DOM + CSS)\nScreens/Panels/Dialogs/Choices\nResponsive layout"]:::ui
    ENGINE["Game Engine / Flow Controller\nEvent-driven state machine\nRouting: intro→chapter→puzzle→result"]:::engine
    STATE["GameState\nscene/chapter\nbranch variables\nprogress flags"]:::state
    NARR["Narrative Graph / Content Model\nstory nodes/chapters/dialogue\nmilestones & branching"]:::content

    subgraph "Learning / Puzzle Modules"
      PZ["Puzzle Module Hub\nstart/grade/feedback/hints"]:::puzzle
      VAR["Variables"]:::puzzleLeaf
      LOOP["Loops"]:::puzzleLeaf
      COND["Conditionals"]:::puzzleLeaf
      FUNC["Functions"]:::puzzleLeaf
      ARR["Arrays"]:::puzzleLeaf
      OBJ["Objects"]:::puzzleLeaf
      REC["Recursion"]:::puzzleLeaf
    end

    PERSIST[("Persistence\nSave/Load (optional)\nlocalStorage/IndexedDB")]:::storageOptional

    subgraph "Platform APIs"
      API_DOM["DOM API"]:::browser
      API_AUDIO["Audio API (optional)"]:::browserOptional
      API_TIMER["Timers / rAF\n(setTimeout/requestAnimationFrame)"]:::browser
    end

    SPEC["Narrative Design Spec\nChapters/Mechanics/Progression"]:::doc
    README["Constraints / Stack Doc\nOffline, no frameworks,\nsingle-file"]:::doc
  end

  %% Core flows
  UI -->|"dispatch UI events"| ENGINE
  ENGINE -->|"render view"| UI

  ENGINE <-->|"read/write"| STATE
  ENGINE -->|"select next node/branch"| NARR
  NARR -->|"content data"| ENGINE

  ENGINE -->|"start puzzle"| PZ
  PZ -->|"evaluate attempt"| VAR
  PZ -->|"evaluate attempt"| LOOP
  PZ -->|"evaluate attempt"| COND
  PZ -->|"evaluate attempt"| FUNC
  PZ -->|"evaluate attempt"| ARR
  PZ -->|"evaluate attempt"| OBJ
  PZ -->|"evaluate attempt"| REC
  PZ -->|"completion + feedback"| ENGINE
  PZ -->|"update completion flags"| STATE

  STATE <-->|"save/load progress"| PERSIST

  %% Platform dependencies
  UI -->|"DOM updates"| API_DOM
  ENGINE -->|"timing/animation"| API_TIMER
  ENGINE -.->|"sound cues"| API_AUDIO

  %% Documentation references
  SPEC -.->|"guides content/chapters"| NARR
  README -.->|"documents constraints"| ENGINE

  %% =========================================================
  %% Diagram 3: Runtime flow (activity-style)
  %% =========================================================
  subgraph "Runtime Flow (Typical Session)"
    START(["Open index.html"]):::flowStart
    INIT["Initialize Engine\nBind UI handlers"]:::flow
    LOAD["Load Save (if any)\nelse create new GameState"]:::flow
    RENDER["Render Intro / Current Scene"]:::flow
    CHOICE{"Player action?\n(choice / input / puzzle)"}:::flowDecision
    RESOLVE["Resolve branch / advance dialogue\nUpdate GameState"]:::flow
    ENTERPZ["Enter Puzzle\nshow prompt + inputs"]:::flow
    EVAL["Validate attempt\npass/fail + hints"]:::flow
    UNLOCK["On success:\nset completion flags\nunlock next content"]:::flow
    SAVE["Autosave progress (optional)"]:::flow
    LOOPBACK(["Continue to next scene"]):::flowEnd
  end

  START --> INIT --> LOAD --> RENDER --> CHOICE
  CHOICE -->|"narrative choice"| RESOLVE --> SAVE --> LOOPBACK --> RENDER
  CHOICE -->|"puzzle attempt"| ENTERPZ --> EVAL
  EVAL -->|"fail"| ENTERPZ
  EVAL -->|"pass"| UNLOCK --> SAVE --> LOOPBACK

  %% =========================================================
  %% Click events (from component_mapping)
  %% =========================================================
  click APP "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click UI "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click ENGINE "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click NARR "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click PZ "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click STATE "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click PERSIST "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/index.html"
  click SPEC "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/GAME-DESIGN.md"
  click README "https://github.com/hpglcrm-afk/the-last-compiler/blob/main/README.md"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef user fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
  classDef app fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1
  classDef ui fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100
  classDef engine fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px,color:#311B92
  classDef state fill:#FCE4EC,stroke:#C2185B,stroke-width:2px,color:#880E4F
  classDef content fill:#E0F7FA,stroke:#00838F,stroke-width:2px,color:#006064
  classDef puzzle fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px,color:#4A148C
  classDef puzzleLeaf fill:#F8EAFB,stroke:#9C27B0,stroke-width:1.5px,color:#4A148C
  classDef storageOptional fill:#FFFDE7,stroke:#F9A825,stroke-width:2px,color:#F57F17,stroke-dasharray: 6 4
  classDef browser fill:#ECEFF1,stroke:#455A64,stroke-width:2px,color:#263238
  classDef browserOptional fill:#ECEFF1,stroke:#607D8B,stroke-width:2px,color:#263238,stroke-dasharray: 6 4
  classDef externalNone fill:#FFEBEE,stroke:#C62828,stroke-width:2px,color:#B71C1C,stroke-dasharray: 6 4
  classDef doc fill:#E8EAF6,stroke:#3949AB,stroke-width:2px,color:#1A237E
  classDef note fill:#FAFAFA,stroke:#757575,stroke-width:1.5px,color:#424242,stroke-dasharray: 4 4

  classDef flowStart fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1
  classDef flow fill:#FFFFFF,stroke:#546E7A,stroke-width:1.5px,color:#263238
  classDef flowDecision fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100
  classDef flowEnd fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
```
