# joegsuero/terminal-playground architecture

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

- Interactive diagram: https://gitdiagram.com/joegsuero/terminal-playground
- Repository: https://github.com/joegsuero/terminal-playground

## Overview

Terminal Playground is a browser-based Linux and Docker command-learning simulator. Users choose a mode, enter commands in a terminal, and receive simulated output in a safe environment; lessons and help support that learning path, while challenges and achievements add progress feedback. The Linux shell executes registered commands against a virtual filesystem; Docker has a separate session and simulated engine. The graph preserves these runtime and learning branches. Some page wiring and Docker-terminal details were not excerpted, so those links are marked unverified rather than presented as inspected calls.

Main entry points: [`src/pages/Index`](https://github.com/joegsuero/terminal-playground/tree/main/src/pages/Index) (Learning Page), [`src/components/Terminal/TmuxTerminal.tsx`](https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/TmuxTerminal.tsx) (Terminal Multiplexer), [`src/store/terminalStore.ts`](https://github.com/joegsuero/terminal-playground/blob/main/src/store/terminalStore.ts) (Progress Store), [`src/lib/ShellSession.ts`](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/ShellSession.ts) (Linux Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_app["App Router<br/>[App.tsx]"]
  node_pages["Learning Page"]
  node_mode["Mode Selector<br/>[ModeSelector.tsx]"]
end

subgraph group_terminal["Terminal Runtime"]
  node_tmux["Terminal Multiplexer<br/>[TmuxTerminal.tsx]"]
  node_readline["Readline Shell<br/>[ReadlineShell.ts]"]
  node_editor["Editor Overlay<br/>[EditorOverlay.tsx]"]
  node_repl["REPL Contract<br/>[repl.ts]"]
end

subgraph group_linux["Linux Simulation"]
  node_linuxsession["Linux Session<br/>[ShellSession.ts]"]
  node_linuxcommands["Linux Commands"]
  node_linuxshell["Shell Parsing<br/>[shell.ts]"]
  node_vfs[("Virtual Filesystem<br/>[vfs.ts]")]
end

subgraph group_docker["Docker Simulation"]
  node_dockerterminal["Docker Terminal<br/>[DockerTerminal.tsx]"]
  node_dockersession["Docker Session<br/>[DockerSession.ts]"]
  node_dockercommands["Docker Commands"]
  node_dockerengine[("Docker Engine State<br/>[DockerEngine.ts]")]
end

subgraph group_learning["Learning Progress"]
  node_linuxlessons["Linux Lessons<br/>[linuxLessons.ts]"]
  node_dockerlessons["Docker Lessons<br/>[dockerLessons.ts]"]
  node_store[("Progress Store<br/>[terminalStore.ts]")]
  node_achievements["Achievements<br/>[achievements.ts]"]
  node_challenges["Daily Challenges<br/>[challenges.ts]"]
  node_challengehook["Challenge View<br/>[useChallenges.ts]"]
  node_achievementhook["Achievement View<br/>[useAchievements.ts]"]
  node_toaster["Achievement Toaster"]
end

node_learner(("Learner"))

node_learner -.->|"opens"| node_app
node_app -->|"routes to"| node_pages
node_pages -.->|"presents"| node_mode
node_pages -.->|"offers terminal"| node_tmux
node_mode -.->|"selects Docker"| node_dockerterminal
node_mode -.->|"selects Linux"| node_tmux
node_tmux -->|"uses"| node_readline
node_tmux -->|"calls session"| node_repl
node_tmux -->|"renders"| node_editor
node_linuxsession -->|"implements"| node_repl
node_linuxsession -->|"dispatches"| node_linuxcommands
node_linuxsession -->|"parses with"| node_linuxshell
node_linuxsession -->|"reads and writes"| node_vfs
node_dockerterminal -.->|"runs commands"| node_dockersession
node_dockersession -->|"dispatches"| node_dockercommands
node_dockersession -->|"uses state"| node_dockerengine
node_pages -.->|"offers lessons"| node_linuxlessons
node_pages -.->|"offers lessons"| node_dockerlessons
node_challengehook -->|"gets challenge"| node_challenges
node_challengehook -->|"reads and updates"| node_store
node_achievementhook -->|"gets catalogue"| node_achievements
node_achievementhook -->|"reads progress"| node_store
node_store -->|"evaluates unlocks"| node_achievements
node_store -->|"gets day key"| node_challenges
node_app -->|"mounts"| node_toaster
node_toaster -->|"reads pending awards"| node_store

click node_app "https://github.com/joegsuero/terminal-playground/blob/main/src/App.tsx"
click node_pages "https://github.com/joegsuero/terminal-playground/tree/main/src/pages/Index"
click node_mode "https://github.com/joegsuero/terminal-playground/blob/main/src/components/ModeSelector.tsx"
click node_tmux "https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/TmuxTerminal.tsx"
click node_readline "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/ReadlineShell.ts"
click node_editor "https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/EditorOverlay.tsx"
click node_repl "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/repl.ts"
click node_linuxsession "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/ShellSession.ts"
click node_linuxcommands "https://github.com/joegsuero/terminal-playground/tree/main/src/commands/linux"
click node_linuxshell "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/shell.ts"
click node_vfs "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/vfs.ts"
click node_linuxlessons "https://github.com/joegsuero/terminal-playground/blob/main/src/data/linuxLessons.ts"
click node_dockerterminal "https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/DockerTerminal.tsx"
click node_dockersession "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/DockerSession.ts"
click node_dockercommands "https://github.com/joegsuero/terminal-playground/tree/main/src/commands/docker"
click node_dockerengine "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/DockerEngine.ts"
click node_dockerlessons "https://github.com/joegsuero/terminal-playground/blob/main/src/data/dockerLessons.ts"
click node_store "https://github.com/joegsuero/terminal-playground/blob/main/src/store/terminalStore.ts"
click node_achievements "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/achievements.ts"
click node_challenges "https://github.com/joegsuero/terminal-playground/blob/main/src/lib/challenges.ts"
click node_challengehook "https://github.com/joegsuero/terminal-playground/blob/main/src/hooks/useChallenges.ts"
click node_achievementhook "https://github.com/joegsuero/terminal-playground/blob/main/src/hooks/useAchievements.ts"
click node_toaster "https://github.com/joegsuero/terminal-playground/blob/main/src/components/Gamification/AchievementToaster.tsx"

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_app,node_pages,node_mode toneBlue
class node_tmux,node_readline,node_editor,node_repl toneAmber
class node_linuxsession,node_linuxcommands,node_linuxshell,node_vfs toneMint
class node_dockerterminal,node_dockersession,node_dockercommands,node_dockerengine toneRose
class node_linuxlessons,node_dockerlessons,node_store,node_achievements,node_challenges,node_challengehook,node_achievementhook,node_toaster,node_learner toneIndigo
```

## Components

### Application UI

- [App Router](https://github.com/joegsuero/terminal-playground/blob/main/src/App.tsx): `src/App.tsx`
- [Learning Page](https://github.com/joegsuero/terminal-playground/tree/main/src/pages/Index): `src/pages/Index`
- [Mode Selector](https://github.com/joegsuero/terminal-playground/blob/main/src/components/ModeSelector.tsx): `src/components/ModeSelector.tsx`

### Terminal Runtime

- [Terminal Multiplexer](https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/TmuxTerminal.tsx): `src/components/Terminal/TmuxTerminal.tsx`
- [Readline Shell](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/ReadlineShell.ts): `src/lib/ReadlineShell.ts`
- [Editor Overlay](https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/EditorOverlay.tsx): `src/components/Terminal/EditorOverlay.tsx`
- [REPL Contract](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/repl.ts): `src/lib/repl.ts`

### Linux Simulation

- [Linux Session](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/ShellSession.ts): `src/lib/ShellSession.ts`
- [Linux Commands](https://github.com/joegsuero/terminal-playground/tree/main/src/commands/linux): `src/commands/linux`
- [Shell Parsing](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/shell.ts): `src/lib/shell.ts`
- [Virtual Filesystem](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/vfs.ts): `src/lib/vfs.ts`

### Docker Simulation

- [Docker Terminal](https://github.com/joegsuero/terminal-playground/blob/main/src/components/Terminal/DockerTerminal.tsx): `src/components/Terminal/DockerTerminal.tsx`
- [Docker Session](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/DockerSession.ts): `src/lib/DockerSession.ts`
- [Docker Commands](https://github.com/joegsuero/terminal-playground/tree/main/src/commands/docker): `src/commands/docker`
- [Docker Engine State](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/DockerEngine.ts): `src/lib/DockerEngine.ts`

### Learning Progress

- [Linux Lessons](https://github.com/joegsuero/terminal-playground/blob/main/src/data/linuxLessons.ts): `src/data/linuxLessons.ts`
- [Docker Lessons](https://github.com/joegsuero/terminal-playground/blob/main/src/data/dockerLessons.ts): `src/data/dockerLessons.ts`
- [Progress Store](https://github.com/joegsuero/terminal-playground/blob/main/src/store/terminalStore.ts): `src/store/terminalStore.ts`
- [Achievements](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/achievements.ts): `src/lib/achievements.ts`
- [Daily Challenges](https://github.com/joegsuero/terminal-playground/blob/main/src/lib/challenges.ts): `src/lib/challenges.ts`
- [Challenge View](https://github.com/joegsuero/terminal-playground/blob/main/src/hooks/useChallenges.ts): `src/hooks/useChallenges.ts`
- [Achievement View](https://github.com/joegsuero/terminal-playground/blob/main/src/hooks/useAchievements.ts): `src/hooks/useAchievements.ts`
- [Achievement Toaster](https://github.com/joegsuero/terminal-playground/blob/main/src/components/Gamification/AchievementToaster.tsx): `src/components/Gamification/AchievementToaster.tsx`

### Other components

- **Learner**

## Connections

- Learner → App Router: opens
- App Router → Learning Page: routes to (evidence: `src/App.tsx`)
- Learning Page → Mode Selector: presents (evidence: `src/pages/Index/Header.tsx`)
- Learning Page → Terminal Multiplexer: offers terminal
- Mode Selector → Docker Terminal: selects Docker
- Mode Selector → Terminal Multiplexer: selects Linux
- Terminal Multiplexer → Readline Shell: uses (evidence: `src/components/Terminal/TmuxTerminal.tsx`)
- Terminal Multiplexer → REPL Contract: calls session (evidence: `src/components/Terminal/TmuxTerminal.tsx`)
- Terminal Multiplexer → Editor Overlay: renders (evidence: `src/components/Terminal/TmuxTerminal.tsx`)
- Linux Session → REPL Contract: implements (evidence: `src/lib/repl.ts`)
- Linux Session → Linux Commands: dispatches (evidence: `src/lib/ShellSession.ts`)
- Linux Session → Shell Parsing: parses with (evidence: `src/lib/ShellSession.ts`)
- Linux Session → Virtual Filesystem: reads and writes (evidence: `src/lib/ShellSession.ts`)
- Docker Terminal → Docker Session: runs commands
- Docker Session → Docker Commands: dispatches (evidence: `src/lib/DockerSession.ts`)
- Docker Session → Docker Engine State: uses state (evidence: `src/lib/DockerSession.ts`)
- Learning Page → Linux Lessons: offers lessons
- Learning Page → Docker Lessons: offers lessons
- Challenge View → Daily Challenges: gets challenge (evidence: `src/hooks/useChallenges.ts`)
- Challenge View → Progress Store: reads and updates (evidence: `src/hooks/useChallenges.ts`)
- Achievement View → Achievements: gets catalogue (evidence: `src/hooks/useAchievements.ts`)
- Achievement View → Progress Store: reads progress (evidence: `src/hooks/useAchievements.ts`)
- Progress Store → Achievements: evaluates unlocks (evidence: `src/store/terminalStore.ts`)
- Progress Store → Daily Challenges: gets day key (evidence: `src/store/terminalStore.ts`)
- App Router → Achievement Toaster: mounts (evidence: `src/App.tsx`)
- Achievement Toaster → Progress Store: reads pending awards (evidence: `src/components/Gamification/AchievementToaster.tsx`)
