# randheer094/velocity architecture

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

- Interactive diagram: https://gitdiagram.com/randheer094/velocity
- Repository: https://github.com/randheer094/velocity

## Overview

Velocity is a webhook-driven Jira-to-GitHub agent. Jira assignments start parent-ticket planning with Claude; the resulting subtasks are worked through pull requests, and GitHub merge or failure events advance, retry, or roll up the plan. The graph also preserves prompt/resource setup and the daemon’s durable webhook queue. Source excerpts and the index support the main wiring; some internal dispatch details are represented only where indexed or documented, so unsampled relationships are omitted.

Main entry points: [`internal/code/code.go`](https://github.com/randheer094/velocity/blob/main/internal/code/code.go) (Subtask coding), [`internal/server/server.go`](https://github.com/randheer094/velocity/blob/main/internal/server/server.go) (HTTP daemon), [`internal/webhook/github.go`](https://github.com/randheer094/velocity/blob/main/internal/webhook/github.go) (GitHub events), [`internal/arch/arch.go`](https://github.com/randheer094/velocity/blob/main/internal/arch/arch.go) (Parent planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Webhook ingress"]
  node_server["HTTP daemon<br/>[server.go]"]
  node_jira_webhook["Jira events<br/>[jira.go]"]
  node_github_webhook["GitHub events<br/>[github.go]"]
  node_job_queue["Webhook queue<br/>[queue.go]"]
  node_dispatch["Event dispatch<br/>[dispatch.go]"]
end

subgraph group_workflow["Agent workflows"]
  node_architect["Parent planning<br/>[arch.go]"]
  node_coder["Subtask coding<br/>[code.go]"]
  node_iterate["PR iteration<br/>[iterate.go]"]
end

subgraph group_integrations["External integrations"]
  node_jira_client["Jira API client<br/>[client.go]"]
  node_github_client["GitHub API client<br/>[client.go]"]
  node_git_workspace["Git workspace<br/>[git.go]"]
  node_claude["Claude runner<br/>[claude_cli.go]"]
end

subgraph group_runtime["Runtime and state"]
  node_postgres[("Postgres state<br/>[postgres.go]")]
  node_plan_store["Plans and tasks<br/>[plans.go]"]
  node_task_store["Webhook job store<br/>[webhook_jobs.go]"]
  node_prompt_library["Prompt library<br/>[prompts.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_operations["Setup and operations"]
  node_cli["CLI commands<br/>[root.go]"]
  node_resource_setup["Resource setup<br/>[resources.go]"]
  node_readiness["Project readiness<br/>[readiness.go]"]
end

node_jira_actor(("Jira Cloud"))
node_github_actor(("GitHub"))

node_jira_actor -->|"posts events"| node_jira_webhook
node_github_actor -->|"posts events"| node_github_webhook
node_server -->|"routes POST"| node_jira_webhook
node_server -->|"routes POST"| node_github_webhook
node_jira_webhook -->|"enqueues jobs"| node_job_queue
node_github_webhook -->|"enqueues jobs"| node_job_queue
node_job_queue -->|"dispatches jobs"| node_dispatch
node_dispatch -->|"runs planning"| node_architect
node_dispatch -->|"runs coding"| node_coder
node_dispatch -->|"runs iteration"| node_iterate
node_architect -->|"creates subtasks"| node_jira_client
node_architect -->|"requests plan"| node_claude
node_architect -->|"loads and saves"| node_plan_store
node_coder -->|"clones and commits"| node_git_workspace
node_coder -->|"requests code"| node_claude
node_coder -->|"opens pull request"| node_github_client
node_coder -->|"updates issue"| node_jira_client
node_iterate -->|"refreshes branch"| node_git_workspace
node_iterate -->|"requests changes"| node_claude
node_iterate -->|"comments on PR"| node_github_client
node_github_webhook -->|"fetches failure details"| node_github_client
node_github_webhook -->|"records merge"| node_coder
node_github_webhook -->|"requests retry"| node_iterate
node_server -->|"starts database"| node_postgres
node_plan_store -.->|"stores plans"| node_postgres
node_task_store -->|"stores jobs"| node_postgres
node_job_queue -->|"persists queue"| node_task_store
node_server -->|"starts workers"| node_job_queue
node_server -->|"reloads prompts"| node_prompt_library
node_cli -->|"starts daemon"| node_server
node_cli -->|"downloads resources"| node_resource_setup
node_cli -->|"refreshes prompts"| node_prompt_library
node_cli -->|"checks projects"| node_readiness
node_resource_setup -.->|"provides templates"| node_prompt_library
node_architect -->|"reads settings"| node_config
node_coder -->|"reads settings"| node_config

click node_server "https://github.com/randheer094/velocity/blob/main/internal/server/server.go"
click node_jira_webhook "https://github.com/randheer094/velocity/blob/main/internal/webhook/jira.go"
click node_github_webhook "https://github.com/randheer094/velocity/blob/main/internal/webhook/github.go"
click node_job_queue "https://github.com/randheer094/velocity/blob/main/internal/webhook/queue.go"
click node_dispatch "https://github.com/randheer094/velocity/blob/main/internal/webhook/dispatch.go"
click node_architect "https://github.com/randheer094/velocity/blob/main/internal/arch/arch.go"
click node_coder "https://github.com/randheer094/velocity/blob/main/internal/code/code.go"
click node_iterate "https://github.com/randheer094/velocity/blob/main/internal/code/iterate.go"
click node_jira_client "https://github.com/randheer094/velocity/blob/main/internal/jira/client.go"
click node_github_client "https://github.com/randheer094/velocity/blob/main/internal/github/client.go"
click node_git_workspace "https://github.com/randheer094/velocity/blob/main/internal/git/git.go"
click node_claude "https://github.com/randheer094/velocity/blob/main/internal/llm/claude_cli.go"
click node_postgres "https://github.com/randheer094/velocity/blob/main/internal/db/postgres.go"
click node_plan_store "https://github.com/randheer094/velocity/blob/main/internal/db/plans.go"
click node_task_store "https://github.com/randheer094/velocity/blob/main/internal/db/webhook_jobs.go"
click node_prompt_library "https://github.com/randheer094/velocity/blob/main/internal/prompts/prompts.go"
click node_config "https://github.com/randheer094/velocity/blob/main/internal/config/config.go"
click node_cli "https://github.com/randheer094/velocity/blob/main/internal/cli/root.go"
click node_resource_setup "https://github.com/randheer094/velocity/blob/main/internal/resources/resources.go"
click node_readiness "https://github.com/randheer094/velocity/blob/main/internal/cli/readiness.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_server,node_jira_webhook,node_github_webhook,node_job_queue,node_dispatch toneBlue
class node_architect,node_coder,node_iterate toneAmber
class node_jira_client,node_github_client,node_git_workspace,node_claude toneMint
class node_postgres,node_plan_store,node_task_store,node_prompt_library,node_config toneRose
class node_cli,node_resource_setup,node_readiness,node_jira_actor,node_github_actor toneIndigo
```

## Components

### Webhook ingress

- [HTTP daemon](https://github.com/randheer094/velocity/blob/main/internal/server/server.go): `internal/server/server.go`
- [Jira events](https://github.com/randheer094/velocity/blob/main/internal/webhook/jira.go): `internal/webhook/jira.go`
- [GitHub events](https://github.com/randheer094/velocity/blob/main/internal/webhook/github.go): `internal/webhook/github.go`
- [Webhook queue](https://github.com/randheer094/velocity/blob/main/internal/webhook/queue.go): `internal/webhook/queue.go`
- [Event dispatch](https://github.com/randheer094/velocity/blob/main/internal/webhook/dispatch.go): `internal/webhook/dispatch.go`

### Agent workflows

- [Parent planning](https://github.com/randheer094/velocity/blob/main/internal/arch/arch.go): `internal/arch/arch.go`
- [Subtask coding](https://github.com/randheer094/velocity/blob/main/internal/code/code.go): `internal/code/code.go`
- [PR iteration](https://github.com/randheer094/velocity/blob/main/internal/code/iterate.go): `internal/code/iterate.go`

### External integrations

- [Jira API client](https://github.com/randheer094/velocity/blob/main/internal/jira/client.go): `internal/jira/client.go`
- [GitHub API client](https://github.com/randheer094/velocity/blob/main/internal/github/client.go): `internal/github/client.go`
- [Git workspace](https://github.com/randheer094/velocity/blob/main/internal/git/git.go): `internal/git/git.go`
- [Claude runner](https://github.com/randheer094/velocity/blob/main/internal/llm/claude_cli.go): `internal/llm/claude_cli.go`

### Runtime and state

- [Postgres state](https://github.com/randheer094/velocity/blob/main/internal/db/postgres.go): `internal/db/postgres.go`
- [Plans and tasks](https://github.com/randheer094/velocity/blob/main/internal/db/plans.go): `internal/db/plans.go`
- [Webhook job store](https://github.com/randheer094/velocity/blob/main/internal/db/webhook_jobs.go): `internal/db/webhook_jobs.go`
- [Prompt library](https://github.com/randheer094/velocity/blob/main/internal/prompts/prompts.go): `internal/prompts/prompts.go`
- [Configuration](https://github.com/randheer094/velocity/blob/main/internal/config/config.go): `internal/config/config.go`

### Setup and operations

- [CLI commands](https://github.com/randheer094/velocity/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Resource setup](https://github.com/randheer094/velocity/blob/main/internal/resources/resources.go): `internal/resources/resources.go`
- [Project readiness](https://github.com/randheer094/velocity/blob/main/internal/cli/readiness.go): `internal/cli/readiness.go`

### Other components

- **Jira Cloud**
- **GitHub**

## Connections

- Jira Cloud → Jira events: posts events (evidence: `README.md`)
- GitHub → GitHub events: posts events (evidence: `README.md`)
- HTTP daemon → Jira events: routes POST (evidence: `internal/server/server.go`)
- HTTP daemon → GitHub events: routes POST (evidence: `internal/server/server.go`)
- Jira events → Webhook queue: enqueues jobs (evidence: `internal/webhook/jira.go`)
- GitHub events → Webhook queue: enqueues jobs (evidence: `internal/webhook/github.go`)
- Webhook queue → Event dispatch: dispatches jobs (evidence: `internal/webhook/queue.go`)
- Event dispatch → Parent planning: runs planning (evidence: `internal/webhook/dispatch.go`)
- Event dispatch → Subtask coding: runs coding (evidence: `internal/webhook/dispatch.go`)
- Event dispatch → PR iteration: runs iteration (evidence: `internal/webhook/dispatch.go`)
- Parent planning → Jira API client: creates subtasks (evidence: `internal/arch/arch.go`)
- Parent planning → Claude runner: requests plan (evidence: `internal/arch/arch.go`)
- Parent planning → Plans and tasks: loads and saves (evidence: `internal/arch/arch.go`)
- Subtask coding → Git workspace: clones and commits (evidence: `internal/code/code.go`)
- Subtask coding → Claude runner: requests code (evidence: `internal/code/code.go`)
- Subtask coding → GitHub API client: opens pull request (evidence: `internal/code/code.go`)
- Subtask coding → Jira API client: updates issue (evidence: `internal/code/code.go`)
- PR iteration → Git workspace: refreshes branch (evidence: `internal/code/iterate.go`)
- PR iteration → Claude runner: requests changes (evidence: `internal/code/iterate.go`)
- PR iteration → GitHub API client: comments on PR (evidence: `internal/code/iterate.go`)
- GitHub events → GitHub API client: fetches failure details (evidence: `internal/webhook/github.go`)
- GitHub events → Subtask coding: records merge (evidence: `internal/webhook/github.go`)
- GitHub events → PR iteration: requests retry (evidence: `internal/webhook/github.go`)
- HTTP daemon → Postgres state: starts database (evidence: `internal/server/server.go`)
- Plans and tasks → Postgres state: stores plans
- Webhook job store → Postgres state: stores jobs (evidence: `internal/db/webhook_jobs.go`)
- Webhook queue → Webhook job store: persists queue (evidence: `internal/webhook/queue.go`)
- HTTP daemon → Webhook queue: starts workers (evidence: `internal/server/server.go`)
- HTTP daemon → Prompt library: reloads prompts (evidence: `internal/server/server.go`)
- CLI commands → HTTP daemon: starts daemon
- CLI commands → Resource setup: downloads resources
- CLI commands → Prompt library: refreshes prompts
- CLI commands → Project readiness: checks projects (evidence: `README.md`)
- Resource setup → Prompt library: provides templates
- Parent planning → Configuration: reads settings (evidence: `internal/arch/arch.go`)
- Subtask coding → Configuration: reads settings (evidence: `internal/code/code.go`)
