# jmfederico/pi-web architecture

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

- Interactive diagram: https://gitdiagram.com/jmfederico/pi-web
- Repository: https://github.com/jmfederico/pi-web
- Video tour (about a minute): https://gitdiagram.com/jmfederico/pi-web/video

## Overview

PI WEB is a browser control surface for persistent Pi Coding Agent sessions running in real workspaces on local or remote machines. The principal flow is to select a machine, create or choose a project and workspace, start a session, and supervise the agent; sessions continue when the browser disconnects. The product also exposes workspace files, terminals, Git, plugins, and remote-machine resources. The README supports these capability-level relationships; sampled source confirms workspace file routing, preview handling, and federation details, but not every subsystem’s internal wiring.

Main entry points: [`src/server/app.ts`](https://github.com/jmfederico/pi-web/blob/main/src/server/app.ts) (HTTP server), [`src/client/src/api.ts`](https://github.com/jmfederico/pi-web/blob/main/src/client/src/api.ts) (Client API), [`src/server/workspaceExplorerRoutes.ts`](https://github.com/jmfederico/pi-web/blob/main/src/server/workspaceExplorerRoutes.ts) (Workspace file routes), [`src/server/sessions/piSessionService.ts`](https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/piSessionService.ts) (Session service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Browser control"]
  node_browser["Web interface<br/>[main.ts]"]
  node_client_api["Client API<br/>[api.ts]"]
  node_machine_ui["Machine controls"]
  node_workspace_ui["Workspace browser<br/>[WorkspacePanel.ts]"]
  node_session_ui["Session controls"]
end

subgraph group_runtime["Machine runtime"]
  node_server["HTTP server<br/>[app.ts]"]
  node_machine_service["Machine service<br/>[machineService.ts]"]
  node_machine_store[("Machine registry<br/>[machineStore.ts]")]
  node_sessiond_client["Daemon client"]
  node_sessiond["Session daemon<br/>[sessiond.ts]"]
end

subgraph group_workspaces["Projects and files"]
  node_projects["Project management<br/>[projectService.ts]"]
  node_workspace_catalog["Workspace catalog"]
  node_workspace_routes["Workspace file routes"]
  node_file_preview["File preview"]
end

subgraph group_sessions["Agent sessions"]
  node_session_routes["Session routes<br/>[sessionRoutes.ts]"]
  node_session_service["Session service"]
  node_session_files[("Session archive")]
end

subgraph group_extensions["Tools and federation"]
  node_terminal["Terminal plugin<br/>[pi-web-plugin.ts]"]
  node_git["Git plugin<br/>[pi-web-plugin.ts]"]
  node_plugin_lifecycle["Plugin lifecycle"]
  node_machine_proxy["Remote machine proxy"]
end

node_user(("Developer"))
node_pi_agent["Pi Coding Agent"]
node_remote_machine["Remote PI WEB"]

node_user -->|"controls"| node_browser
node_browser -->|"requests"| node_client_api
node_client_api -->|"calls API"| node_server
node_browser -->|"selects machine"| node_machine_ui
node_machine_ui -->|"manages"| node_machine_service
node_machine_service -->|"reads and writes"| node_machine_store
node_server -->|"routes project work"| node_projects
node_projects -->|"resolves workspaces"| node_workspace_catalog
node_workspace_ui -->|"requests files"| node_client_api
node_server -->|"registers routes"| node_workspace_routes
node_workspace_routes -->|"resolves context"| node_workspace_catalog
node_workspace_routes -->|"reads previews"| node_file_preview
node_workspace_routes -->|"returns file data"| node_workspace_ui
node_session_ui -->|"starts sessions"| node_client_api
node_server -->|"routes sessions"| node_session_routes
node_session_routes -->|"dispatches"| node_session_service
node_session_service -->|"uses daemon"| node_sessiond_client
node_sessiond_client -->|"sends requests"| node_sessiond
node_sessiond -->|"runs agent"| node_pi_agent
node_session_service -->|"archives sessions"| node_session_files
node_session_service -->|"streams session updates"| node_session_ui
node_user -->|"browses workspace"| node_workspace_ui
node_user -->|"uses terminal"| node_terminal
node_user -->|"reviews Git"| node_git
node_server -->|"manages plugins"| node_plugin_lifecycle
node_machine_proxy -.->|"proxies requests"| node_remote_machine
node_server -.->|"routes federated calls"| node_machine_proxy
node_client_api -.->|"targets selected machine"| node_machine_proxy

click node_browser "https://github.com/jmfederico/pi-web/blob/main/src/client/src/main.ts"
click node_client_api "https://github.com/jmfederico/pi-web/blob/main/src/client/src/api.ts"
click node_server "https://github.com/jmfederico/pi-web/blob/main/src/server/app.ts"
click node_machine_ui "https://github.com/jmfederico/pi-web/blob/main/src/client/src/controllers/machineController.ts"
click node_machine_service "https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineService.ts"
click node_machine_store "https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineStore.ts"
click node_projects "https://github.com/jmfederico/pi-web/blob/main/src/server/projects/projectService.ts"
click node_workspace_catalog "https://github.com/jmfederico/pi-web/blob/main/src/server/workspaces/workspaceCatalog.ts"
click node_workspace_routes "https://github.com/jmfederico/pi-web/blob/main/src/server/workspaceExplorerRoutes.ts"
click node_file_preview "https://github.com/jmfederico/pi-web/blob/main/src/server/workspaces/filePreviewService.ts"
click node_workspace_ui "https://github.com/jmfederico/pi-web/blob/main/src/client/src/components/WorkspacePanel.ts"
click node_session_ui "https://github.com/jmfederico/pi-web/blob/main/src/client/src/controllers/sessionController.ts"
click node_session_routes "https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/sessionRoutes.ts"
click node_session_service "https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/piSessionService.ts"
click node_session_files "https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/sessionArchiveStore.ts"
click node_sessiond_client "https://github.com/jmfederico/pi-web/blob/main/src/sessiond/sessionDaemonClient.ts"
click node_sessiond "https://github.com/jmfederico/pi-web/blob/main/src/server/sessiond.ts"
click node_terminal "https://github.com/jmfederico/pi-web/blob/main/pi-web-plugins/terminal/pi-web-plugin.ts"
click node_git "https://github.com/jmfederico/pi-web/blob/main/pi-web-plugins/git/browser/pi-web-plugin.ts"
click node_plugin_lifecycle "https://github.com/jmfederico/pi-web/blob/main/src/server/piWebPluginLifecycle.ts"
click node_machine_proxy "https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineProxyRoutes.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_browser,node_client_api,node_machine_ui,node_workspace_ui,node_session_ui toneBlue
class node_server,node_machine_service,node_machine_store,node_sessiond_client,node_sessiond toneAmber
class node_projects,node_workspace_catalog,node_workspace_routes,node_file_preview toneMint
class node_session_routes,node_session_service,node_session_files toneRose
class node_terminal,node_git,node_plugin_lifecycle,node_machine_proxy,node_user,node_pi_agent,node_remote_machine toneIndigo
```

## Components

### Browser control

- [Web interface](https://github.com/jmfederico/pi-web/blob/main/src/client/src/main.ts): `src/client/src/main.ts`
- [Client API](https://github.com/jmfederico/pi-web/blob/main/src/client/src/api.ts): `src/client/src/api.ts`
- [Machine controls](https://github.com/jmfederico/pi-web/blob/main/src/client/src/controllers/machineController.ts): `src/client/src/controllers/machineController.ts`
- [Workspace browser](https://github.com/jmfederico/pi-web/blob/main/src/client/src/components/WorkspacePanel.ts): `src/client/src/components/WorkspacePanel.ts`
- [Session controls](https://github.com/jmfederico/pi-web/blob/main/src/client/src/controllers/sessionController.ts): `src/client/src/controllers/sessionController.ts`

### Machine runtime

- [HTTP server](https://github.com/jmfederico/pi-web/blob/main/src/server/app.ts): `src/server/app.ts`
- [Machine service](https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineService.ts): `src/server/machines/machineService.ts`
- [Machine registry](https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineStore.ts): `src/server/machines/machineStore.ts`
- [Daemon client](https://github.com/jmfederico/pi-web/blob/main/src/sessiond/sessionDaemonClient.ts): `src/sessiond/sessionDaemonClient.ts`
- [Session daemon](https://github.com/jmfederico/pi-web/blob/main/src/server/sessiond.ts): `src/server/sessiond.ts`

### Projects and files

- [Project management](https://github.com/jmfederico/pi-web/blob/main/src/server/projects/projectService.ts): `src/server/projects/projectService.ts`
- [Workspace catalog](https://github.com/jmfederico/pi-web/blob/main/src/server/workspaces/workspaceCatalog.ts): `src/server/workspaces/workspaceCatalog.ts`
- [Workspace file routes](https://github.com/jmfederico/pi-web/blob/main/src/server/workspaceExplorerRoutes.ts): `src/server/workspaceExplorerRoutes.ts`
- [File preview](https://github.com/jmfederico/pi-web/blob/main/src/server/workspaces/filePreviewService.ts): `src/server/workspaces/filePreviewService.ts`

### Agent sessions

- [Session routes](https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/sessionRoutes.ts): `src/server/sessions/sessionRoutes.ts`
- [Session service](https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/piSessionService.ts): `src/server/sessions/piSessionService.ts`
- [Session archive](https://github.com/jmfederico/pi-web/blob/main/src/server/sessions/sessionArchiveStore.ts): `src/server/sessions/sessionArchiveStore.ts`

### Tools and federation

- [Terminal plugin](https://github.com/jmfederico/pi-web/blob/main/pi-web-plugins/terminal/pi-web-plugin.ts): `pi-web-plugins/terminal/pi-web-plugin.ts`
- [Git plugin](https://github.com/jmfederico/pi-web/blob/main/pi-web-plugins/git/browser/pi-web-plugin.ts): `pi-web-plugins/git/browser/pi-web-plugin.ts`
- [Plugin lifecycle](https://github.com/jmfederico/pi-web/blob/main/src/server/piWebPluginLifecycle.ts): `src/server/piWebPluginLifecycle.ts`
- [Remote machine proxy](https://github.com/jmfederico/pi-web/blob/main/src/server/machines/machineProxyRoutes.ts): `src/server/machines/machineProxyRoutes.ts`

### Other components

- **Developer**
- **Pi Coding Agent**
- **Remote PI WEB**

## Connections

- Developer → Web interface: controls
- Web interface → Client API: requests
- Client API → HTTP server: calls API
- Web interface → Machine controls: selects machine
- Machine controls → Machine service: manages
- Machine service → Machine registry: reads and writes
- HTTP server → Project management: routes project work
- Project management → Workspace catalog: resolves workspaces
- Workspace browser → Client API: requests files
- HTTP server → Workspace file routes: registers routes
- Workspace file routes → Workspace catalog: resolves context
- Workspace file routes → File preview: reads previews
- Workspace file routes → Workspace browser: returns file data
- Session controls → Client API: starts sessions
- HTTP server → Session routes: routes sessions
- Session routes → Session service: dispatches
- Session service → Daemon client: uses daemon
- Daemon client → Session daemon: sends requests
- Session daemon → Pi Coding Agent: runs agent
- Session service → Session archive: archives sessions
- Session service → Session controls: streams session updates
- Developer → Workspace browser: browses workspace
- Developer → Terminal plugin: uses terminal
- Developer → Git plugin: reviews Git
- HTTP server → Plugin lifecycle: manages plugins
- Remote machine proxy → Remote PI WEB: proxies requests
- HTTP server → Remote machine proxy: routes federated calls
- Client API → Remote machine proxy: targets selected machine