# proma-ai/proma architecture

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

- Interactive diagram: https://gitdiagram.com/proma-ai/proma
- Repository: https://github.com/proma-ai/proma

## Overview

Proma is a local-first desktop Agent for professional work. Users organize work into projects and sessions, provide project memory and tools as context, then interact with Chat or Agent workflows and review results in files, previews, or related sessions. The README also documents planning, parallel exploration, scheduling, embedded browser/terminal, Skills/MCP/CLI, and remote messaging integrations. The graph combines those documented capabilities with source-indexed implementation modules; unsampled subsystems are not treated as inspected, and uncertain internal wiring is omitted.

Main entry points: [`apps/electron/src/main/lib/agent-orchestrator.ts`](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-orchestrator.ts) (Agent orchestration), [`apps/electron/src/main/lib/agent-session-manager.ts`](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-session-manager.ts) (Agent sessions), [`apps/electron/src/renderer/App.tsx`](https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/App.tsx) (Desktop UI), [`apps/electron/src/main/lib/conversation-manager.ts`](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/conversation-manager.ts) (Chat conversations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_renderer["Desktop UI<br/>[App.tsx]"]
  node_renderer_entry["Renderer entry<br/>[main.tsx]"]
  node_agent_ui_state["Agent UI state<br/>[agent-atoms.ts]"]
end

subgraph group_agent["Agent and sessions"]
  node_agent_runtime["Agent orchestration"]
  node_agent_sessions["Agent sessions"]
  node_conversations["Chat conversations"]
  node_session_core["Transcript processing<br/>[transcript.ts]"]
end

subgraph group_workspace["Project context"]
  node_project_workspaces["Project workspaces"]
  node_project_storage[("Local configuration<br/>[config-paths.ts]")]
end

subgraph group_productivity["Work tools"]
  node_planning["Plans and tasks"]
  node_automation["Scheduled tasks"]
  node_browser["Embedded browser"]
  node_terminal["Embedded terminal"]
  node_file_preview["File preview"]
end

subgraph group_integrations["Extensions and channels"]
  node_skills_mcp["Skills and MCP"]
  node_messaging["Remote messaging<br/>[feishu-bridge.ts]"]
  node_cli["Session CLI<br/>[search.ts]"]
  node_provider["Model providers"]
end

node_user(("Professional user"))

node_user -->|"uses"| node_renderer
node_renderer_entry -->|"mounts"| node_renderer
node_renderer -.->|"manages UI state"| node_agent_ui_state
node_renderer -.->|"starts Agent work"| node_agent_runtime
node_agent_runtime -.->|"coordinates sessions"| node_agent_sessions
node_agent_sessions -->|"uses workspace"| node_project_workspaces
node_agent_sessions -->|"uses conversation data"| node_conversations
node_agent_sessions -->|"uses paths"| node_project_storage
node_conversations -.->|"processes transcripts"| node_session_core
node_agent_runtime -.->|"requests model output"| node_provider
node_agent_runtime -.->|"works with plans"| node_planning
node_agent_runtime -.->|"supports schedules"| node_automation
node_agent_runtime -.->|"uses browser"| node_browser
node_agent_runtime -.->|"uses terminal"| node_terminal
node_agent_runtime -.->|"reviews files"| node_file_preview
node_agent_runtime -.->|"uses project tools"| node_skills_mcp
node_agent_runtime -.->|"receives remote work"| node_messaging
node_cli -->|"searches transcripts"| node_session_core
node_file_preview -.->|"resolves local files"| node_project_storage

click node_renderer "https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/App.tsx"
click node_renderer_entry "https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/main.tsx"
click node_agent_ui_state "https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/atoms/agent-atoms.ts"
click node_agent_runtime "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-orchestrator.ts"
click node_agent_sessions "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-session-manager.ts"
click node_conversations "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/conversation-manager.ts"
click node_session_core "https://github.com/proma-ai/proma/blob/main/packages/session-core/src/transcript.ts"
click node_project_workspaces "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-workspace-manager.ts"
click node_project_storage "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/config-paths.ts"
click node_planning "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/planning-manager.ts"
click node_automation "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/automation-scheduler.ts"
click node_browser "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/browser-controller.ts"
click node_terminal "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/terminal-service.ts"
click node_file_preview "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/file-preview-service.ts"
click node_skills_mcp "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-workspace-manager.ts"
click node_messaging "https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/feishu-bridge.ts"
click node_cli "https://github.com/proma-ai/proma/blob/main/apps/cli/src/commands/search.ts"
click node_provider "https://github.com/proma-ai/proma/blob/main/packages/core/src/providers/anthropic-adapter.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_renderer,node_renderer_entry,node_agent_ui_state,node_user toneBlue
class node_agent_runtime,node_agent_sessions,node_conversations,node_session_core toneAmber
class node_project_workspaces,node_project_storage toneMint
class node_planning,node_automation,node_browser,node_terminal,node_file_preview toneRose
class node_skills_mcp,node_messaging,node_cli,node_provider toneIndigo
```

## Components

### Desktop experience

- [Desktop UI](https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/App.tsx): `apps/electron/src/renderer/App.tsx`
- [Renderer entry](https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/main.tsx): `apps/electron/src/renderer/main.tsx`
- [Agent UI state](https://github.com/proma-ai/proma/blob/main/apps/electron/src/renderer/atoms/agent-atoms.ts): `apps/electron/src/renderer/atoms/agent-atoms.ts`

### Agent and sessions

- [Agent orchestration](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-orchestrator.ts): `apps/electron/src/main/lib/agent-orchestrator.ts`
- [Agent sessions](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-session-manager.ts): `apps/electron/src/main/lib/agent-session-manager.ts`
- [Chat conversations](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/conversation-manager.ts): `apps/electron/src/main/lib/conversation-manager.ts`
- [Transcript processing](https://github.com/proma-ai/proma/blob/main/packages/session-core/src/transcript.ts): `packages/session-core/src/transcript.ts`

### Project context

- [Project workspaces](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-workspace-manager.ts): `apps/electron/src/main/lib/agent-workspace-manager.ts`
- [Local configuration](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/config-paths.ts): `apps/electron/src/main/lib/config-paths.ts`

### Work tools

- [Plans and tasks](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/planning-manager.ts): `apps/electron/src/main/lib/planning-manager.ts`
- [Scheduled tasks](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/automation-scheduler.ts): `apps/electron/src/main/lib/automation-scheduler.ts`
- [Embedded browser](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/browser-controller.ts): `apps/electron/src/main/lib/browser-controller.ts`
- [Embedded terminal](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/terminal-service.ts): `apps/electron/src/main/lib/terminal-service.ts`
- [File preview](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/file-preview-service.ts): `apps/electron/src/main/lib/file-preview-service.ts`

### Extensions and channels

- [Skills and MCP](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/agent-workspace-manager.ts): `apps/electron/src/main/lib/agent-workspace-manager.ts`
- [Remote messaging](https://github.com/proma-ai/proma/blob/main/apps/electron/src/main/lib/feishu-bridge.ts): `apps/electron/src/main/lib/feishu-bridge.ts`
- [Session CLI](https://github.com/proma-ai/proma/blob/main/apps/cli/src/commands/search.ts): `apps/cli/src/commands/search.ts`
- [Model providers](https://github.com/proma-ai/proma/blob/main/packages/core/src/providers/anthropic-adapter.ts): `packages/core/src/providers/anthropic-adapter.ts`

### Other components

- **Professional user**

## Connections

- Professional user → Desktop UI: uses (evidence: `README.md`)
- Renderer entry → Desktop UI: mounts (evidence: `apps/electron/src/renderer/main.tsx`)
- Desktop UI → Agent UI state: manages UI state
- Desktop UI → Agent orchestration: starts Agent work
- Agent orchestration → Agent sessions: coordinates sessions
- Agent sessions → Project workspaces: uses workspace (evidence: `apps/electron/src/main/lib/agent-session-manager.ts`)
- Agent sessions → Chat conversations: uses conversation data (evidence: `apps/electron/src/main/lib/agent-session-manager.ts`)
- Agent sessions → Local configuration: uses paths (evidence: `apps/electron/src/main/lib/agent-session-manager.ts`)
- Chat conversations → Transcript processing: processes transcripts
- Agent orchestration → Model providers: requests model output
- Agent orchestration → Plans and tasks: works with plans
- Agent orchestration → Scheduled tasks: supports schedules
- Agent orchestration → Embedded browser: uses browser
- Agent orchestration → Embedded terminal: uses terminal
- Agent orchestration → File preview: reviews files
- Agent orchestration → Skills and MCP: uses project tools
- Agent orchestration → Remote messaging: receives remote work
- Session CLI → Transcript processing: searches transcripts (evidence: `apps/cli/src/commands/search.ts`)
- File preview → Local configuration: resolves local files
