# ayuayue/pideck architecture

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

- Interactive diagram: https://gitdiagram.com/ayuayue/pideck
- Repository: https://github.com/ayuayue/pideck

## Overview

#### Purpose and runtime model
PiDeck is a local Electron desktop workbench for managing multiple `pi` coding-agent sessions across project directories. It is not an agent implementation: each Agent tab owns an isolated `pi --mode rpc` subprocess and project cwd. Electron main owns privileged operations; React renders the workspace; preload exposes a constrained IPC surface.

Entry points: `src/main/index.ts`, `src/preload/index.ts`, `src/renderer/src/main.tsx`, and `src/renderer/src/App.tsx`.

#### Process, RPC, and agent lifecycle
The main process locates the externally installed `pi` CLI, starts/stops RPC subprocesses, translates RPC events into application state, gates streaming, and preserves per-agent lifecycle state. This is the core boundary between PiDeck and the external pi runtime.

Grounding: `src/main/pi/AgentManager.ts`, `src/main/pi/PiProcess.ts`, `src/main/pi/PiRpcClient.ts`.

#### Desktop IPC boundary
Renderer code does not directly access Node, filesystem, subprocesses, or Electron APIs. Shared IPC channel names/types define the contract; preload publishes the desktop API; main handlers route calls to domain services. The renderer has a browser-preview fallback when this API is absent, but real agent/project behavior requires Electron.

Grounding: `src/shared/ipc.ts`, `src/shared/types.ts`, `src/preload/index.ts`.

#### Workspace, sessions, and local resources
Projects are persisted independently from active agents. Main-process services manage project records, scan/import native pi and external Codex/Claude/OpenCode sessions, and operate on project files, Git worktrees/branches, prompts, skills, and extensions. These services are the persistence and local-machine boundary.

Grounding: `src/main/projects/ProjectStore.ts`, `src/main/sessions/SessionScanner.ts`, `src/main/fs/FileSystemService.ts`.

#### Interactive desktop workspace
The React shell coordinates project/agent selection, streamed chat timeline, composer behavior, files/history/configuration drawers, Git and browser panels, and session-specific terminal docking. It consumes the preload API and shared data contracts rather than spawning agents itself.

Grounding: `src/renderer/src/App.tsx`, `src/renderer/src/components/app/AppParts.tsx`, `src/renderer/src/components/app/RichInput.tsx`.

#### Native integrations and optional surfaces
Electron main manages pty-backed terminals, native editor detection, desktop proxy settings, WSL path/environment handling, local LAN web serving, tray/window behavior, and pet overlay windows. Git is accessed locally; `pi` is an external executable; optional Feishu integration bridges remote card interactions to agent/session operations.

Grounding: `src/main/terminal/TerminalSessionManager.ts`, `src/main/wsl/WslEnvironment.ts`, `src/main/feishu/FeishuBridge.ts`.

#### Configuration, extensibility, and external services
Configuration management reads/writes pi configuration and supports provider/model testing. Skills and extensions are managed at global/project scope, including bundled extensions. The application can query GitHub Releases for updates, sends opt-out anonymous heartbeat telemetry, and supports prompt/skill store discovery; model/provider credentials remain configured through pi-facing settings.

Grounding: `src/main/config/ConfigManager.ts`, `src/main/extensions/ExtensionManager.ts`, `src/main/telemetry/TelemetryService.ts`.

