# tls11/seraphim architecture

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

- Interactive diagram: https://gitdiagram.com/tls11/seraphim
- Repository: https://github.com/tls11/seraphim

## Overview

Seraphim is a self-hosted autonomous developer agent. Operators curate issues on a kanban board; the API syncs tracker issues, selects the top To Do task, prepares a persistent Docker workspace, drives a resumable Claude Code session, and surfaces its live progress. Pull requests are detected and checked against repository review policy before completion or human review. The graph also shows settings, automation, Jira, and usage capabilities documented by the README or represented in the source index; unsampled implementation details are not inferred beyond those references.

Main entry points: [`api/src/orchestrator/mod.rs`](https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/mod.rs) (Agent and sync loops), [`api/src/db/queries.rs`](https://github.com/tls11/seraphim/blob/main/api/src/db/queries.rs) (Database queries), [`api/src/http/mod.rs`](https://github.com/tls11/seraphim/blob/main/api/src/http/mod.rs) (REST and SSE routes), [`api/src/http/webhooks.rs`](https://github.com/tls11/seraphim/blob/main/api/src/http/webhooks.rs) (Issue webhooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and state"]
  node_api_server["API server<br/>[main.rs]"]
  node_http["REST and SSE routes<br/>[mod.rs]"]
  node_board_http["Board endpoints<br/>[board.rs]"]
  node_tasks_http["Task endpoints<br/>[tasks.rs]"]
  node_settings_http["Settings endpoints<br/>[settings.rs]"]
  node_state["Shared state and events<br/>[state.rs]"]
  node_db_models["Domain models<br/>[models.rs]"]
  node_db_queries["Database queries<br/>[queries.rs]"]
  node_config["Runtime configuration<br/>[config.rs]"]
end

subgraph group_work["Agent workflow"]
  node_orchestrator["Agent and sync loops<br/>[mod.rs]"]
  node_prompt["Prompt construction<br/>[prompt.rs]"]
  node_provision["Workspace preparation<br/>[provision.rs]"]
  node_claude_events["Agent event parsing<br/>[events.rs]"]
  node_review["PR review policy<br/>[review.rs]"]
  node_automation["Automation rules<br/>[mod.rs]"]
end

subgraph group_integrations["Trackers and integrations"]
  node_webhooks["Issue webhooks<br/>[webhooks.rs]"]
  node_claude_oauth["Claude OAuth and usage<br/>[oauth.rs]"]
  node_git["GitHub operations<br/>[mod.rs]"]
  node_jira["Jira client and mapping<br/>[mod.rs]"]
end

subgraph group_ui["Operator interface"]
  node_frontend["Kanban and settings UI<br/>[+page.svelte]"]
  node_frontend_search["Board search<br/>[SearchBar.svelte]"]
end

node_operator(("Operator"))
node_postgres[("Postgres")]
node_workspace["Docker workspace"]
node_claude["Claude service"]
node_github["GitHub issues and PRs"]
node_jira_service["Jira service"]

node_operator -->|"curates work"| node_frontend
node_frontend -->|"uses REST and SSE"| node_http
node_api_server -->|"serves routes"| node_http
node_api_server -->|"constructs shared state"| node_state
node_api_server -->|"spawns loops"| node_orchestrator
node_http -->|"registers routes"| node_board_http
node_http -->|"registers routes"| node_tasks_http
node_http -->|"registers routes"| node_settings_http
node_board_http -.->|"reads and writes"| node_db_queries
node_tasks_http -->|"queries tasks"| node_db_queries
node_tasks_http -->|"uses GitHub operations"| node_git
node_webhooks -->|"updates issue cache"| node_db_queries
node_webhooks -->|"maps GitHub issues"| node_git
node_webhooks -->|"maps Jira events"| node_jira
node_github -->|"sends issue events"| node_webhooks
node_jira_service -->|"sends issue events"| node_webhooks
node_state -->|"queries persisted state"| node_db_queries
node_db_queries -.->|"reads and writes"| node_postgres
node_db_models -->|"defines domain data"| node_state
node_orchestrator -->|"selects and updates tasks"| node_db_queries
node_orchestrator -->|"prepares repository"| node_provision
node_orchestrator -->|"builds agent prompt"| node_prompt
node_orchestrator -.->|"handles streamed events"| node_claude_events
node_provision -.->|"prepares workspace"| node_workspace
node_workspace -->|"runs resumed session"| node_claude
node_claude -->|"streams task output"| node_frontend
node_orchestrator -->|"detects and reviews PRs"| node_git
node_review -.->|"applies review policy"| node_git
node_git -->|"checks and merges PRs"| node_github
node_settings_http -.->|"supports subscription login"| node_claude_oauth
node_claude_oauth -->|"exchanges token and usage"| node_claude
node_orchestrator -->|"fires matching rules"| node_automation
node_settings_http -.->|"configures integration"| node_jira
node_frontend_search -->|"filters board tasks"| node_frontend
node_frontend -->|"shows board and progress"| node_operator

click node_frontend "https://github.com/tls11/seraphim/blob/main/frontend/src/routes/%2Bpage.svelte"
click node_frontend_search "https://github.com/tls11/seraphim/blob/main/frontend/src/lib/components/SearchBar.svelte"
click node_api_server "https://github.com/tls11/seraphim/blob/main/api/src/main.rs"
click node_http "https://github.com/tls11/seraphim/blob/main/api/src/http/mod.rs"
click node_board_http "https://github.com/tls11/seraphim/blob/main/api/src/http/board.rs"
click node_tasks_http "https://github.com/tls11/seraphim/blob/main/api/src/http/tasks.rs"
click node_settings_http "https://github.com/tls11/seraphim/blob/main/api/src/http/settings.rs"
click node_webhooks "https://github.com/tls11/seraphim/blob/main/api/src/http/webhooks.rs"
click node_state "https://github.com/tls11/seraphim/blob/main/api/src/state.rs"
click node_db_models "https://github.com/tls11/seraphim/blob/main/api/src/db/models.rs"
click node_db_queries "https://github.com/tls11/seraphim/blob/main/api/src/db/queries.rs"
click node_orchestrator "https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/mod.rs"
click node_prompt "https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/prompt.rs"
click node_provision "https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/provision.rs"
click node_claude_events "https://github.com/tls11/seraphim/blob/main/api/src/claude/events.rs"
click node_claude_oauth "https://github.com/tls11/seraphim/blob/main/api/src/claude/oauth.rs"
click node_review "https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/review.rs"
click node_git "https://github.com/tls11/seraphim/blob/main/api/src/git/mod.rs"
click node_jira "https://github.com/tls11/seraphim/blob/main/api/src/jira/mod.rs"
click node_automation "https://github.com/tls11/seraphim/blob/main/api/src/automation/mod.rs"
click node_config "https://github.com/tls11/seraphim/blob/main/api/src/config.rs"

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_api_server,node_http,node_board_http,node_tasks_http,node_settings_http,node_state,node_db_models,node_db_queries,node_config toneBlue
class node_orchestrator,node_prompt,node_provision,node_claude_events,node_review,node_automation,node_postgres toneAmber
class node_webhooks,node_claude_oauth,node_git,node_jira toneMint
class node_frontend,node_frontend_search toneRose
class node_operator,node_workspace,node_claude,node_github,node_jira_service toneIndigo
```

## Components

### API and state

- [API server](https://github.com/tls11/seraphim/blob/main/api/src/main.rs): `api/src/main.rs`
- [REST and SSE routes](https://github.com/tls11/seraphim/blob/main/api/src/http/mod.rs): `api/src/http/mod.rs`
- [Board endpoints](https://github.com/tls11/seraphim/blob/main/api/src/http/board.rs): `api/src/http/board.rs`
- [Task endpoints](https://github.com/tls11/seraphim/blob/main/api/src/http/tasks.rs): `api/src/http/tasks.rs`
- [Settings endpoints](https://github.com/tls11/seraphim/blob/main/api/src/http/settings.rs): `api/src/http/settings.rs`
- [Shared state and events](https://github.com/tls11/seraphim/blob/main/api/src/state.rs): `api/src/state.rs`
- [Domain models](https://github.com/tls11/seraphim/blob/main/api/src/db/models.rs): `api/src/db/models.rs`
- [Database queries](https://github.com/tls11/seraphim/blob/main/api/src/db/queries.rs): `api/src/db/queries.rs`
- [Runtime configuration](https://github.com/tls11/seraphim/blob/main/api/src/config.rs): `api/src/config.rs`

### Agent workflow

- [Agent and sync loops](https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/mod.rs): `api/src/orchestrator/mod.rs`
- [Prompt construction](https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/prompt.rs): `api/src/orchestrator/prompt.rs`
- [Workspace preparation](https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/provision.rs): `api/src/orchestrator/provision.rs`
- [Agent event parsing](https://github.com/tls11/seraphim/blob/main/api/src/claude/events.rs): `api/src/claude/events.rs`
- [PR review policy](https://github.com/tls11/seraphim/blob/main/api/src/orchestrator/review.rs): `api/src/orchestrator/review.rs`
- [Automation rules](https://github.com/tls11/seraphim/blob/main/api/src/automation/mod.rs): `api/src/automation/mod.rs`

### Trackers and integrations

- [Issue webhooks](https://github.com/tls11/seraphim/blob/main/api/src/http/webhooks.rs): `api/src/http/webhooks.rs`
- [Claude OAuth and usage](https://github.com/tls11/seraphim/blob/main/api/src/claude/oauth.rs): `api/src/claude/oauth.rs`
- [GitHub operations](https://github.com/tls11/seraphim/blob/main/api/src/git/mod.rs): `api/src/git/mod.rs`
- [Jira client and mapping](https://github.com/tls11/seraphim/blob/main/api/src/jira/mod.rs): `api/src/jira/mod.rs`

### Operator interface

- [Kanban and settings UI](https://github.com/tls11/seraphim/blob/main/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Board search](https://github.com/tls11/seraphim/blob/main/frontend/src/lib/components/SearchBar.svelte): `frontend/src/lib/components/SearchBar.svelte`

### Other components

- **Operator**
- **Postgres**
- **Docker workspace**
- **Claude service**
- **GitHub issues and PRs**
- **Jira service**

## Connections

- Operator → Kanban and settings UI: curates work
- Kanban and settings UI → REST and SSE routes: uses REST and SSE
- API server → REST and SSE routes: serves routes (evidence: `api/src/main.rs`)
- API server → Shared state and events: constructs shared state (evidence: `api/src/main.rs`)
- API server → Agent and sync loops: spawns loops (evidence: `api/src/main.rs`)
- REST and SSE routes → Board endpoints: registers routes (evidence: `api/src/http/mod.rs`)
- REST and SSE routes → Task endpoints: registers routes (evidence: `api/src/http/mod.rs`)
- REST and SSE routes → Settings endpoints: registers routes (evidence: `api/src/http/mod.rs`)
- Board endpoints → Database queries: reads and writes
- Task endpoints → Database queries: queries tasks (evidence: `api/src/http/tasks.rs`)
- Task endpoints → GitHub operations: uses GitHub operations (evidence: `api/src/http/tasks.rs`)
- Issue webhooks → Database queries: updates issue cache (evidence: `api/src/http/webhooks.rs`)
- Issue webhooks → GitHub operations: maps GitHub issues (evidence: `api/src/http/webhooks.rs`)
- Issue webhooks → Jira client and mapping: maps Jira events (evidence: `api/src/http/webhooks.rs`)
- GitHub issues and PRs → Issue webhooks: sends issue events (evidence: `api/src/http/webhooks.rs`)
- Jira service → Issue webhooks: sends issue events (evidence: `api/src/http/webhooks.rs`)
- Shared state and events → Database queries: queries persisted state (evidence: `api/src/state.rs`)
- Database queries → Postgres: reads and writes
- Domain models → Shared state and events: defines domain data (evidence: `api/src/db/models.rs`)
- Agent and sync loops → Database queries: selects and updates tasks (evidence: `api/src/orchestrator/mod.rs`)
- Agent and sync loops → Workspace preparation: prepares repository (evidence: `api/src/orchestrator/mod.rs`)
- Agent and sync loops → Prompt construction: builds agent prompt (evidence: `api/src/orchestrator/mod.rs`)
- Agent and sync loops → Agent event parsing: handles streamed events
- Workspace preparation → Docker workspace: prepares workspace
- Docker workspace → Claude service: runs resumed session
- Claude service → Kanban and settings UI: streams task output
- Agent and sync loops → GitHub operations: detects and reviews PRs (evidence: `api/src/orchestrator/mod.rs`)
- PR review policy → GitHub operations: applies review policy
- GitHub operations → GitHub issues and PRs: checks and merges PRs (evidence: `api/src/git/mod.rs`)
- Settings endpoints → Claude OAuth and usage: supports subscription login
- Claude OAuth and usage → Claude service: exchanges token and usage (evidence: `api/src/claude/oauth.rs`)
- Agent and sync loops → Automation rules: fires matching rules (evidence: `api/src/orchestrator/mod.rs`)
- Settings endpoints → Jira client and mapping: configures integration
- Board search → Kanban and settings UI: filters board tasks (evidence: `frontend/src/lib/components/SearchBar.svelte`)
- Kanban and settings UI → Operator: shows board and progress
