# adrirubio/claude-deck architecture

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

- Interactive diagram: https://gitdiagram.com/adrirubio/claude-deck
- Repository: https://github.com/adrirubio/claude-deck

## Overview

Claude Deck is a self-hosted web console for inspecting and managing local AI-coding-agent workspaces. Users enter through the dashboard, select a provider or project, manage configuration and extensions, and inspect or coordinate agent sessions; results affect local files, CLI sessions, and persisted coordination data. The graph preserves the README’s major feature areas while grouping related screens and API domains. Some backend services are unsampled, so their links are marked unverified rather than presented as inspected call paths.

Main entry points: [`frontend/src/App.tsx`](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/App.tsx) (Claude Deck UI), [`backend/app/api/v1/router.py`](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/router.py) (Versioned API), [`backend/app/api/v1/agent_teams.py`](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_teams.py) (Team endpoints), [`backend/app/api/v1/agent_mail.py`](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_mail.py) (Mail endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry"]
  node_web["Claude Deck UI<br/>[App.tsx]"]
end

subgraph group_workspace["Workspace management"]
  node_config_ui["Provider config"]
  node_extensions_ui["Agent extensions<br/>[MCPServersPage.tsx]"]
  node_project_ui["Projects and backups<br/>[ProjectsPage.tsx]"]
  node_agents_ui["Agents and skills<br/>[AgentsPage.tsx]"]
end

subgraph group_coordination["Agent coordination"]
  node_mail_ui["Agent Mail<br/>[AgentMailPage.tsx]"]
  node_teams_ui["Agent Teams<br/>[AgentTeamsPage.tsx]"]
  node_bridge_ui["Agent Bridge<br/>[CCBridgePage.tsx]"]
  node_mail_api["Mail endpoints<br/>[agent_mail.py]"]
  node_teams_api["Team endpoints<br/>[agent_teams.py]"]
  node_bridge_api["Bridge endpoints<br/>[router.py]"]
  node_cc_bridge_api["CC Bridge endpoints<br/>[router.py]"]
end

subgraph group_insight["History and insight"]
  node_transcript_ui["Session transcripts"]
  node_analytics_ui["Context and usage<br/>[ContextPage.tsx]"]
end

subgraph group_runtime["Backend runtime"]
  node_api["Versioned API<br/>[router.py]"]
  node_config_api["Config endpoints<br/>[config.py]"]
  node_mcp_api["MCP endpoints<br/>[mcp.py]"]
  node_agent_api["Agent endpoints<br/>[agents.py]"]
  node_history_api["History endpoints<br/>[sessions.py]"]
  node_session_service["Transcript analysis<br/>[session_service.py]"]
  node_context_service["Context analysis<br/>[context_service.py]"]
  node_mail_service["Mail coordination"]
  node_team_service["Team orchestration"]
  node_bridge_services["Session discovery and relay<br/>[pty_relay.py]"]
  node_db[("SQLite state<br/>[database.py]")]
end

node_operator(("Local operator"))
node_local_files["Agent config and history files"]
node_agent_clis["Local agent CLIs"]
node_github["GitHub"]

node_operator -->|"uses"| node_web
node_web -.->|"requests"| node_api
node_web -->|"routes to"| node_config_ui
node_web -->|"routes to"| node_extensions_ui
node_web -->|"routes to"| node_project_ui
node_web -->|"routes to"| node_agents_ui
node_web -->|"routes to"| node_mail_ui
node_web -->|"routes to"| node_teams_ui
node_web -->|"routes to"| node_bridge_ui
node_web -->|"routes to"| node_transcript_ui
node_web -->|"routes to"| node_analytics_ui
node_api -->|"registers"| node_config_api
node_api -->|"registers"| node_mcp_api
node_api -->|"registers"| node_agent_api
node_api -->|"registers"| node_mail_api
node_api -->|"registers"| node_teams_api
node_api -->|"registers"| node_bridge_api
node_api -->|"registers"| node_cc_bridge_api
node_api -->|"registers"| node_history_api
node_history_api -->|"calls"| node_session_service
node_context_service -->|"reads"| node_local_files
node_session_service -->|"reads"| node_local_files
node_bridge_api -->|"uses"| node_bridge_services
node_cc_bridge_api -->|"relays via"| node_bridge_services
node_teams_api -->|"calls"| node_team_service
node_teams_api -->|"calls"| node_mail_service
node_mail_api -->|"calls"| node_mail_service
node_mail_api -->|"queries"| node_db
node_teams_api -->|"queries"| node_db
node_config_api -.->|"manages"| node_local_files
node_mcp_api -.->|"manages"| node_local_files
node_agent_api -.->|"manages"| node_local_files
node_bridge_services -.->|"discovers sessions"| node_agent_clis
node_team_service -.->|"launches sessions"| node_agent_clis
node_team_service -.->|"coordinates dispatch"| node_github
node_mail_service -.->|"persists coordination"| node_db

click node_web "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/App.tsx"
click node_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/router.py"
click node_config_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/config/ConfigViewerPage.tsx"
click node_extensions_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/mcp/MCPServersPage.tsx"
click node_project_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/projects/ProjectsPage.tsx"
click node_agents_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agents/AgentsPage.tsx"
click node_config_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/config.py"
click node_mcp_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/mcp.py"
click node_agent_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agents.py"
click node_mail_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agent-mail/AgentMailPage.tsx"
click node_teams_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agent-teams/AgentTeamsPage.tsx"
click node_bridge_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/cc-bridge/CCBridgePage.tsx"
click node_mail_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_mail.py"
click node_teams_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_teams.py"
click node_bridge_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_bridge/router.py"
click node_cc_bridge_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/cc_bridge/router.py"
click node_transcript_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/sessions/SessionViewPage.tsx"
click node_analytics_ui "https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/context/ContextPage.tsx"
click node_history_api "https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/sessions.py"
click node_session_service "https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/session_service.py"
click node_context_service "https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/context_service.py"
click node_mail_service "https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/agent_mail_service.py"
click node_team_service "https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/agent_team_service.py"
click node_bridge_services "https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/cc_bridge/pty_relay.py"
click node_db "https://github.com/adrirubio/claude-deck/blob/master/backend/app/models/database.py"

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_web toneBlue
class node_config_ui,node_extensions_ui,node_project_ui,node_agents_ui toneAmber
class node_mail_ui,node_teams_ui,node_bridge_ui,node_mail_api,node_teams_api,node_bridge_api,node_cc_bridge_api toneMint
class node_transcript_ui,node_analytics_ui toneRose
class node_api,node_config_api,node_mcp_api,node_agent_api,node_history_api,node_session_service,node_context_service,node_mail_service,node_team_service,node_bridge_services,node_db,node_operator,node_local_files,node_agent_clis,node_github toneIndigo
```

## Components

### Web entry

- [Claude Deck UI](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`

### Workspace management

- [Provider config](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/config/ConfigViewerPage.tsx): `frontend/src/features/config/ConfigViewerPage.tsx`
- [Agent extensions](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/mcp/MCPServersPage.tsx): `frontend/src/features/mcp/MCPServersPage.tsx`
- [Projects and backups](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/projects/ProjectsPage.tsx): `frontend/src/features/projects/ProjectsPage.tsx`
- [Agents and skills](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agents/AgentsPage.tsx): `frontend/src/features/agents/AgentsPage.tsx`

### Agent coordination

- [Agent Mail](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agent-mail/AgentMailPage.tsx): `frontend/src/features/agent-mail/AgentMailPage.tsx`
- [Agent Teams](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/agent-teams/AgentTeamsPage.tsx): `frontend/src/features/agent-teams/AgentTeamsPage.tsx`
- [Agent Bridge](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/cc-bridge/CCBridgePage.tsx): `frontend/src/features/cc-bridge/CCBridgePage.tsx`
- [Mail endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_mail.py): `backend/app/api/v1/agent_mail.py`
- [Team endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_teams.py): `backend/app/api/v1/agent_teams.py`
- [Bridge endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agent_bridge/router.py): `backend/app/api/v1/agent_bridge/router.py`
- [CC Bridge endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/cc_bridge/router.py): `backend/app/api/v1/cc_bridge/router.py`

### History and insight

- [Session transcripts](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/sessions/SessionViewPage.tsx): `frontend/src/features/sessions/SessionViewPage.tsx`
- [Context and usage](https://github.com/adrirubio/claude-deck/blob/master/frontend/src/features/context/ContextPage.tsx): `frontend/src/features/context/ContextPage.tsx`

### Backend runtime

- [Versioned API](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Config endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/config.py): `backend/app/api/v1/config.py`
- [MCP endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/mcp.py): `backend/app/api/v1/mcp.py`
- [Agent endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/agents.py): `backend/app/api/v1/agents.py`
- [History endpoints](https://github.com/adrirubio/claude-deck/blob/master/backend/app/api/v1/sessions.py): `backend/app/api/v1/sessions.py`
- [Transcript analysis](https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- [Context analysis](https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/context_service.py): `backend/app/services/context_service.py`
- [Mail coordination](https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/agent_mail_service.py): `backend/app/services/agent_mail_service.py`
- [Team orchestration](https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/agent_team_service.py): `backend/app/services/agent_team_service.py`
- [Session discovery and relay](https://github.com/adrirubio/claude-deck/blob/master/backend/app/services/cc_bridge/pty_relay.py): `backend/app/services/cc_bridge/pty_relay.py`
- [SQLite state](https://github.com/adrirubio/claude-deck/blob/master/backend/app/models/database.py): `backend/app/models/database.py`

### Other components

- **Local operator**
- **Agent config and history files**
- **Local agent CLIs**
- **GitHub**

## Connections

- Local operator → Claude Deck UI: uses (evidence: `README.md`)
- Claude Deck UI → Versioned API: requests
- Claude Deck UI → Provider config: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Agent extensions: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Projects and backups: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Agents and skills: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Agent Mail: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Agent Teams: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Agent Bridge: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Session transcripts: routes to (evidence: `frontend/src/App.tsx`)
- Claude Deck UI → Context and usage: routes to (evidence: `frontend/src/App.tsx`)
- Versioned API → Config endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → MCP endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Agent endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Mail endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Team endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Bridge endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → CC Bridge endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → History endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- History endpoints → Transcript analysis: calls (evidence: `backend/app/api/v1/sessions.py`)
- Context analysis → Agent config and history files: reads (evidence: `backend/app/services/context_service.py`)
- Transcript analysis → Agent config and history files: reads (evidence: `backend/app/services/session_service.py`)
- Bridge endpoints → Session discovery and relay: uses (evidence: `backend/app/api/v1/agent_bridge/router.py`)
- CC Bridge endpoints → Session discovery and relay: relays via (evidence: `backend/app/api/v1/cc_bridge/router.py`)
- Team endpoints → Team orchestration: calls (evidence: `backend/app/api/v1/agent_teams.py`)
- Team endpoints → Mail coordination: calls (evidence: `backend/app/api/v1/agent_teams.py`)
- Mail endpoints → Mail coordination: calls (evidence: `backend/app/api/v1/agent_mail.py`)
- Mail endpoints → SQLite state: queries (evidence: `backend/app/api/v1/agent_mail.py`)
- Team endpoints → SQLite state: queries (evidence: `backend/app/api/v1/agent_teams.py`)
- Config endpoints → Agent config and history files: manages
- MCP endpoints → Agent config and history files: manages
- Agent endpoints → Agent config and history files: manages
- Session discovery and relay → Local agent CLIs: discovers sessions
- Team orchestration → Local agent CLIs: launches sessions
- Team orchestration → GitHub: coordinates dispatch
- Mail coordination → SQLite state: persists coordination