Main entry points: [`src/main/index.ts`](https://github.com/ayuayue/pideck/blob/main/src/main/index.ts) (Main entry), [`src/renderer/src/App.tsx`](https://github.com/ayuayue/pideck/blob/main/src/renderer/src/App.tsx) (Workspace shell), [`src/main/pi/PiProcess.ts`](https://github.com/ayuayue/pideck/blob/main/src/main/pi/PiProcess.ts) (Pi process), [`src/main/pi/AgentManager.ts`](https://github.com/ayuayue/pideck/blob/main/src/main/pi/AgentManager.ts) (Agent manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer workspace"]
  node_react_entry["React entry<br/>renderer entry<br/>[main.tsx]"]
  node_workspace_shell["Workspace shell<br/>React application<br/>[App.tsx]"]
  node_workspace_components["Workspace UI<br/>React components<br/>[AppParts.tsx]"]
  node_rich_input["Rich composer<br/>input component<br/>[RichInput.tsx]"]
end

subgraph group_ipc["Desktop IPC"]
  node_ipc_contract["IPC contract<br/>shared channels<br/>[ipc.ts]"]
  node_shared_types["Shared data types<br/>shared models<br/>[types.ts]"]
  node_preload_api{{"Preload API<br/>IPC bridge<br/>[index.ts]"}}
end

subgraph group_main["Electron main"]
  node_main_entry["Main entry<br/>Electron main<br/>[index.ts]"]
  node_agent_manager["Agent manager<br/>agent lifecycle<br/>[AgentManager.ts]"]
  node_pi_process["Pi process<br/>subprocess launcher<br/>[PiProcess.ts]"]
  node_pi_rpc["Pi RPC client<br/>RPC transport<br/>[PiRpcClient.ts]"]
  node_project_store[("Project store<br/>local persistence<br/>[ProjectStore.ts]")]
  node_session_scanner["Session scanner<br/>session import<br/>[SessionScanner.ts]"]
  node_filesystem["Local resource service<br/>filesystem and Git"]
  node_terminal_manager["Terminal manager<br/>PTY sessions"]
  node_config_manager["Pi configuration<br/>settings service<br/>[ConfigManager.ts]"]
  node_extension_manager["Extensions and skills<br/>extensibility service"]
  node_wsl_environment["WSL environment<br/>platform adapter<br/>[WslEnvironment.ts]"]
  node_feishu_bridge["Feishu bridge<br/>remote integration<br/>[FeishuBridge.ts]"]
  node_telemetry["Telemetry service<br/>heartbeat client"]
end

subgraph group_external["Local and remote integrations"]
  node_pi_cli{{"pi CLI<br/>external agent runtime"}}
  node_local_machine[("Projects and Git<br/>local machine resources")]
  node_remote_services["Remote services<br/>optional network services"]
end

node_react_entry -->|"mounts"| node_workspace_shell
node_workspace_shell -->|"composes"| node_workspace_components
node_workspace_components -->|"includes"| node_rich_input
node_workspace_shell -->|"uses desktop API"| node_preload_api
node_preload_api -->|"implements"| node_ipc_contract
node_preload_api -->|"invokes and receives events"| node_main_entry
node_shared_types -->|"models UI state"| node_workspace_shell
node_shared_types -->|"models IPC payloads"| node_main_entry
node_main_entry -->|"routes agent operations"| node_agent_manager
node_main_entry -->|"routes project operations"| node_project_store
node_main_entry -->|"routes session imports"| node_session_scanner
node_main_entry -->|"routes local resource operations"| node_filesystem
node_main_entry -->|"routes terminal operations"| node_terminal_manager
node_main_entry -->|"routes settings operations"| node_config_manager
node_main_entry -->|"routes extensibility operations"| node_extension_manager
node_agent_manager -->|"starts and stops"| node_pi_process
node_pi_process -->|"launches per-agent RPC process"| node_pi_cli
node_pi_process -->|"connects RPC transport"| node_pi_rpc
node_pi_rpc -->|"streams RPC events"| node_agent_manager
node_project_store -->|"persists project records"| node_local_machine
node_session_scanner -->|"scans sessions"| node_local_machine
node_filesystem -->|"manages files and Git"| node_local_machine
node_wsl_environment -.->|"adapts WSL execution"| node_pi_process
node_feishu_bridge -->|"forwards card actions"| node_agent_manager
node_config_manager -.->|"configures providers"| node_pi_cli
node_telemetry -->|"sends opt-out heartbeat"| node_remote_services
node_main_entry -.->|"checks updates and discovery"| node_remote_services

click node_react_entry "https://github.com/ayuayue/pideck/blob/main/src/renderer/src/main.tsx"
click node_workspace_shell "https://github.com/ayuayue/pideck/blob/main/src/renderer/src/App.tsx"
click node_workspace_components "https://github.com/ayuayue/pideck/blob/main/src/renderer/src/components/app/AppParts.tsx"
click node_rich_input "https://github.com/ayuayue/pideck/blob/main/src/renderer/src/components/app/RichInput.tsx"
click node_ipc_contract "https://github.com/ayuayue/pideck/blob/main/src/shared/ipc.ts"
click node_shared_types "https://github.com/ayuayue/pideck/blob/main/src/shared/types.ts"
click node_preload_api "https://github.com/ayuayue/pideck/blob/main/src/preload/index.ts"
click node_main_entry "https://github.com/ayuayue/pideck/blob/main/src/main/index.ts"
click node_agent_manager "https://github.com/ayuayue/pideck/blob/main/src/main/pi/AgentManager.ts"
click node_pi_process "https://github.com/ayuayue/pideck/blob/main/src/main/pi/PiProcess.ts"
click node_pi_rpc "https://github.com/ayuayue/pideck/blob/main/src/main/pi/PiRpcClient.ts"
click node_project_store "https://github.com/ayuayue/pideck/blob/main/src/main/projects/ProjectStore.ts"
click node_session_scanner "https://github.com/ayuayue/pideck/blob/main/src/main/sessions/SessionScanner.ts"
click node_filesystem "https://github.com/ayuayue/pideck/blob/main/src/main/fs/FileSystemService.ts"
click node_terminal_manager "https://github.com/ayuayue/pideck/blob/main/src/main/terminal/TerminalSessionManager.ts"
click node_config_manager "https://github.com/ayuayue/pideck/blob/main/src/main/config/ConfigManager.ts"
click node_extension_manager "https://github.com/ayuayue/pideck/blob/main/src/main/extensions/ExtensionManager.ts"
click node_wsl_environment "https://github.com/ayuayue/pideck/blob/main/src/main/wsl/WslEnvironment.ts"
click node_feishu_bridge "https://github.com/ayuayue/pideck/blob/main/src/main/feishu/FeishuBridge.ts"
click node_telemetry "https://github.com/ayuayue/pideck/blob/main/src/main/telemetry/TelemetryService.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_react_entry,node_workspace_shell,node_workspace_components,node_rich_input toneBlue
class node_ipc_contract,node_shared_types,node_preload_api toneAmber
class node_main_entry,node_agent_manager,node_pi_process,node_pi_rpc,node_project_store,node_session_scanner,node_filesystem,node_terminal_manager,node_config_manager,node_extension_manager,node_wsl_environment,node_feishu_bridge,node_telemetry toneMint
class node_pi_cli,node_local_machine,node_remote_services toneRose
```

## Components

### Renderer workspace

- [React entry](https://github.com/ayuayue/pideck/blob/main/src/renderer/src/main.tsx): renderer entry · `src/renderer/src/main.tsx`
- [Workspace shell](https://github.com/ayuayue/pideck/blob/main/src/renderer/src/App.tsx): React application · Coordinates selected projects, agents, panels, and streamed chat. · `src/renderer/src/App.tsx`
- [Workspace UI](https://github.com/ayuayue/pideck/blob/main/src/renderer/src/components/app/AppParts.tsx): React components · Provides app panels and rich composer behavior. · `src/renderer/src/components/app/AppParts.tsx`
- [Rich composer](https://github.com/ayuayue/pideck/blob/main/src/renderer/src/components/app/RichInput.tsx): input component · `src/renderer/src/components/app/RichInput.tsx`

### Desktop IPC

- [IPC contract](https://github.com/ayuayue/pideck/blob/main/src/shared/ipc.ts): shared channels · Defines typed renderer-to-main operations and events. · `src/shared/ipc.ts`
- [Shared data types](https://github.com/ayuayue/pideck/blob/main/src/shared/types.ts): shared models · `src/shared/types.ts`
- [Preload API](https://github.com/ayuayue/pideck/blob/main/src/preload/index.ts): IPC bridge · Exposes the constrained desktop API to the renderer. · `src/preload/index.ts`

### Electron main

- [Main entry](https://github.com/ayuayue/pideck/blob/main/src/main/index.ts): Electron main · Owns privileged IPC handlers and desktop lifecycle. · `src/main/index.ts`
- [Agent manager](https://github.com/ayuayue/pideck/blob/main/src/main/pi/AgentManager.ts): agent lifecycle · Maintains isolated agent state and gates streamed RPC events. · `src/main/pi/AgentManager.ts`
- [Pi process](https://github.com/ayuayue/pideck/blob/main/src/main/pi/PiProcess.ts): subprocess launcher · Locates and starts or stops pi CLI processes per project cwd. · `src/main/pi/PiProcess.ts`
- [Pi RPC client](https://github.com/ayuayue/pideck/blob/main/src/main/pi/PiRpcClient.ts): RPC transport · Translates pi RPC traffic into application events. · `src/main/pi/PiRpcClient.ts`
- [Project store](https://github.com/ayuayue/pideck/blob/main/src/main/projects/ProjectStore.ts): local persistence · Persists projects independently of active agents. · `src/main/projects/ProjectStore.ts`
- [Session scanner](https://github.com/ayuayue/pideck/blob/main/src/main/sessions/SessionScanner.ts): session import · Scans native pi and external coding-agent sessions. · `src/main/sessions/SessionScanner.ts`
- [Local resource service](https://github.com/ayuayue/pideck/blob/main/src/main/fs/FileSystemService.ts): filesystem and Git · Operates on project files, worktrees, branches, prompts, skills, and extensions. · `src/main/fs/FileSystemService.ts`
- [Terminal manager](https://github.com/ayuayue/pideck/blob/main/src/main/terminal/TerminalSessionManager.ts): PTY sessions · Hosts session-specific terminal docks. · `src/main/terminal/TerminalSessionManager.ts`
- [Pi configuration](https://github.com/ayuayue/pideck/blob/main/src/main/config/ConfigManager.ts): settings service · Reads pi settings and tests providers and models. · `src/main/config/ConfigManager.ts`
- [Extensions and skills](https://github.com/ayuayue/pideck/blob/main/src/main/extensions/ExtensionManager.ts): extensibility service · Manages global, project, and bundled extensions. · `src/main/extensions/ExtensionManager.ts`
- [WSL environment](https://github.com/ayuayue/pideck/blob/main/src/main/wsl/WslEnvironment.ts): platform adapter · Adapts paths and environment for WSL. · `src/main/wsl/WslEnvironment.ts`
- [Feishu bridge](https://github.com/ayuayue/pideck/blob/main/src/main/feishu/FeishuBridge.ts): remote integration · Maps remote card actions to agent and session operations. · `src/main/feishu/FeishuBridge.ts`
- [Telemetry service](https://github.com/ayuayue/pideck/blob/main/src/main/telemetry/TelemetryService.ts): heartbeat client · Sends opt-out anonymous heartbeat telemetry. · `src/main/telemetry/TelemetryService.ts`

### Local and remote integrations

- **pi CLI**: external agent runtime · Externally installed RPC coding-agent executable.
- **Projects and Git**: local machine resources · Project directories, native sessions, Git repositories, and credentials remain local.
- **Remote services**: optional network services · GitHub releases, stores, telemetry endpoint, and Feishu.

## Connections

- React entry → Workspace shell: mounts
- Workspace shell → Workspace UI: composes
- Workspace UI → Rich composer: includes
- Workspace shell → Preload API: uses desktop API
- Preload API → IPC contract: implements
- Preload API → Main entry: invokes and receives events
- Shared data types → Workspace shell: models UI state
- Shared data types → Main entry: models IPC payloads
- Main entry → Agent manager: routes agent operations
- Main entry → Project store: routes project operations
- Main entry → Session scanner: routes session imports
- Main entry → Local resource service: routes local resource operations
- Main entry → Terminal manager: routes terminal operations
- Main entry → Pi configuration: routes settings operations
- Main entry → Extensions and skills: routes extensibility operations
- Agent manager → Pi process: starts and stops
- Pi process → pi CLI: launches per-agent RPC process
- Pi process → Pi RPC client: connects RPC transport
- Pi RPC client → Agent manager: streams RPC events
- Project store → Projects and Git: persists project records
- Session scanner → Projects and Git: scans sessions
- Local resource service → Projects and Git: manages files and Git
- WSL environment → Pi process: adapts WSL execution
- Feishu bridge → Agent manager: forwards card actions
- Pi configuration → pi CLI: configures providers
- Telemetry service → Remote services: sends opt-out heartbeat
- Main entry → Remote services: checks updates and discovery