# artyomsv/code-spire architecture

> Architecture diagram of the GitHub repository artyomsv/code-spire, 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/artyomsv/code-spire
- Repository: https://github.com/artyomsv/code-spire

## Overview

Code Spire is a self-hosted, event-driven AI pull-request reviewer. The main workflow is SCM webhook ingress, event-driven review orchestration, worker-side review, and operator visibility in the dashboard. The repository also includes work-item/run execution, configurable SCM and context-provider integrations, and operator configuration capabilities. Service responsibilities and message flow are based on the README; sampled source confirms lifecycle event persistence and rerun dispatch, but several subsystem internals were not sampled.

Main entry points: [`spire-review-worker/src/main/java/dev/codespire/worker/pipeline/ReviewWorker.java`](https://github.com/artyomsv/code-spire/blob/master/spire-review-worker/src/main/java/dev/codespire/worker/pipeline/ReviewWorker.java) (Review worker), [`spire-run-worker/src/main/java/dev/codespire/runworker/WorkRunWorker.java`](https://github.com/artyomsv/code-spire/blob/master/spire-run-worker/src/main/java/dev/codespire/runworker/WorkRunWorker.java) (Run worker), [`spire-ui/src/App.tsx`](https://github.com/artyomsv/code-spire/blob/master/spire-ui/src/App.tsx) (Operator dashboard), [`spire-orchestrator/src/main/java/dev/codespire/orchestrator`](https://github.com/artyomsv/code-spire/tree/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator) (Review orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Webhook ingress"]
  node_gateway["Webhook gateway"]
  node_integration_contract["Integration events"]
end

subgraph group_orchestration["Review orchestration"]
  node_event_bus["Kafka event bus"]
  node_orchestrator["Review orchestrator"]
  node_lifecycle["Review lifecycle"]
  node_event_store[("Event store")]
  node_review_projection[("Review read model")]
end

subgraph group_execution["Review and run execution"]
  node_review_worker["Review worker<br/>[ReviewWorker.java]"]
  node_run_worker["Run worker<br/>[WorkRunWorker.java]"]
  node_harness["Agent harness"]
  node_docker_runtime["Docker runtime"]
end

subgraph group_extensions["Provider extensions"]
  node_scm_adapters["SCM adapters<br/>[GitHubClient.java]"]
  node_llm["LLM provider"]
  node_context_code["Code context"]
  node_context_issues["Issue context"]
  node_context_docs["Confluence context"]
end

subgraph group_operator["Operator experience"]
  node_dashboard["Operator dashboard<br/>[App.tsx]"]
  node_live_reviews["Live review feed<br/>[useLiveReviews.ts]"]
  node_work_items["Work-item features"]
end

node_operator_user(("Operator"))
node_scm(("Git platforms"))

node_scm -->|"sends webhooks"| node_gateway
node_gateway -->|"translates events"| node_integration_contract
node_gateway -->|"publishes integration"| node_event_bus
node_event_bus -->|"delivers events"| node_orchestrator
node_orchestrator -->|"handles lifecycle"| node_lifecycle
node_lifecycle -->|"loads and appends"| node_event_store
node_orchestrator -->|"emits commands"| node_event_bus
node_event_bus -->|"delivers commands"| node_review_worker
node_review_worker -->|"publishes results"| node_event_bus
node_event_bus -->|"delivers run commands"| node_run_worker
node_run_worker -->|"publishes run result"| node_event_bus
node_run_worker -->|"drives agent"| node_harness
node_run_worker -->|"builds run unit"| node_docker_runtime
node_review_worker -.->|"fetches and comments"| node_scm_adapters
node_review_worker -.->|"requests review"| node_llm
node_review_worker -.->|"gathers context"| node_context_code
node_review_worker -.->|"gathers context"| node_context_issues
node_review_worker -.->|"gathers context"| node_context_docs
node_operator_user -->|"views and configures"| node_dashboard
node_dashboard -->|"renders feed"| node_live_reviews
node_live_reviews -->|"fetches reviews"| node_review_projection
node_dashboard -->|"uses API and sockets"| node_orchestrator
node_dashboard -->|"manages work"| node_work_items

click node_gateway "https://github.com/artyomsv/code-spire/tree/master/spire-gateway/src/main/java/dev/codespire/gateway"
click node_integration_contract "https://github.com/artyomsv/code-spire/blob/master/spire-contract/src/main/java/dev/codespire/contract/event/IntegrationEvent.java"
click node_orchestrator "https://github.com/artyomsv/code-spire/tree/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator"
click node_lifecycle "https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/lifecycle/ReviewLifecycleService.java"
click node_event_store "https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/eventstore/JdbcEventStore.java"
click node_review_worker "https://github.com/artyomsv/code-spire/blob/master/spire-review-worker/src/main/java/dev/codespire/worker/pipeline/ReviewWorker.java"
click node_run_worker "https://github.com/artyomsv/code-spire/blob/master/spire-run-worker/src/main/java/dev/codespire/runworker/WorkRunWorker.java"
click node_harness "https://github.com/artyomsv/code-spire/tree/master/spire-harness/src/main/java/dev/codespire/harness"
click node_docker_runtime "https://github.com/artyomsv/code-spire/blob/master/spire-runtime-docker/src/main/java/dev/codespire/runtime/docker/DockerRunRuntime.java"
click node_scm_adapters "https://github.com/artyomsv/code-spire/blob/master/spire-scm-github/src/main/java/dev/codespire/scm/github/GitHubClient.java"
click node_llm "https://github.com/artyomsv/code-spire/blob/master/spire-llm/src/main/java/dev/codespire/llm/LangChain4jLlmProvider.java"
click node_context_code "https://github.com/artyomsv/code-spire/blob/master/spire-context-code/src/main/java/dev/codespire/context/code/CodeContextProvider.java"
click node_context_issues "https://github.com/artyomsv/code-spire/blob/master/spire-context-jira/src/main/java/dev/codespire/context/jira/JiraContextProvider.java"
click node_context_docs "https://github.com/artyomsv/code-spire/blob/master/spire-context-confluence/src/main/java/dev/codespire/context/confluence/ConfluenceContextProvider.java"
click node_dashboard "https://github.com/artyomsv/code-spire/blob/master/spire-ui/src/App.tsx"
click node_live_reviews "https://github.com/artyomsv/code-spire/blob/master/spire-ui/src/useLiveReviews.ts"
click node_review_projection "https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/readmodel/ReviewProjection.java"
click node_work_items "https://github.com/artyomsv/code-spire/blob/master/spire-contract/src/main/java/dev/codespire/contract/work/WorkItemLifecycle.java"

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_gateway,node_integration_contract toneBlue
class node_event_bus,node_orchestrator,node_lifecycle,node_event_store,node_review_projection toneAmber
class node_review_worker,node_run_worker,node_harness,node_docker_runtime toneMint
class node_scm_adapters,node_llm,node_context_code,node_context_issues,node_context_docs toneRose
class node_dashboard,node_live_reviews,node_work_items,node_operator_user,node_scm toneIndigo
```

## Components

### Webhook ingress

- [Webhook gateway](https://github.com/artyomsv/code-spire/tree/master/spire-gateway/src/main/java/dev/codespire/gateway): `spire-gateway/src/main/java/dev/codespire/gateway`
- [Integration events](https://github.com/artyomsv/code-spire/blob/master/spire-contract/src/main/java/dev/codespire/contract/event/IntegrationEvent.java): `spire-contract/src/main/java/dev/codespire/contract/event/IntegrationEvent.java`

### Review orchestration

- **Kafka event bus**
- [Review orchestrator](https://github.com/artyomsv/code-spire/tree/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator): `spire-orchestrator/src/main/java/dev/codespire/orchestrator`
- [Review lifecycle](https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/lifecycle/ReviewLifecycleService.java): `spire-orchestrator/src/main/java/dev/codespire/orchestrator/lifecycle/ReviewLifecycleService.java`
- [Event store](https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/eventstore/JdbcEventStore.java): `spire-orchestrator/src/main/java/dev/codespire/orchestrator/eventstore/JdbcEventStore.java`
- [Review read model](https://github.com/artyomsv/code-spire/blob/master/spire-orchestrator/src/main/java/dev/codespire/orchestrator/readmodel/ReviewProjection.java): `spire-orchestrator/src/main/java/dev/codespire/orchestrator/readmodel/ReviewProjection.java`

### Review and run execution

- [Review worker](https://github.com/artyomsv/code-spire/blob/master/spire-review-worker/src/main/java/dev/codespire/worker/pipeline/ReviewWorker.java): `spire-review-worker/src/main/java/dev/codespire/worker/pipeline/ReviewWorker.java`
- [Run worker](https://github.com/artyomsv/code-spire/blob/master/spire-run-worker/src/main/java/dev/codespire/runworker/WorkRunWorker.java): `spire-run-worker/src/main/java/dev/codespire/runworker/WorkRunWorker.java`
- [Agent harness](https://github.com/artyomsv/code-spire/tree/master/spire-harness/src/main/java/dev/codespire/harness): `spire-harness/src/main/java/dev/codespire/harness`
- [Docker runtime](https://github.com/artyomsv/code-spire/blob/master/spire-runtime-docker/src/main/java/dev/codespire/runtime/docker/DockerRunRuntime.java): `spire-runtime-docker/src/main/java/dev/codespire/runtime/docker/DockerRunRuntime.java`

### Provider extensions

- [SCM adapters](https://github.com/artyomsv/code-spire/blob/master/spire-scm-github/src/main/java/dev/codespire/scm/github/GitHubClient.java): `spire-scm-github/src/main/java/dev/codespire/scm/github/GitHubClient.java`
- [LLM provider](https://github.com/artyomsv/code-spire/blob/master/spire-llm/src/main/java/dev/codespire/llm/LangChain4jLlmProvider.java): `spire-llm/src/main/java/dev/codespire/llm/LangChain4jLlmProvider.java`
- [Code context](https://github.com/artyomsv/code-spire/blob/master/spire-context-code/src/main/java/dev/codespire/context/code/CodeContextProvider.java): `spire-context-code/src/main/java/dev/codespire/context/code/CodeContextProvider.java`
- [Issue context](https://github.com/artyomsv/code-spire/blob/master/spire-context-jira/src/main/java/dev/codespire/context/jira/JiraContextProvider.java): `spire-context-jira/src/main/java/dev/codespire/context/jira/JiraContextProvider.java`
- [Confluence context](https://github.com/artyomsv/code-spire/blob/master/spire-context-confluence/src/main/java/dev/codespire/context/confluence/ConfluenceContextProvider.java): `spire-context-confluence/src/main/java/dev/codespire/context/confluence/ConfluenceContextProvider.java`

### Operator experience

- [Operator dashboard](https://github.com/artyomsv/code-spire/blob/master/spire-ui/src/App.tsx): `spire-ui/src/App.tsx`
- [Live review feed](https://github.com/artyomsv/code-spire/blob/master/spire-ui/src/useLiveReviews.ts): `spire-ui/src/useLiveReviews.ts`
- [Work-item features](https://github.com/artyomsv/code-spire/blob/master/spire-contract/src/main/java/dev/codespire/contract/work/WorkItemLifecycle.java): `spire-contract/src/main/java/dev/codespire/contract/work/WorkItemLifecycle.java`

### Other components

- **Operator**
- **Git platforms**

## Connections

- Git platforms → Webhook gateway: sends webhooks (evidence: `README.md`)
- Webhook gateway → Integration events: translates events (evidence: `README.md`)
- Webhook gateway → Kafka event bus: publishes integration (evidence: `README.md`)
- Kafka event bus → Review orchestrator: delivers events (evidence: `README.md`)
- Review orchestrator → Review lifecycle: handles lifecycle (evidence: `spire-orchestrator/src/main/java/dev/codespire/orchestrator/lifecycle/ReviewLifecycleService.java`)
- Review lifecycle → Event store: loads and appends (evidence: `spire-orchestrator/src/main/java/dev/codespire/orchestrator/lifecycle/ReviewLifecycleService.java`)
- Review orchestrator → Kafka event bus: emits commands (evidence: `README.md`)
- Kafka event bus → Review worker: delivers commands (evidence: `README.md`)
- Review worker → Kafka event bus: publishes results (evidence: `README.md`)
- Kafka event bus → Run worker: delivers run commands (evidence: `README.md`)
- Run worker → Kafka event bus: publishes run result (evidence: `README.md`)
- Run worker → Agent harness: drives agent (evidence: `README.md`)
- Run worker → Docker runtime: builds run unit (evidence: `README.md`)
- Review worker → SCM adapters: fetches and comments
- Review worker → LLM provider: requests review
- Review worker → Code context: gathers context
- Review worker → Issue context: gathers context
- Review worker → Confluence context: gathers context
- Operator → Operator dashboard: views and configures (evidence: `README.md`)
- Operator dashboard → Live review feed: renders feed (evidence: `spire-ui/src/App.tsx`)
- Live review feed → Review read model: fetches reviews (evidence: `README.md`)
- Operator dashboard → Review orchestrator: uses API and sockets (evidence: `README.md`)
- Operator dashboard → Work-item features: manages work (evidence: `spire-ui/src/App.tsx`)
