# oncas/agent-deck architecture

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

- Interactive diagram: https://gitdiagram.com/oncas/agent-deck
- Repository: https://github.com/oncas/agent-deck

## Overview

Agent Deck is a desktop workspace for running AI coding agents across Git repositories, reviewing changes, and using project tools. The main flow is Electron launching the local Go service, whose HTTP and WebSocket interfaces serve the UI and manage project sessions and terminals. Distinct capabilities include workspace management, Git and worktree operations, scheduled jobs, database browsing, usage reporting, and integrations. The graph follows documented capabilities and shown wiring; many feature-specific API routes and UI interactions were not excerpted, so those links are omitted or marked unverified.

Main entry points: [`internal/server/server.go`](https://github.com/oncas/agent-deck/blob/main/internal/server/server.go) (HTTP API server), [`cmd/agentdeck/main.go`](https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/main.go) (Backend startup), [`internal/server/database.go`](https://github.com/oncas/agent-deck/blob/main/internal/server/database.go) (Database browser), [`internal/pty/manager.go`](https://github.com/oncas/agent-deck/blob/main/internal/pty/manager.go) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and UI"]
  node_electron["Electron shell<br/>[main.js]"]
  node_frontend["Agent Deck UI<br/>[app.js]"]
  node_terminalui["Terminal controls"]
  node_transport["Terminal transport"]
end

subgraph group_runtime["Server runtime"]
  node_server["HTTP API server<br/>[server.go]"]
  node_entry["Backend startup<br/>[main.go]"]
  node_config["App configuration<br/>[config.go]"]
end

subgraph group_agents["Agent sessions"]
  node_pty_manager["Session manager<br/>[manager.go]"]
  node_pty_session["PTY process<br/>[session.go]"]
  node_pty_status["Session status<br/>[status.go]"]
  node_websocket["Terminal WebSocket<br/>[websocket.go]"]
  node_jobs["Scheduled jobs<br/>[jobs.go]"]
end

subgraph group_projects["Projects and Git"]
  node_scanner["Repository discovery<br/>[scanner.go]"]
  node_workspaces["Workspaces<br/>[workspaces.go]"]
  node_git["Git operations<br/>[git.go]"]
  node_worktree["Git worktrees<br/>[worktree.go]"]
  node_fetcher["Background fetch<br/>[fetcher.go]"]
end

subgraph group_tools["Project tools"]
  node_database_api["Database browser<br/>[database.go]"]
  node_database_store["Database saved state<br/>[database_store.go]"]
  node_database_state["Database state<br/>[database_state.go]"]
  node_docker["Docker stacks<br/>[docker.go]"]
  node_usage["Agent usage<br/>[usage.go]"]
  node_claude_usage["Claude usage<br/>[claude_usage.go]"]
  node_codex_usage["Codex usage<br/>[codex_usage.go]"]
  node_usage_limits["Usage limits<br/>[usage_limits.go]"]
  node_forge["Forge activity<br/>[forge.go]"]
  node_github["GitHub activity<br/>[github.go]"]
  node_gitlab["GitLab activity<br/>[gitlab.go]"]
  node_power["Keep-awake control<br/>[power.go]"]
end

node_user(("Desktop user"))
node_ai_cli(("AI CLI processes"))
node_db_services[("PostgreSQL, MySQL, SQLite")]
node_git_host(("GitHub and GitLab"))

node_user -->|"uses"| node_electron
node_electron -.->|"launches"| node_entry
node_electron -->|"polls readiness"| node_server
node_electron -->|"polls power"| node_power
node_frontend -.->|"uses API"| node_server
node_terminalui -.->|"controls"| node_transport
node_transport -.->|"exchanges terminal data"| node_websocket
node_entry -.->|"loads"| node_config
node_entry -.->|"discovers projects"| node_scanner
node_entry -->|"creates"| node_pty_manager
node_entry -->|"starts"| node_server
node_server -->|"routes workspace requests"| node_workspaces
node_server -->|"routes terminal sockets"| node_websocket
node_server -.->|"handles job requests"| node_jobs
node_server -.->|"routes Git actions"| node_git
node_server -.->|"routes worktree actions"| node_worktree
node_server -.->|"routes database requests"| node_database_api
node_server -.->|"routes Docker requests"| node_docker
node_server -.->|"routes usage requests"| node_usage
node_server -.->|"routes forge requests"| node_forge
node_server -.->|"serves power state"| node_power
node_pty_manager -->|"creates and manages"| node_pty_session
node_pty_manager -->|"queries status"| node_pty_status
node_pty_session -->|"runs"| node_ai_cli
node_websocket -.->|"accesses sessions"| node_pty_manager
node_jobs -.->|"runs scheduled prompts"| node_pty_manager
node_database_api -->|"persists saved state"| node_database_store
node_database_api -.->|"loads connection state"| node_database_state
node_database_api -->|"queries"| node_db_services
node_database_api -.->|"resolves passwords"| node_database_store
node_usage -.->|"reads Claude logs"| node_claude_usage
node_usage -.->|"reads Codex logs"| node_codex_usage
node_usage -.->|"reports limits"| node_usage_limits
node_forge -.->|"uses GitHub activity"| node_github
node_forge -.->|"uses GitLab activity"| node_gitlab
node_github -.->|"queries gh"| node_git_host
node_gitlab -.->|"queries glab"| node_git_host
node_git -.->|"refreshes status"| node_fetcher
node_git -.->|"supports worktree actions"| node_worktree
node_docker -.->|"independent project tool"| node_ai_cli

click node_electron "https://github.com/oncas/agent-deck/blob/main/electron/main.js"
click node_frontend "https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/app.js"
click node_terminalui "https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/terminal_interactions.js"
click node_transport "https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/terminal_transport.js"
click node_server "https://github.com/oncas/agent-deck/blob/main/internal/server/server.go"
click node_entry "https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/main.go"
click node_config "https://github.com/oncas/agent-deck/blob/main/internal/config/config.go"
click node_scanner "https://github.com/oncas/agent-deck/blob/main/internal/scanner/scanner.go"
click node_workspaces "https://github.com/oncas/agent-deck/blob/main/internal/server/workspaces.go"
click node_git "https://github.com/oncas/agent-deck/blob/main/internal/server/git.go"
click node_worktree "https://github.com/oncas/agent-deck/blob/main/internal/server/worktree.go"
click node_fetcher "https://github.com/oncas/agent-deck/blob/main/internal/server/fetcher.go"
click node_pty_manager "https://github.com/oncas/agent-deck/blob/main/internal/pty/manager.go"
click node_pty_session "https://github.com/oncas/agent-deck/blob/main/internal/pty/session.go"
click node_pty_status "https://github.com/oncas/agent-deck/blob/main/internal/pty/status.go"
click node_websocket "https://github.com/oncas/agent-deck/blob/main/internal/server/websocket.go"
click node_jobs "https://github.com/oncas/agent-deck/blob/main/internal/server/jobs.go"
click node_database_api "https://github.com/oncas/agent-deck/blob/main/internal/server/database.go"
click node_database_store "https://github.com/oncas/agent-deck/blob/main/internal/server/database_store.go"
click node_database_state "https://github.com/oncas/agent-deck/blob/main/internal/server/database_state.go"
click node_docker "https://github.com/oncas/agent-deck/blob/main/internal/server/docker.go"
click node_usage "https://github.com/oncas/agent-deck/blob/main/internal/server/usage.go"
click node_claude_usage "https://github.com/oncas/agent-deck/blob/main/internal/server/claude_usage.go"
click node_codex_usage "https://github.com/oncas/agent-deck/blob/main/internal/server/codex_usage.go"
click node_usage_limits "https://github.com/oncas/agent-deck/blob/main/internal/server/usage_limits.go"
click node_forge "https://github.com/oncas/agent-deck/blob/main/internal/server/forge.go"
click node_github "https://github.com/oncas/agent-deck/blob/main/internal/server/github.go"
click node_gitlab "https://github.com/oncas/agent-deck/blob/main/internal/server/gitlab.go"
click node_power "https://github.com/oncas/agent-deck/blob/main/internal/server/power.go"

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_electron,node_frontend,node_terminalui,node_transport,node_user toneBlue
class node_server,node_entry,node_config,node_db_services toneAmber
class node_pty_manager,node_pty_session,node_pty_status,node_websocket,node_jobs toneMint
class node_scanner,node_workspaces,node_git,node_worktree,node_fetcher toneRose
class node_database_api,node_database_store,node_database_state,node_docker,node_usage,node_claude_usage,node_codex_usage,node_usage_limits,node_forge,node_github,node_gitlab,node_power,node_ai_cli,node_git_host toneIndigo
```

## Components

### Desktop and UI

- [Electron shell](https://github.com/oncas/agent-deck/blob/main/electron/main.js): `electron/main.js`
- [Agent Deck UI](https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/app.js): `cmd/agentdeck/static/app.js`
- [Terminal controls](https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/terminal_interactions.js): `cmd/agentdeck/static/terminal_interactions.js`
- [Terminal transport](https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/static/terminal_transport.js): `cmd/agentdeck/static/terminal_transport.js`

### Server runtime

- [HTTP API server](https://github.com/oncas/agent-deck/blob/main/internal/server/server.go): `internal/server/server.go`
- [Backend startup](https://github.com/oncas/agent-deck/blob/main/cmd/agentdeck/main.go): `cmd/agentdeck/main.go`
- [App configuration](https://github.com/oncas/agent-deck/blob/main/internal/config/config.go): `internal/config/config.go`

### Agent sessions

- [Session manager](https://github.com/oncas/agent-deck/blob/main/internal/pty/manager.go): `internal/pty/manager.go`
- [PTY process](https://github.com/oncas/agent-deck/blob/main/internal/pty/session.go): `internal/pty/session.go`
- [Session status](https://github.com/oncas/agent-deck/blob/main/internal/pty/status.go): `internal/pty/status.go`
- [Terminal WebSocket](https://github.com/oncas/agent-deck/blob/main/internal/server/websocket.go): `internal/server/websocket.go`
- [Scheduled jobs](https://github.com/oncas/agent-deck/blob/main/internal/server/jobs.go): `internal/server/jobs.go`

### Projects and Git

- [Repository discovery](https://github.com/oncas/agent-deck/blob/main/internal/scanner/scanner.go): `internal/scanner/scanner.go`
- [Workspaces](https://github.com/oncas/agent-deck/blob/main/internal/server/workspaces.go): `internal/server/workspaces.go`
- [Git operations](https://github.com/oncas/agent-deck/blob/main/internal/server/git.go): `internal/server/git.go`
- [Git worktrees](https://github.com/oncas/agent-deck/blob/main/internal/server/worktree.go): `internal/server/worktree.go`
- [Background fetch](https://github.com/oncas/agent-deck/blob/main/internal/server/fetcher.go): `internal/server/fetcher.go`

### Project tools

- [Database browser](https://github.com/oncas/agent-deck/blob/main/internal/server/database.go): `internal/server/database.go`
- [Database saved state](https://github.com/oncas/agent-deck/blob/main/internal/server/database_store.go): `internal/server/database_store.go`
- [Database state](https://github.com/oncas/agent-deck/blob/main/internal/server/database_state.go): `internal/server/database_state.go`
- [Docker stacks](https://github.com/oncas/agent-deck/blob/main/internal/server/docker.go): `internal/server/docker.go`
- [Agent usage](https://github.com/oncas/agent-deck/blob/main/internal/server/usage.go): `internal/server/usage.go`
- [Claude usage](https://github.com/oncas/agent-deck/blob/main/internal/server/claude_usage.go): `internal/server/claude_usage.go`
- [Codex usage](https://github.com/oncas/agent-deck/blob/main/internal/server/codex_usage.go): `internal/server/codex_usage.go`
- [Usage limits](https://github.com/oncas/agent-deck/blob/main/internal/server/usage_limits.go): `internal/server/usage_limits.go`
- [Forge activity](https://github.com/oncas/agent-deck/blob/main/internal/server/forge.go): `internal/server/forge.go`
- [GitHub activity](https://github.com/oncas/agent-deck/blob/main/internal/server/github.go): `internal/server/github.go`
- [GitLab activity](https://github.com/oncas/agent-deck/blob/main/internal/server/gitlab.go): `internal/server/gitlab.go`
- [Keep-awake control](https://github.com/oncas/agent-deck/blob/main/internal/server/power.go): `internal/server/power.go`

### Other components

- **Desktop user**
- **AI CLI processes**
- **PostgreSQL, MySQL, SQLite**
- **GitHub and GitLab**

## Connections

- Desktop user → Electron shell: uses
- Electron shell → Backend startup: launches
- Electron shell → HTTP API server: polls readiness (evidence: `electron/main.js`)
- Electron shell → Keep-awake control: polls power (evidence: `electron/main.js`)
- Agent Deck UI → HTTP API server: uses API
- Terminal controls → Terminal transport: controls
- Terminal transport → Terminal WebSocket: exchanges terminal data
- Backend startup → App configuration: loads
- Backend startup → Repository discovery: discovers projects
- Backend startup → Session manager: creates (evidence: `cmd/agentdeck/main.go`)
- Backend startup → HTTP API server: starts (evidence: `cmd/agentdeck/main.go`)
- HTTP API server → Workspaces: routes workspace requests (evidence: `internal/server/server.go`)
- HTTP API server → Terminal WebSocket: routes terminal sockets (evidence: `internal/server/server.go`)
- HTTP API server → Scheduled jobs: handles job requests
- HTTP API server → Git operations: routes Git actions
- HTTP API server → Git worktrees: routes worktree actions
- HTTP API server → Database browser: routes database requests
- HTTP API server → Docker stacks: routes Docker requests
- HTTP API server → Agent usage: routes usage requests
- HTTP API server → Forge activity: routes forge requests
- HTTP API server → Keep-awake control: serves power state
- Session manager → PTY process: creates and manages (evidence: `internal/pty/manager.go`)
- Session manager → Session status: queries status (evidence: `internal/pty/manager.go`)
- PTY process → AI CLI processes: runs (evidence: `internal/pty/session.go`)
- Terminal WebSocket → Session manager: accesses sessions
- Scheduled jobs → Session manager: runs scheduled prompts
- Database browser → Database saved state: persists saved state (evidence: `internal/server/database.go`)
- Database browser → Database state: loads connection state
- Database browser → PostgreSQL, MySQL, SQLite: queries (evidence: `internal/server/database.go`)
- Database browser → Database saved state: resolves passwords
- Agent usage → Claude usage: reads Claude logs
- Agent usage → Codex usage: reads Codex logs
- Agent usage → Usage limits: reports limits
- Forge activity → GitHub activity: uses GitHub activity
- Forge activity → GitLab activity: uses GitLab activity
- GitHub activity → GitHub and GitLab: queries gh
- GitLab activity → GitHub and GitLab: queries glab
- Git operations → Background fetch: refreshes status
- Git operations → Git worktrees: supports worktree actions
- Docker stacks → AI CLI processes: independent project tool
