# mnahtygal/thor-city architecture

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

- Interactive diagram: https://gitdiagram.com/mnahtygal/thor-city
- Repository: https://github.com/mnahtygal/thor-city

## Overview

THOR CITY collects live process and host telemetry from the local THOR machine and an optional Mac Mini, then streams it to a browser that renders an interactive, GPU-instanced city. The principal path is telemetry collection → host aggregation → WebSocket updates → city visualization and inspection. The README also documents search, pause, overview, FPS, process picking, and the performance-oriented tower design. Most browser behavior is in one sampled file; the HTML and CSS are present in the tree but were not sampled, so their wiring is not inferred.

Main entry points: [`app/static/city.js`](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js) (3D Scene), [`app/main.py`](https://github.com/mnahtygal/thor-city/blob/main/app/main.py) (Fleet Snapshot), [`app/static/index.html`](https://github.com/mnahtygal/thor-city/blob/main/app/static/index.html) (City Page), [`collector.py`](https://github.com/mnahtygal/thor-city/blob/main/collector.py) (Mac Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telemetry["Telemetry Collection"]
  node_local["Local Telemetry<br/>[main.py]"]
  node_remote["Mac Collector<br/>[collector.py]"]
end

subgraph group_service["Aggregation Service"]
  node_fleet["Fleet Snapshot<br/>[main.py]"]
  node_http["Snapshot API<br/>[main.py]"]
  node_stream["WebSocket Stream<br/>[main.py]"]
end

subgraph group_visualization["City Visualization"]
  node_page["City Page<br/>[index.html]"]
  node_scene["3D Scene<br/>[city.js]"]
  node_districts["City Districts<br/>[city.js]"]
  node_towers["Process Towers<br/>[city.js]"]
  node_traffic["Data Traffic<br/>[city.js]"]
  node_styles["Page Styling<br/>[style.css]"]
end

subgraph group_interaction["Browser Interaction"]
  node_controls["Camera Controls<br/>[city.js]"]
  node_search["Process Search<br/>[city.js]"]
  node_inspector["Process Inspector<br/>[city.js]"]
  node_status["Telemetry Status<br/>[city.js]"]
end

node_operator(("Operator"))

node_local -->|"collects locally"| node_fleet
node_fleet -->|"fetches snapshot"| node_remote
node_remote -.->|"returns telemetry"| node_fleet
node_http -->|"returns snapshot"| node_fleet
node_stream -->|"requests updates"| node_fleet
node_operator -.->|"opens"| node_page
node_page -.->|"hosts scene"| node_scene
node_scene -->|"receives updates"| node_stream
node_scene -->|"builds districts"| node_districts
node_scene -->|"renders processes"| node_towers
node_scene -->|"animates traffic"| node_traffic
node_scene -->|"updates camera"| node_controls
node_search -->|"filters processes"| node_towers
node_towers -->|"selects process"| node_inspector
node_scene -->|"updates metrics"| node_status
node_page -.->|"uses styles"| node_styles

click node_local "https://github.com/mnahtygal/thor-city/blob/main/app/main.py"
click node_remote "https://github.com/mnahtygal/thor-city/blob/main/collector.py"
click node_fleet "https://github.com/mnahtygal/thor-city/blob/main/app/main.py"
click node_http "https://github.com/mnahtygal/thor-city/blob/main/app/main.py"
click node_stream "https://github.com/mnahtygal/thor-city/blob/main/app/main.py"
click node_page "https://github.com/mnahtygal/thor-city/blob/main/app/static/index.html"
click node_scene "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_districts "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_towers "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_traffic "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_controls "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_search "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_inspector "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_status "https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js"
click node_styles "https://github.com/mnahtygal/thor-city/blob/main/app/static/style.css"

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_local,node_remote toneBlue
class node_fleet,node_http,node_stream toneAmber
class node_page,node_scene,node_districts,node_towers,node_traffic,node_styles toneMint
class node_controls,node_search,node_inspector,node_status toneRose
class node_operator toneIndigo
```

## Components

### Telemetry Collection

- [Local Telemetry](https://github.com/mnahtygal/thor-city/blob/main/app/main.py): `app/main.py`
- [Mac Collector](https://github.com/mnahtygal/thor-city/blob/main/collector.py): `collector.py`

### Aggregation Service

- [Fleet Snapshot](https://github.com/mnahtygal/thor-city/blob/main/app/main.py): `app/main.py`
- [Snapshot API](https://github.com/mnahtygal/thor-city/blob/main/app/main.py): `app/main.py`
- [WebSocket Stream](https://github.com/mnahtygal/thor-city/blob/main/app/main.py): `app/main.py`

### City Visualization

- [City Page](https://github.com/mnahtygal/thor-city/blob/main/app/static/index.html): `app/static/index.html`
- [3D Scene](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [City Districts](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Process Towers](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Data Traffic](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Page Styling](https://github.com/mnahtygal/thor-city/blob/main/app/static/style.css): `app/static/style.css`

### Browser Interaction

- [Camera Controls](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Process Search](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Process Inspector](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`
- [Telemetry Status](https://github.com/mnahtygal/thor-city/blob/main/app/static/city.js): `app/static/city.js`

### Other components

- **Operator**

## Connections

- Local Telemetry → Fleet Snapshot: collects locally (evidence: `app/main.py`)
- Fleet Snapshot → Mac Collector: fetches snapshot (evidence: `app/main.py`)
- Mac Collector → Fleet Snapshot: returns telemetry
- Snapshot API → Fleet Snapshot: returns snapshot (evidence: `app/main.py`)
- WebSocket Stream → Fleet Snapshot: requests updates (evidence: `app/main.py`)
- Operator → City Page: opens
- City Page → 3D Scene: hosts scene
- 3D Scene → WebSocket Stream: receives updates (evidence: `app/static/city.js`)
- 3D Scene → City Districts: builds districts (evidence: `app/static/city.js`)
- 3D Scene → Process Towers: renders processes (evidence: `app/static/city.js`)
- 3D Scene → Data Traffic: animates traffic (evidence: `app/static/city.js`)
- 3D Scene → Camera Controls: updates camera (evidence: `app/static/city.js`)
- Process Search → Process Towers: filters processes (evidence: `app/static/city.js`)
- Process Towers → Process Inspector: selects process (evidence: `app/static/city.js`)
- 3D Scene → Telemetry Status: updates metrics (evidence: `app/static/city.js`)
- City Page → Page Styling: uses styles
