# herockone/pi-web architecture

> Architecture diagram of the GitHub repository herockone/pi-web, 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/herockone/pi-web
- Repository: https://github.com/herockone/pi-web

## Overview

Pi Web is a local browser workspace for the pi coding agent. The main workflow is selecting a project and session, composing a prompt, sending it through the agent API to the live pi session, and viewing streamed events and results. Separate branches cover session history, project files and Git worktrees, model and resource configuration, and usage reporting. The README documents these capabilities; the sampled source confirms selected route-to-library calls, but not all UI-to-route wiring, so uncertain links are omitted.

Main entry points: [`app/page.tsx`](https://github.com/herockone/pi-web/blob/main/app/page.tsx) (Workspace page), [`components/SessionSidebar.tsx`](https://github.com/herockone/pi-web/blob/main/components/SessionSidebar.tsx) (Project navigation), [`components/SettingsPanel.tsx`](https://github.com/herockone/pi-web/blob/main/components/SettingsPanel.tsx) (Settings panels), [`hooks/useAgentSession.ts`](https://github.com/herockone/pi-web/blob/main/hooks/useAgentSession.ts) (Session interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Session workspace"]
  node_home["Workspace page<br/>[page.tsx]"]
  node_chat["Chat interface<br/>[ChatWindow.tsx]"]
  node_sessionhook["Session interaction<br/>[useAgentSession.ts]"]
  node_sessionapi["Session routes<br/>[route.ts]"]
  node_sessiondetail["Session detail<br/>[route.ts]"]
  node_sessiondata[("Pi session files<br/>[session-reader.ts]")]
end

subgraph group_agent["Agent runtime"]
  node_agentapi["Agent routes<br/>[route.ts]"]
  node_rpc["Agent RPC manager<br/>[rpc-manager.ts]"]
  node_agentclient["Agent event client"]
  node_piagent["Pi agent runtime"]
end

subgraph group_project["Project tools"]
  node_projectui["Project navigation<br/>[SessionSidebar.tsx]"]
  node_filesapi["File access routes<br/>[route.ts]"]
  node_fileindex["File index route<br/>[route.ts]"]
  node_gitapi["Git routes<br/>[route.ts]"]
  node_worktreesapi["Worktree routes<br/>[route.ts]"]
  node_worktree["Worktree operations<br/>[worktree.ts]"]
end

subgraph group_configuration["Models and resources"]
  node_settingsui["Settings panels<br/>[SettingsPanel.tsx]"]
  node_modelsapi["Model routes<br/>[route.ts]"]
  node_enabledapi["Enabled models<br/>[route.ts]"]
  node_pluginsapi["Plugin management<br/>[route.ts]"]
  node_skillsapi["Skills management<br/>[route.ts]"]
end

subgraph group_usage["Usage reporting"]
  node_usageui["Usage dashboard<br/>[UsageStats.tsx]"]
  node_usageapi["Usage statistics<br/>[route.ts]"]
  node_usagefiles[("Usage records<br/>[usage-stats.ts]")]
  node_balances[("Provider balances<br/>[usage-balances.ts]")]
end

node_user(("Browser user"))

node_user -->|"opens workspace"| node_home
node_home -->|"shows chat"| node_chat
node_chat -->|"submits prompts"| node_sessionhook
node_sessionhook -->|"sends commands"| node_agentapi
node_agentapi -->|"dispatches RPC"| node_rpc
node_rpc -->|"controls session"| node_piagent
node_piagent -->|"emits events"| node_rpc
node_sessionhook -->|"connects events"| node_agentclient
node_agentclient -->|"receives stream"| node_agentapi
node_home -->|"loads sessions"| node_sessionapi
node_sessionapi -->|"reads history"| node_sessiondata
node_sessiondetail -->|"reads and updates"| node_sessiondata
node_home -->|"browses projects"| node_projectui
node_projectui -->|"requests files"| node_filesapi
node_projectui -->|"searches files"| node_fileindex
node_projectui -->|"checks Git"| node_gitapi
node_projectui -->|"manages worktrees"| node_worktreesapi
node_worktreesapi -->|"calls operations"| node_worktree
node_settingsui -->|"loads models"| node_modelsapi
node_settingsui -->|"sets availability"| node_enabledapi
node_settingsui -->|"manages plugins"| node_pluginsapi
node_settingsui -->|"manages skills"| node_skillsapi
node_home -->|"shows usage"| node_usageui
node_usageui -->|"requests statistics"| node_usageapi
node_usageapi -->|"reads analytics"| node_usagefiles
node_usageapi -->|"computes and saves"| node_balances

click node_home "https://github.com/herockone/pi-web/blob/main/app/page.tsx"
click node_chat "https://github.com/herockone/pi-web/blob/main/components/ChatWindow.tsx"
click node_sessionhook "https://github.com/herockone/pi-web/blob/main/hooks/useAgentSession.ts"
click node_sessionapi "https://github.com/herockone/pi-web/blob/main/app/api/sessions/route.ts"
click node_sessiondetail "https://github.com/herockone/pi-web/blob/main/app/api/sessions/%5Bid%5D/route.ts"
click node_sessiondata "https://github.com/herockone/pi-web/blob/main/lib/session-reader.ts"
click node_agentapi "https://github.com/herockone/pi-web/blob/main/app/api/agent/%5Bid%5D/route.ts"
click node_rpc "https://github.com/herockone/pi-web/blob/main/lib/rpc-manager.ts"
click node_agentclient "https://github.com/herockone/pi-web/blob/main/lib/agent-event-connection.ts"
click node_projectui "https://github.com/herockone/pi-web/blob/main/components/SessionSidebar.tsx"
click node_filesapi "https://github.com/herockone/pi-web/blob/main/app/api/files/%5B...path%5D/route.ts"
click node_fileindex "https://github.com/herockone/pi-web/blob/main/app/api/file-index/route.ts"
click node_gitapi "https://github.com/herockone/pi-web/blob/main/app/api/git/status/route.ts"
click node_worktreesapi "https://github.com/herockone/pi-web/blob/main/app/api/worktrees/route.ts"
click node_worktree "https://github.com/herockone/pi-web/blob/main/lib/worktree.ts"
click node_settingsui "https://github.com/herockone/pi-web/blob/main/components/SettingsPanel.tsx"
click node_modelsapi "https://github.com/herockone/pi-web/blob/main/app/api/models/route.ts"
click node_enabledapi "https://github.com/herockone/pi-web/blob/main/app/api/models/enabled/route.ts"
click node_pluginsapi "https://github.com/herockone/pi-web/blob/main/app/api/plugins/route.ts"
click node_skillsapi "https://github.com/herockone/pi-web/blob/main/app/api/skills/route.ts"
click node_usageui "https://github.com/herockone/pi-web/blob/main/components/UsageStats.tsx"
click node_usageapi "https://github.com/herockone/pi-web/blob/main/app/api/usage-stats/route.ts"
click node_usagefiles "https://github.com/herockone/pi-web/blob/main/lib/usage-stats.ts"
click node_balances "https://github.com/herockone/pi-web/blob/main/lib/usage-balances.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_home,node_chat,node_sessionhook,node_sessionapi,node_sessiondetail,node_sessiondata,node_user toneBlue
class node_agentapi,node_rpc,node_agentclient,node_piagent toneAmber
class node_projectui,node_filesapi,node_fileindex,node_gitapi,node_worktreesapi,node_worktree toneMint
class node_settingsui,node_modelsapi,node_enabledapi,node_pluginsapi,node_skillsapi toneRose
class node_usageui,node_usageapi,node_usagefiles,node_balances toneIndigo
```

## Components

### Session workspace

- [Workspace page](https://github.com/herockone/pi-web/blob/main/app/page.tsx): `app/page.tsx`
- [Chat interface](https://github.com/herockone/pi-web/blob/main/components/ChatWindow.tsx): `components/ChatWindow.tsx`
- [Session interaction](https://github.com/herockone/pi-web/blob/main/hooks/useAgentSession.ts): `hooks/useAgentSession.ts`
- [Session routes](https://github.com/herockone/pi-web/blob/main/app/api/sessions/route.ts): `app/api/sessions/route.ts`
- [Session detail](https://github.com/herockone/pi-web/blob/main/app/api/sessions/%5Bid%5D/route.ts): `app/api/sessions/[id]/route.ts`
- [Pi session files](https://github.com/herockone/pi-web/blob/main/lib/session-reader.ts): `lib/session-reader.ts`

### Agent runtime

- [Agent routes](https://github.com/herockone/pi-web/blob/main/app/api/agent/%5Bid%5D/route.ts): `app/api/agent/[id]/route.ts`
- [Agent RPC manager](https://github.com/herockone/pi-web/blob/main/lib/rpc-manager.ts): `lib/rpc-manager.ts`
- [Agent event client](https://github.com/herockone/pi-web/blob/main/lib/agent-event-connection.ts): `lib/agent-event-connection.ts`
- **Pi agent runtime**

### Project tools

- [Project navigation](https://github.com/herockone/pi-web/blob/main/components/SessionSidebar.tsx): `components/SessionSidebar.tsx`
- [File access routes](https://github.com/herockone/pi-web/blob/main/app/api/files/%5B...path%5D/route.ts): `app/api/files/[...path]/route.ts`
- [File index route](https://github.com/herockone/pi-web/blob/main/app/api/file-index/route.ts): `app/api/file-index/route.ts`
- [Git routes](https://github.com/herockone/pi-web/blob/main/app/api/git/status/route.ts): `app/api/git/status/route.ts`
- [Worktree routes](https://github.com/herockone/pi-web/blob/main/app/api/worktrees/route.ts): `app/api/worktrees/route.ts`
- [Worktree operations](https://github.com/herockone/pi-web/blob/main/lib/worktree.ts): `lib/worktree.ts`

### Models and resources

- [Settings panels](https://github.com/herockone/pi-web/blob/main/components/SettingsPanel.tsx): `components/SettingsPanel.tsx`
- [Model routes](https://github.com/herockone/pi-web/blob/main/app/api/models/route.ts): `app/api/models/route.ts`
- [Enabled models](https://github.com/herockone/pi-web/blob/main/app/api/models/enabled/route.ts): `app/api/models/enabled/route.ts`
- [Plugin management](https://github.com/herockone/pi-web/blob/main/app/api/plugins/route.ts): `app/api/plugins/route.ts`
- [Skills management](https://github.com/herockone/pi-web/blob/main/app/api/skills/route.ts): `app/api/skills/route.ts`

### Usage reporting

- [Usage dashboard](https://github.com/herockone/pi-web/blob/main/components/UsageStats.tsx): `components/UsageStats.tsx`
- [Usage statistics](https://github.com/herockone/pi-web/blob/main/app/api/usage-stats/route.ts): `app/api/usage-stats/route.ts`
- [Usage records](https://github.com/herockone/pi-web/blob/main/lib/usage-stats.ts): `lib/usage-stats.ts`
- [Provider balances](https://github.com/herockone/pi-web/blob/main/lib/usage-balances.ts): `lib/usage-balances.ts`

### Other components

- **Browser user**

## Connections

- Browser user → Workspace page: opens workspace
- Workspace page → Chat interface: shows chat
- Chat interface → Session interaction: submits prompts
- Session interaction → Agent routes: sends commands
- Agent routes → Agent RPC manager: dispatches RPC
- Agent RPC manager → Pi agent runtime: controls session
- Pi agent runtime → Agent RPC manager: emits events
- Session interaction → Agent event client: connects events
- Agent event client → Agent routes: receives stream
- Workspace page → Session routes: loads sessions
- Session routes → Pi session files: reads history
- Session detail → Pi session files: reads and updates
- Workspace page → Project navigation: browses projects
- Project navigation → File access routes: requests files
- Project navigation → File index route: searches files
- Project navigation → Git routes: checks Git
- Project navigation → Worktree routes: manages worktrees
- Worktree routes → Worktree operations: calls operations
- Settings panels → Model routes: loads models
- Settings panels → Enabled models: sets availability
- Settings panels → Plugin management: manages plugins
- Settings panels → Skills management: manages skills
- Workspace page → Usage dashboard: shows usage
- Usage dashboard → Usage statistics: requests statistics
- Usage statistics → Usage records: reads analytics
- Usage statistics → Provider balances: computes and saves