# jsmastery-pro/jsm-hq architecture

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

- Interactive diagram: https://gitdiagram.com/jsmastery-pro/jsm-hq
- Repository: https://github.com/jsmastery-pro/jsm-hq

## Overview

JSM HQ is a local control plane for a team of coding agents: a person configures a project and team, asks the lead to plan work, then monitors worker sessions, tasks, terminals, access requests, and pull requests in a pixel-art office. The server coordinates planning, workspaces, sandbox or local execution, GitHub review synchronization, and agent messaging; the browser consumes live office data and renders the UI and scene. README documents these product stages and capabilities. Server wiring beyond shown imports is summarized conservatively; unsampled subsystem links are omitted where their callers are not evidenced.

Main entry points: [`server/main.ts`](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/main.ts) (Server runtime), [`server/sessions.ts`](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/sessions.ts) (Agent sessions), [`server/hub.ts`](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/hub.ts) (Team hub), [`src/App.tsx`](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/App.tsx) (HQ browser UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["HQ Control Plane"]
  node_cli["HQ launcher<br/>[jsm-hq.mjs]"]
  node_server["Server runtime<br/>[main.ts]"]
  node_hub["Team hub<br/>[hub.ts]"]
  node_state[("HQ state<br/>[store.ts]")]
  node_planner["Task planning<br/>[planner.ts]"]
  node_action["Action items<br/>[actionItems.ts]"]
  node_inbox["Agent messaging<br/>[inbox.ts]"]
  node_http["HTTP and live feed<br/>[http.ts]"]
end

subgraph group_execution["Agent Execution"]
  node_sessions["Agent sessions<br/>[sessions.ts]"]
  node_workspace["Agent workspaces<br/>[workspace.ts]"]
  node_backends["Terminal backends<br/>[pty.ts]"]
  node_sandbox["Sandbox control<br/>[sbx.ts]"]
  node_setup["Setup checks<br/>[setup.ts]"]
  node_repo["Repository operations<br/>[repo.ts]"]
end

subgraph group_integrations["Workflow Integrations"]
  node_github["GitHub review sync<br/>[githubSync.ts]"]
  node_mcp["Agent MCP tools<br/>[mcp.ts]"]
  node_stack["Stack and skills<br/>[stack.ts]"]
end

subgraph group_client["Office Client"]
  node_browser["HQ browser UI<br/>[App.tsx]"]
  node_office_store["Office data store<br/>[office.ts]"]
  node_data_source["Data source contract<br/>[source.ts]"]
  node_drawers["Agent and task drawers<br/>[AgentDrawer.tsx]"]
  node_terminal_view["Terminal view<br/>[TerminalView.tsx]"]
  node_settings["Project settings<br/>[StackSettings.tsx]"]
end

subgraph group_visual["Office Rendering"]
  node_office_scene["Office scene<br/>[OfficeScene.ts]"]
  node_layout["Office layout<br/>[layout.ts]"]
  node_office_store_ui["Office and UI state<br/>[office.ts]"]
  node_palette["Visual theme<br/>[palette.ts]"]
  node_tokens["Theme tokens<br/>[tokens.ts]"]
end

node_person(("Project owner"))

node_person -->|"starts HQ"| node_cli
node_cli -->|"launches"| node_server
node_server -->|"creates"| node_hub
node_server -->|"starts"| node_http
node_server -->|"starts sync"| node_github
node_server -->|"wires"| node_planner
node_server -->|"wires"| node_inbox
node_server -->|"wires"| node_action
node_hub -->|"reads and writes"| node_state
node_hub -->|"uses repo"| node_repo
node_hub -->|"exports plan"| node_planner
node_sessions -->|"prepares folder"| node_workspace
node_sessions -->|"selects backend"| node_backends
node_sessions -->|"runs checks"| node_setup
node_sessions -->|"queries sandbox"| node_sandbox
node_sessions -->|"installs skills"| node_stack
node_github -.->|"syncs PR state"| node_hub
node_person -->|"configures and monitors"| node_browser
node_browser -->|"connects"| node_office_store
node_office_store -->|"uses contract"| node_data_source
node_office_store -.->|"streams updates"| node_http
node_office_store -.->|"sends commands"| node_server
node_browser -->|"hosts drawers"| node_drawers
node_drawers -->|"renders terminal"| node_terminal_view
node_settings -->|"configures stack"| node_stack
node_browser -->|"renders canvas"| node_office_scene
node_office_scene -->|"builds scene layout"| node_layout
node_office_scene -->|"reads state"| node_office_store_ui
node_office_scene -->|"draws with"| node_palette
node_layout -->|"uses palette"| node_palette
node_palette -->|"uses theme tokens"| node_tokens

click node_cli "https://github.com/jsmastery-pro/jsm-hq/blob/main/bin/jsm-hq.mjs"
click node_server "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/main.ts"
click node_hub "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/hub.ts"
click node_state "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/store.ts"
click node_planner "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/planner.ts"
click node_action "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/actionItems.ts"
click node_inbox "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/inbox.ts"
click node_http "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/http.ts"
click node_sessions "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/sessions.ts"
click node_workspace "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/workspace.ts"
click node_backends "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/backends/pty.ts"
click node_sandbox "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/sbx.ts"
click node_setup "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/setup.ts"
click node_repo "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/repo.ts"
click node_github "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/githubSync.ts"
click node_mcp "https://github.com/jsmastery-pro/jsm-hq/blob/main/server/mcp.ts"
click node_stack "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/data/stack.ts"
click node_browser "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/App.tsx"
click node_office_store "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/store/office.ts"
click node_data_source "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/data/source.ts"
click node_drawers "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/drawers/AgentDrawer.tsx"
click node_terminal_view "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/drawers/TerminalView.tsx"
click node_settings "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/settings/StackSettings.tsx"
click node_office_scene "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/OfficeScene.ts"
click node_layout "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/layout/layout.ts"
click node_office_store_ui "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/store/office.ts"
click node_palette "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/engine/palette.ts"
click node_tokens "https://github.com/jsmastery-pro/jsm-hq/blob/main/src/theme/tokens.ts"

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_server,node_hub,node_state,node_planner,node_action,node_inbox,node_http toneBlue
class node_sessions,node_workspace,node_backends,node_sandbox,node_setup,node_repo toneAmber
class node_github,node_mcp,node_stack toneMint
class node_browser,node_office_store,node_data_source,node_drawers,node_terminal_view,node_settings toneRose
class node_office_scene,node_layout,node_office_store_ui,node_palette,node_tokens,node_person toneIndigo
```

## Components

### HQ Control Plane

- [HQ launcher](https://github.com/jsmastery-pro/jsm-hq/blob/main/bin/jsm-hq.mjs): `bin/jsm-hq.mjs`
- [Server runtime](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/main.ts): `server/main.ts`
- [Team hub](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/hub.ts): `server/hub.ts`
- [HQ state](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/store.ts): `server/store.ts`
- [Task planning](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/planner.ts): `server/planner.ts`
- [Action items](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/actionItems.ts): `server/actionItems.ts`
- [Agent messaging](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/inbox.ts): `server/inbox.ts`
- [HTTP and live feed](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/http.ts): `server/http.ts`

### Agent Execution

- [Agent sessions](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/sessions.ts): `server/sessions.ts`
- [Agent workspaces](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/workspace.ts): `server/workspace.ts`
- [Terminal backends](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/backends/pty.ts): `server/backends/pty.ts`
- [Sandbox control](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/sbx.ts): `server/sbx.ts`
- [Setup checks](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/setup.ts): `server/setup.ts`
- [Repository operations](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/repo.ts): `server/repo.ts`

### Workflow Integrations

- [GitHub review sync](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/githubSync.ts): `server/githubSync.ts`
- [Agent MCP tools](https://github.com/jsmastery-pro/jsm-hq/blob/main/server/mcp.ts): `server/mcp.ts`
- [Stack and skills](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/data/stack.ts): `src/data/stack.ts`

### Office Client

- [HQ browser UI](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/App.tsx): `src/App.tsx`
- [Office data store](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/store/office.ts): `src/store/office.ts`
- [Data source contract](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/data/source.ts): `src/data/source.ts`
- [Agent and task drawers](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/drawers/AgentDrawer.tsx): `src/ui/drawers/AgentDrawer.tsx`
- [Terminal view](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/drawers/TerminalView.tsx): `src/ui/drawers/TerminalView.tsx`
- [Project settings](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/ui/settings/StackSettings.tsx): `src/ui/settings/StackSettings.tsx`

### Office Rendering

- [Office scene](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/OfficeScene.ts): `src/office/OfficeScene.ts`
- [Office layout](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/layout/layout.ts): `src/office/layout/layout.ts`
- [Office and UI state](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/store/office.ts): `src/store/office.ts`
- [Visual theme](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/office/engine/palette.ts): `src/office/engine/palette.ts`
- [Theme tokens](https://github.com/jsmastery-pro/jsm-hq/blob/main/src/theme/tokens.ts): `src/theme/tokens.ts`

### Other components

- **Project owner**

## Connections

- Project owner → HQ launcher: starts HQ
- HQ launcher → Server runtime: launches (evidence: `bin/jsm-hq.mjs`)
- Server runtime → Team hub: creates (evidence: `server/main.ts`)
- Server runtime → HTTP and live feed: starts (evidence: `server/main.ts`)
- Server runtime → GitHub review sync: starts sync (evidence: `server/main.ts`)
- Server runtime → Task planning: wires (evidence: `server/main.ts`)
- Server runtime → Agent messaging: wires (evidence: `server/main.ts`)
- Server runtime → Action items: wires (evidence: `server/main.ts`)
- Team hub → HQ state: reads and writes (evidence: `server/hub.ts`)
- Team hub → Repository operations: uses repo (evidence: `server/hub.ts`)
- Team hub → Task planning: exports plan (evidence: `server/hub.ts`)
- Agent sessions → Agent workspaces: prepares folder (evidence: `server/sessions.ts`)
- Agent sessions → Terminal backends: selects backend (evidence: `server/sessions.ts`)
- Agent sessions → Setup checks: runs checks (evidence: `server/sessions.ts`)
- Agent sessions → Sandbox control: queries sandbox (evidence: `server/sessions.ts`)
- Agent sessions → Stack and skills: installs skills (evidence: `server/sessions.ts`)
- GitHub review sync → Team hub: syncs PR state
- Project owner → HQ browser UI: configures and monitors
- HQ browser UI → Office data store: connects (evidence: `src/App.tsx`)
- Office data store → Data source contract: uses contract (evidence: `src/store/office.ts`)
- Office data store → HTTP and live feed: streams updates
- Office data store → Server runtime: sends commands
- HQ browser UI → Agent and task drawers: hosts drawers (evidence: `src/App.tsx`)
- Agent and task drawers → Terminal view: renders terminal (evidence: `src/ui/drawers/AgentDrawer.tsx`)
- Project settings → Stack and skills: configures stack
- HQ browser UI → Office scene: renders canvas (evidence: `src/App.tsx`)
- Office scene → Office layout: builds scene layout (evidence: `src/office/OfficeScene.ts`)
- Office scene → Office and UI state: reads state (evidence: `src/office/OfficeScene.ts`)
- Office scene → Visual theme: draws with (evidence: `src/office/OfficeScene.ts`)
- Office layout → Visual theme: uses palette (evidence: `src/office/layout/layout.ts`)
- Visual theme → Theme tokens: uses theme tokens (evidence: `src/office/engine/palette.ts`)
