# fabrigu/codetown architecture

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

- Interactive diagram: https://gitdiagram.com/fabrigu/codetown
- Repository: https://github.com/fabrigu/codetown

## Overview

CodeTown surveys a Git repository, turns its modules, imports, and detected issues into a town model, then lets users explore that model in terminal, browser, snapshots, or live agent-watch views. Its distinct domain stages include language-aware source analysis, town layout and road routing, problem detection, and session/watch activity visualization. The graph reflects documented workflows and relationships visible in the supplied excerpts or source index; browser serving and several runtime details are documented but not sampled in source.

Main entry points: [`towncode.py`](https://github.com/fabrigu/codetown/blob/main/towncode.py) (Command interface), [`survey.py`](https://github.com/fabrigu/codetown/blob/main/survey.py) (Survey engine), [`townmap.py`](https://github.com/fabrigu/codetown/blob/main/townmap.py) (Town map), [`watch.py`](https://github.com/fabrigu/codetown/blob/main/watch.py) (Agent watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Repository analysis"]
  node_cli["Command interface<br/>[towncode.py]"]
  node_repo["Repository reader<br/>[repo.py]"]
  node_survey["Survey engine<br/>[survey.py]"]
  node_adapters["Language adapters<br/>[langs.py]"]
  node_parsing["Parser toolkit<br/>[langkit.py]"]
  node_session["Session analysis<br/>[session.py]"]
end

subgraph group_town["Town modeling"]
  node_model["Repository model<br/>[model.py]"]
  node_layout["District layout<br/>[plat.py]"]
  node_townmap["Town map<br/>[townmap.py]"]
  node_roads["Import roads<br/>[roads.py]"]
  node_problems["Problem detection<br/>[problems.py]"]
end

subgraph group_views["Exploration and rendering"]
  node_terminal["Terminal viewer<br/>[viewer.py]"]
  node_renderer["Town renderer<br/>[drawtown.py]"]
  node_browser["Browser town<br/>[webserve.py]"]
  node_webclient["3D web client<br/>[town3d.js]"]
  node_snapshot["PNG snapshot<br/>[snapshot.py]"]
end

subgraph group_watch["Live agent watch"]
  node_watch["Agent watcher<br/>[watch.py]"]
  node_live["Live town state<br/>[livetown.py]"]
  node_crowd["Agent movement<br/>[crowd.py]"]
end

node_user(("Engineer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"runs survey"| node_survey
node_survey -->|"reads files"| node_repo
node_survey -->|"selects languages"| node_adapters
node_adapters -->|"uses parser"| node_parsing
node_survey -->|"builds model"| node_model
node_cli -->|"loads session"| node_session
node_session -->|"validates repository"| node_repo
node_cli -->|"lays out town"| node_layout
node_cli -->|"builds town"| node_townmap
node_townmap -->|"maps modules"| node_model
node_cli -->|"routes imports"| node_roads
node_roads -->|"routes on tiles"| node_townmap
node_cli -->|"finds issues"| node_problems
node_problems -->|"checks modules"| node_model
node_cli -->|"opens viewer"| node_terminal
node_terminal -->|"draws town"| node_renderer
node_cli -->|"renders snapshot"| node_snapshot
node_cli -->|"serves browser view"| node_browser
node_browser -->|"serves client"| node_webclient
node_cli -->|"starts watch"| node_watch
node_watch -->|"updates town"| node_live
node_live -.->|"advances agents"| node_crowd
node_crowd -->|"moves through town"| node_townmap
node_live -->|"draws activity"| node_renderer
node_watch -->|"reads transcripts"| node_session

click node_cli "https://github.com/fabrigu/codetown/blob/main/towncode.py"
click node_repo "https://github.com/fabrigu/codetown/blob/main/repo.py"
click node_survey "https://github.com/fabrigu/codetown/blob/main/survey.py"
click node_adapters "https://github.com/fabrigu/codetown/blob/main/langs.py"
click node_parsing "https://github.com/fabrigu/codetown/blob/main/langkit.py"
click node_session "https://github.com/fabrigu/codetown/blob/main/session.py"
click node_model "https://github.com/fabrigu/codetown/blob/main/model.py"
click node_layout "https://github.com/fabrigu/codetown/blob/main/plat.py"
click node_townmap "https://github.com/fabrigu/codetown/blob/main/townmap.py"
click node_roads "https://github.com/fabrigu/codetown/blob/main/roads.py"
click node_problems "https://github.com/fabrigu/codetown/blob/main/problems.py"
click node_terminal "https://github.com/fabrigu/codetown/blob/main/viewer.py"
click node_renderer "https://github.com/fabrigu/codetown/blob/main/drawtown.py"
click node_browser "https://github.com/fabrigu/codetown/blob/main/webserve.py"
click node_webclient "https://github.com/fabrigu/codetown/blob/main/web/town3d.js"
click node_snapshot "https://github.com/fabrigu/codetown/blob/main/snapshot.py"
click node_watch "https://github.com/fabrigu/codetown/blob/main/watch.py"
click node_live "https://github.com/fabrigu/codetown/blob/main/livetown.py"
click node_crowd "https://github.com/fabrigu/codetown/blob/main/crowd.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_cli,node_repo,node_survey,node_adapters,node_parsing,node_session toneBlue
class node_model,node_layout,node_townmap,node_roads,node_problems toneAmber
class node_terminal,node_renderer,node_browser,node_webclient,node_snapshot toneMint
class node_watch,node_live,node_crowd toneRose
class node_user toneIndigo
```

## Components

### Repository analysis

- [Command interface](https://github.com/fabrigu/codetown/blob/main/towncode.py): `towncode.py`
- [Repository reader](https://github.com/fabrigu/codetown/blob/main/repo.py): `repo.py`
- [Survey engine](https://github.com/fabrigu/codetown/blob/main/survey.py): `survey.py`
- [Language adapters](https://github.com/fabrigu/codetown/blob/main/langs.py): `langs.py`
- [Parser toolkit](https://github.com/fabrigu/codetown/blob/main/langkit.py): `langkit.py`
- [Session analysis](https://github.com/fabrigu/codetown/blob/main/session.py): `session.py`

### Town modeling

- [Repository model](https://github.com/fabrigu/codetown/blob/main/model.py): `model.py`
- [District layout](https://github.com/fabrigu/codetown/blob/main/plat.py): `plat.py`
- [Town map](https://github.com/fabrigu/codetown/blob/main/townmap.py): `townmap.py`
- [Import roads](https://github.com/fabrigu/codetown/blob/main/roads.py): `roads.py`
- [Problem detection](https://github.com/fabrigu/codetown/blob/main/problems.py): `problems.py`

### Exploration and rendering

- [Terminal viewer](https://github.com/fabrigu/codetown/blob/main/viewer.py): `viewer.py`
- [Town renderer](https://github.com/fabrigu/codetown/blob/main/drawtown.py): `drawtown.py`
- [Browser town](https://github.com/fabrigu/codetown/blob/main/webserve.py): `webserve.py`
- [3D web client](https://github.com/fabrigu/codetown/blob/main/web/town3d.js): `web/town3d.js`
- [PNG snapshot](https://github.com/fabrigu/codetown/blob/main/snapshot.py): `snapshot.py`

### Live agent watch

- [Agent watcher](https://github.com/fabrigu/codetown/blob/main/watch.py): `watch.py`
- [Live town state](https://github.com/fabrigu/codetown/blob/main/livetown.py): `livetown.py`
- [Agent movement](https://github.com/fabrigu/codetown/blob/main/crowd.py): `crowd.py`

### Other components

- **Engineer**

## Connections

- Engineer → Command interface: runs commands
- Command interface → Survey engine: runs survey (evidence: `towncode.py`)
- Survey engine → Repository reader: reads files (evidence: `survey.py`)
- Survey engine → Language adapters: selects languages (evidence: `survey.py`)
- Language adapters → Parser toolkit: uses parser
- Survey engine → Repository model: builds model (evidence: `survey.py`)
- Command interface → Session analysis: loads session (evidence: `towncode.py`)
- Session analysis → Repository reader: validates repository (evidence: `session.py`)
- Command interface → District layout: lays out town (evidence: `towncode.py`)
- Command interface → Town map: builds town (evidence: `towncode.py`)
- Town map → Repository model: maps modules (evidence: `townmap.py`)
- Command interface → Import roads: routes imports (evidence: `towncode.py`)
- Import roads → Town map: routes on tiles (evidence: `roads.py`)
- Command interface → Problem detection: finds issues (evidence: `towncode.py`)
- Problem detection → Repository model: checks modules (evidence: `problems.py`)
- Command interface → Terminal viewer: opens viewer (evidence: `towncode.py`)
- Terminal viewer → Town renderer: draws town (evidence: `viewer.py`)
- Command interface → PNG snapshot: renders snapshot (evidence: `towncode.py`)
- Command interface → Browser town: serves browser view (evidence: `towncode.py`)
- Browser town → 3D web client: serves client
- Command interface → Agent watcher: starts watch (evidence: `towncode.py`)
- Agent watcher → Live town state: updates town (evidence: `livetown.py`)
- Live town state → Agent movement: advances agents (evidence: `livetown.py`)
- Agent movement → Town map: moves through town (evidence: `crowd.py`)
- Live town state → Town renderer: draws activity (evidence: `livetown.py`)
- Agent watcher → Session analysis: reads transcripts (evidence: `watch.py`)
