# lineville/herdr-flightdeck-layout architecture

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

- Interactive diagram: https://gitdiagram.com/lineville/herdr-flightdeck-layout
- Repository: https://github.com/lineville/herdr-flightdeck-layout

## Overview

This repository is a collection of Herdr desktop mods centered on Flight Deck: users organize repository spaces and worktrees, launch agent terminals or chats, and monitor agents in an orbital view. Supporting mods provide tab and file navigation, context menus, worktree management, and Claude/Codex usage meters. The sampled code shows shared state and host commands, but not every mod’s registration or UI wiring; uncertain links are omitted.

Main entry points: [`mods/flightdeck/main.js`](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/main.js) (Agent fleet view), [`mods/deck-tabs/main.js`](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-tabs/main.js) (Tab navigation), [`mods/deck-spaces/main.js`](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-spaces/main.js) (Space and worktree tree), [`mods/usage-meter/fetch.py`](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/usage-meter/fetch.py) (Usage fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace navigation"]
  node_spaces["Space and worktree tree<br/>[main.js]"]
  node_tabs["Tab navigation<br/>[main.js]"]
  node_files["File browser<br/>[main.js]"]
  node_menu["Sidebar context menu<br/>[main.js]"]
  node_newmenu["New agent menu<br/>[main.js]"]
  node_worktree["Worktree dialog<br/>[main.js]"]
end

subgraph group_agents["Agent operations"]
end

subgraph group_flightdeck["Flight Deck"]
  node_deck["Agent fleet view<br/>[main.js]"]
  node_orbit["Orbit geometry<br/>[orbit.js]"]
  node_telemetry["Status parsing and model look<br/>[telemetry.js]"]
  node_demo["Demo fleet data<br/>[demo.js]"]
end

subgraph group_usage["Usage metering"]
  node_meter["Usage status bar<br/>[main.js]"]
  node_fetch["Usage fetcher<br/>[fetch.py]"]
end

node_user(("Herdr user"))
node_host["Herdr host"]
node_claude["Anthropic usage API"]
node_codex["ChatGPT usage API"]

node_user -->|"uses tabs"| node_tabs
node_user -->|"launches agents"| node_newmenu
node_user -->|"checks usage"| node_meter
node_spaces -->|"reads commands"| node_host
node_spaces -->|"publishes tree"| node_tabs
node_tabs -->|"runs tab actions"| node_host
node_tabs -->|"reads shared tree"| node_spaces
node_files -->|"runs Git"| node_host
node_menu -->|"runs tab actions"| node_host
node_newmenu -->|"creates tabs"| node_host
node_worktree -->|"runs Git"| node_host
node_deck -->|"reads agent state"| node_host
node_deck -->|"projects positions"| node_orbit
node_deck -->|"parses status"| node_telemetry
node_deck -.->|"uses demo data"| node_demo
node_meter -->|"executes fetcher"| node_host
node_fetch -->|"requests usage"| node_claude
node_fetch -->|"requests usage"| node_codex

click node_spaces "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-spaces/main.js"
click node_tabs "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-tabs/main.js"
click node_files "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-files/main.js"
click node_menu "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-menu/main.js"
click node_newmenu "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-new-menu/main.js"
click node_worktree "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-worktree/main.js"
click node_deck "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/main.js"
click node_orbit "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/orbit.js"
click node_telemetry "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/telemetry.js"
click node_demo "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/demo.js"
click node_meter "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/usage-meter/main.js"
click node_fetch "https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/usage-meter/fetch.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_spaces,node_tabs,node_files,node_menu,node_newmenu,node_worktree,node_user toneBlue
class node_deck,node_orbit,node_telemetry,node_demo,node_claude,node_codex toneMint
class node_meter,node_fetch toneRose
class node_host toneIndigo
```

## Components

### Workspace navigation

- [Space and worktree tree](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-spaces/main.js): `mods/deck-spaces/main.js`
- [Tab navigation](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-tabs/main.js): `mods/deck-tabs/main.js`
- [File browser](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-files/main.js): `mods/deck-files/main.js`
- [Sidebar context menu](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-menu/main.js): `mods/deck-menu/main.js`
- [New agent menu](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-new-menu/main.js): `mods/deck-new-menu/main.js`
- [Worktree dialog](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/deck-worktree/main.js): `mods/deck-worktree/main.js`

### Flight Deck

- [Agent fleet view](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/main.js): `mods/flightdeck/main.js`
- [Orbit geometry](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/orbit.js): `mods/flightdeck/orbit.js`
- [Status parsing and model look](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/telemetry.js): `mods/flightdeck/telemetry.js`
- [Demo fleet data](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/flightdeck/demo.js): `mods/flightdeck/demo.js`

### Usage metering

- [Usage status bar](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/usage-meter/main.js): `mods/usage-meter/main.js`
- [Usage fetcher](https://github.com/lineville/herdr-flightdeck-layout/blob/main/mods/usage-meter/fetch.py): `mods/usage-meter/fetch.py`

### Other components

- **Herdr user**
- **Herdr host**
- **Anthropic usage API**
- **ChatGPT usage API**

## Connections

- Herdr user → Tab navigation: uses tabs (evidence: `mods/deck-tabs/main.js`)
- Herdr user → New agent menu: launches agents (evidence: `mods/deck-new-menu/main.js`)
- Herdr user → Usage status bar: checks usage (evidence: `mods/usage-meter/main.js`)
- Space and worktree tree → Herdr host: reads commands (evidence: `mods/deck-spaces/main.js`)
- Space and worktree tree → Tab navigation: publishes tree (evidence: `mods/deck-spaces/main.js`)
- Tab navigation → Herdr host: runs tab actions (evidence: `mods/deck-tabs/main.js`)
- Tab navigation → Space and worktree tree: reads shared tree (evidence: `mods/deck-tabs/main.js`)
- File browser → Herdr host: runs Git (evidence: `mods/deck-files/main.js`)
- Sidebar context menu → Herdr host: runs tab actions (evidence: `mods/deck-menu/main.js`)
- New agent menu → Herdr host: creates tabs (evidence: `mods/deck-new-menu/main.js`)
- Worktree dialog → Herdr host: runs Git (evidence: `mods/deck-worktree/main.js`)
- Agent fleet view → Herdr host: reads agent state (evidence: `mods/flightdeck/main.js`)
- Agent fleet view → Orbit geometry: projects positions (evidence: `mods/flightdeck/main.js`)
- Agent fleet view → Status parsing and model look: parses status (evidence: `mods/flightdeck/main.js`)
- Agent fleet view → Demo fleet data: uses demo data (evidence: `mods/flightdeck/main.js`)
- Usage status bar → Herdr host: executes fetcher (evidence: `mods/usage-meter/main.js`)
- Usage fetcher → Anthropic usage API: requests usage (evidence: `mods/usage-meter/fetch.py`)
- Usage fetcher → ChatGPT usage API: requests usage (evidence: `mods/usage-meter/fetch.py`)
