# nerdatwork24x7/pi_scope architecture

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

- Interactive diagram: https://gitdiagram.com/nerdatwork24x7/pi_scope
- Repository: https://github.com/nerdatwork24x7/pi_scope

## Overview

Pi Scope is a local observability dashboard and control surface for AI coding-agent sessions. An agent extension—or another event-producing tool—sends telemetry to the server; the server stores events and broadcasts them for live viewing and replay. From the dashboard, users can also chat with an agent and operate on the host workspace through terminal, file review, checkpoints, and Git tools. The README documents these major capabilities; some endpoint wiring is not visible in the sampled excerpts, so uncertain links are omitted.

Main entry points: [`apps/scope/server.ts`](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/server.ts) (Scope server), [`apps/scope/public/app.js`](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/app.js) (Dashboard shell), [`apps/scope/stt.ts`](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/stt.ts) (Speech transcription), [`apps/scope-launcher/main.js`](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope-launcher/main.js) (Electron launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Telemetry capture"]
  node_extension["Pi extension<br/>[pi-scope.ts]"]
  node_capture_parser["LLM capture parser<br/>[capture.ts]"]
end

subgraph group_service["Local service"]
  node_server["Scope server<br/>[server.ts]"]
  node_database[("Event database<br/>[db.ts]")]
  node_types["Event model<br/>[types.ts]"]
  node_api_keys["API key settings<br/>[api-keys.ts]"]
end

subgraph group_dashboard["Browser dashboard"]
  node_dashboard_app["Dashboard shell<br/>[app.js]"]
  node_chat_ui["Chat view<br/>[chat.js]"]
  node_trajectory_ui["Trajectory view<br/>[trajectory.js]"]
  node_settings_ui["Settings view<br/>[settings.js]"]
  node_terminal_ui["Terminal view<br/>[terminal.js]"]
  node_files_ui["File review<br/>[files.js]"]
  node_git_ui["Git client<br/>[git.js]"]
  node_checkpoints_ui["Checkpoints view<br/>[checkpoints.js]"]
end

subgraph group_workspace["Workspace controls"]
  node_chat_runtime["Agent chat runtime<br/>[chat.ts]"]
  node_terminal_runtime["Shell service<br/>[terminal.ts]"]
  node_stt["Speech transcription<br/>[stt.ts]"]
  node_workspace_files[("Workspace files")]
  node_git_repo[("Git repository")]
end

subgraph group_desktop["Desktop launcher"]
  node_launcher["Electron launcher<br/>[main.js]"]
  node_server_control["Server lifecycle<br/>[scope-control.js]"]
end

node_developer(("Developer"))
node_agent(("Pi agent"))
node_other_tool(("Event producer"))
node_groq["Groq transcription API"]

node_developer -->|"runs"| node_agent
node_agent -->|"emits events"| node_extension
node_extension -->|"POSTs telemetry"| node_server
node_other_tool -->|"POSTs events"| node_server
node_other_tool -.->|"POSTs LLM payloads"| node_server
node_server -->|"parses payloads"| node_capture_parser
node_server -->|"stores events"| node_database
node_server -->|"reads sessions"| node_database
node_server -->|"streams events"| node_dashboard_app
node_dashboard_app -->|"requests data"| node_server
node_developer -->|"uses"| node_dashboard_app
node_chat_ui -->|"sends prompts"| node_server
node_server -->|"dispatches chat"| node_chat_runtime
node_chat_runtime -->|"controls process"| node_agent
node_trajectory_ui -->|"requests history"| node_server
node_settings_ui -->|"reads and updates"| node_server
node_server -->|"reads keys"| node_api_keys
node_terminal_ui -->|"opens terminal"| node_server
node_server -->|"handles terminal"| node_terminal_runtime
node_terminal_runtime -->|"runs shell commands"| node_workspace_files
node_files_ui -->|"requests file diffs"| node_server
node_server -->|"reads and writes"| node_workspace_files
node_git_ui -->|"requests Git actions"| node_server
node_server -->|"runs Git operations"| node_git_repo
node_checkpoints_ui -->|"manages checkpoints"| node_server
node_server -->|"creates and restores"| node_git_repo
node_server -->|"handles transcription"| node_stt
node_stt -->|"reads stored key"| node_api_keys
node_stt -->|"sends audio"| node_groq
node_launcher -->|"starts server"| node_server_control
node_server_control -->|"spawns or reuses"| node_server
node_launcher -->|"opens dashboard"| node_dashboard_app

click node_extension "https://github.com/nerdatwork24x7/pi_scope/blob/main/extension/pi-scope.ts"
click node_capture_parser "https://github.com/nerdatwork24x7/pi_scope/blob/main/shared/capture.ts"
click node_server "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/server.ts"
click node_database "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/db.ts"
click node_types "https://github.com/nerdatwork24x7/pi_scope/blob/main/shared/types.ts"
click node_api_keys "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/api-keys.ts"
click node_dashboard_app "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/app.js"
click node_chat_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/chat.js"
click node_trajectory_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/trajectory.js"
click node_settings_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/settings.js"
click node_terminal_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/terminal.js"
click node_files_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/files.js"
click node_git_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/git.js"
click node_checkpoints_ui "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/checkpoints.js"
click node_chat_runtime "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/chat.ts"
click node_terminal_runtime "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/terminal.ts"
click node_stt "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/stt.ts"
click node_launcher "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope-launcher/main.js"
click node_server_control "https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope-launcher/scope-control.js"

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_extension,node_capture_parser toneBlue
class node_server,node_database,node_types,node_api_keys toneAmber
class node_dashboard_app,node_chat_ui,node_trajectory_ui,node_settings_ui,node_terminal_ui,node_files_ui,node_git_ui,node_checkpoints_ui,node_groq toneMint
class node_chat_runtime,node_terminal_runtime,node_stt,node_workspace_files,node_git_repo toneRose
class node_launcher,node_server_control,node_developer,node_agent,node_other_tool toneIndigo
```

## Components

### Telemetry capture

- [Pi extension](https://github.com/nerdatwork24x7/pi_scope/blob/main/extension/pi-scope.ts): `extension/pi-scope.ts`
- [LLM capture parser](https://github.com/nerdatwork24x7/pi_scope/blob/main/shared/capture.ts): `shared/capture.ts`

### Local service

- [Scope server](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/server.ts): `apps/scope/server.ts`
- [Event database](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/db.ts): `apps/scope/db.ts`
- [Event model](https://github.com/nerdatwork24x7/pi_scope/blob/main/shared/types.ts): `shared/types.ts`
- [API key settings](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/api-keys.ts): `apps/scope/api-keys.ts`

### Browser dashboard

- [Dashboard shell](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/app.js): `apps/scope/public/app.js`
- [Chat view](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/chat.js): `apps/scope/public/chat.js`
- [Trajectory view](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/trajectory.js): `apps/scope/public/trajectory.js`
- [Settings view](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/settings.js): `apps/scope/public/settings.js`
- [Terminal view](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/terminal.js): `apps/scope/public/terminal.js`
- [File review](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/files.js): `apps/scope/public/files.js`
- [Git client](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/git.js): `apps/scope/public/git.js`
- [Checkpoints view](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/public/checkpoints.js): `apps/scope/public/checkpoints.js`

### Workspace controls

- [Agent chat runtime](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/chat.ts): `apps/scope/chat.ts`
- [Shell service](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/terminal.ts): `apps/scope/terminal.ts`
- [Speech transcription](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope/stt.ts): `apps/scope/stt.ts`
- **Workspace files**
- **Git repository**

### Desktop launcher

- [Electron launcher](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope-launcher/main.js): `apps/scope-launcher/main.js`
- [Server lifecycle](https://github.com/nerdatwork24x7/pi_scope/blob/main/apps/scope-launcher/scope-control.js): `apps/scope-launcher/scope-control.js`

### Other components

- **Developer**
- **Pi agent**
- **Event producer**
- **Groq transcription API**

## Connections

- Developer → Pi agent: runs
- Pi agent → Pi extension: emits events
- Pi extension → Scope server: POSTs telemetry
- Event producer → Scope server: POSTs events
- Event producer → Scope server: POSTs LLM payloads
- Scope server → LLM capture parser: parses payloads
- Scope server → Event database: stores events
- Scope server → Event database: reads sessions
- Scope server → Dashboard shell: streams events
- Dashboard shell → Scope server: requests data
- Developer → Dashboard shell: uses
- Chat view → Scope server: sends prompts
- Scope server → Agent chat runtime: dispatches chat
- Agent chat runtime → Pi agent: controls process
- Trajectory view → Scope server: requests history
- Settings view → Scope server: reads and updates
- Scope server → API key settings: reads keys
- Terminal view → Scope server: opens terminal
- Scope server → Shell service: handles terminal
- Shell service → Workspace files: runs shell commands
- File review → Scope server: requests file diffs
- Scope server → Workspace files: reads and writes
- Git client → Scope server: requests Git actions
- Scope server → Git repository: runs Git operations
- Checkpoints view → Scope server: manages checkpoints
- Scope server → Git repository: creates and restores
- Scope server → Speech transcription: handles transcription
- Speech transcription → API key settings: reads stored key
- Speech transcription → Groq transcription API: sends audio
- Electron launcher → Server lifecycle: starts server
- Server lifecycle → Scope server: spawns or reuses
- Electron launcher → Dashboard shell: opens dashboard