# probablyapigeon/youtubelonk architecture

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

- Interactive diagram: https://gitdiagram.com/probablyapigeon/youtubelonk
- Repository: https://github.com/probablyapigeon/youtubelonk

## Overview

YouTubeLonk is a terminal civilization simulator: a player advances or commands a world of Lonks, whose social and learning systems produce dialogue, events, and a live map. Optional quote teaching and read-only YouTube chat feed learning or commands into that experience. The main program is the runtime hub; the other modules provide civilization, dialogue, input, and presentation capabilities. Several internal call sites are not shown in the excerpts, so edges based only on documented module references are labeled as imports rather than inferred execution steps.

Main entry points: [`dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`](https://github.com/probablyapigeon/youtubelonk/blob/main/dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py) (World and CLI), [`lonk_quotes.py`](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_quotes.py) (Quote teaching), [`lonk_dialogue.py`](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_dialogue.py) (Dialogue grammar), [`lonk_youtube.py`](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_youtube.py) (Chat intake)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_world["World simulation"]
  node_runtime["World and CLI"]
  node_society["Civilization systems<br/>[lonk_society.py]"]
end

subgraph group_learning["Learning and memory"]
  node_dialogue["Dialogue grammar<br/>[lonk_dialogue.py]"]
  node_semantics[("Semantic traces<br/>[lonk_semantics.py]")]
  node_quotes["Quote teaching<br/>[lonk_quotes.py]"]
end

subgraph group_interaction["User interaction"]
  node_youtube["Chat intake<br/>[lonk_youtube.py]"]
end

subgraph group_presentation["Terminal presentation"]
  node_live_view["Live dashboard<br/>[lonk_live.py]"]
  node_map["World map<br/>[lonk_map.py]"]
  node_visuals["Visual helpers<br/>[lonk_visuals.py]"]
end

node_player(("Player"))
node_quote_files["Quote corpus"]
node_viewers(("Live viewers"))
node_youtube_api["YouTube API"]
node_speech["Speech engine"]

node_player -->|"commands"| node_runtime
node_runtime -->|"imports"| node_society
node_runtime -->|"imports"| node_dialogue
node_runtime -->|"imports"| node_semantics
node_runtime -->|"imports"| node_quotes
node_runtime -->|"imports"| node_youtube
node_runtime -->|"imports"| node_live_view
node_quotes -->|"loads"| node_quote_files
node_quotes -->|"teaches through"| node_dialogue
node_quotes -->|"learns emoji"| node_visuals
node_youtube -->|"requests"| node_youtube_api
node_viewers -->|"send chat"| node_youtube
node_youtube -->|"queues comments"| node_runtime
node_live_view -->|"renders map"| node_map
node_map -->|"imports"| node_visuals
node_dialogue -->|"imports"| node_semantics
node_dialogue -->|"imports"| node_visuals
node_runtime -.->|"speaks with"| node_speech

click node_runtime "https://github.com/probablyapigeon/youtubelonk/blob/main/dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py"
click node_society "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_society.py"
click node_dialogue "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_dialogue.py"
click node_semantics "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_semantics.py"
click node_quotes "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_quotes.py"
click node_quote_files "https://github.com/probablyapigeon/youtubelonk/tree/main/quote_library"
click node_youtube "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_youtube.py"
click node_live_view "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_live.py"
click node_map "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_map.py"
click node_visuals "https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_visuals.py"

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_runtime,node_society,node_viewers toneBlue
class node_dialogue,node_semantics,node_quotes toneAmber
class node_youtube,node_youtube_api toneMint
class node_live_view,node_map,node_visuals toneRose
class node_player,node_speech toneIndigo
class node_quote_files toneTeal
```

## Components

### World simulation

- [World and CLI](https://github.com/probablyapigeon/youtubelonk/blob/main/dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py): `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`
- [Civilization systems](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_society.py): `lonk_society.py`

### Learning and memory

- [Dialogue grammar](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_dialogue.py): `lonk_dialogue.py`
- [Semantic traces](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_semantics.py): `lonk_semantics.py`
- [Quote teaching](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_quotes.py): `lonk_quotes.py`

### User interaction

- [Chat intake](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_youtube.py): `lonk_youtube.py`

### Terminal presentation

- [Live dashboard](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_live.py): `lonk_live.py`
- [World map](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_map.py): `lonk_map.py`
- [Visual helpers](https://github.com/probablyapigeon/youtubelonk/blob/main/lonk_visuals.py): `lonk_visuals.py`

### Other components

- **Player**
- [Quote corpus](https://github.com/probablyapigeon/youtubelonk/tree/main/quote_library): `quote_library`
- **Live viewers**
- **YouTube API**
- **Speech engine**

## Connections

- Player → World and CLI: commands (evidence: `README.md`)
- World and CLI → Civilization systems: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- World and CLI → Dialogue grammar: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- World and CLI → Semantic traces: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- World and CLI → Quote teaching: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- World and CLI → Chat intake: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- World and CLI → Live dashboard: imports (evidence: `dynamiclonk-py-v13-lonks-finally-have-ears-say-command-fixed.py`)
- Quote teaching → Quote corpus: loads (evidence: `lonk_quotes.py`)
- Quote teaching → Dialogue grammar: teaches through (evidence: `lonk_quotes.py`)
- Quote teaching → Visual helpers: learns emoji (evidence: `lonk_quotes.py`)
- Chat intake → YouTube API: requests (evidence: `lonk_youtube.py`)
- Live viewers → Chat intake: send chat (evidence: `README.md`)
- Chat intake → World and CLI: queues comments (evidence: `README.md`)
- Live dashboard → World map: renders map (evidence: `lonk_live.py`)
- World map → Visual helpers: imports (evidence: `lonk_map.py`)
- Dialogue grammar → Semantic traces: imports (evidence: `lonk_dialogue.py`)
- Dialogue grammar → Visual helpers: imports (evidence: `lonk_dialogue.py`)
- World and CLI → Speech engine: speaks with (evidence: `README.md`)