# hivecommons/hive architecture

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

- Interactive diagram: https://gitdiagram.com/hivecommons/hive
- Repository: https://github.com/hivecommons/hive

## Overview

Hive orchestrates open-source contribution work: it discovers GitHub issues and pull requests, classifies and schedules them, dispatches agents, and governs resulting changes. Its major runtime branches also include operator controls and fleet coordination. The README documents the end-to-end work pipeline; sampled source confirms agent launching and dashboard/TUI behavior, but does not expose every caller, so uncertain wiring is omitted.

Main entry points: [`src/cmd/hive/main.go`](https://github.com/hivecommons/hive/blob/v5/src/cmd/hive/main.go) (Hive runtime), [`src/pkg/dashboard/server.go`](https://github.com/hivecommons/hive/blob/v5/src/pkg/dashboard/server.go) (Web dashboard), [`src/pkg/agent/manager.go`](https://github.com/hivecommons/hive/blob/v5/src/pkg/agent/manager.go) (Agent manager), [`src/pkg/github/client.go`](https://github.com/hivecommons/hive/blob/v5/src/pkg/github/client.go) (GitHub client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Work orchestration"]
  node_hive["Hive runtime<br/>[main.go]"]
  node_config["Hive config<br/>[config.go]"]
  node_intake["Issue intake<br/>[issue_admitter.go]"]
  node_classify["Work classification<br/>[classifier.go]"]
  node_governor["Cadence governor<br/>[governor.go]"]
  node_beads[("Work knowledge<br/>[beads.go]")]
end

subgraph group_agents["Agent runtime"]
  node_agents["Agent manager<br/>[manager.go]"]
  node_launch["Agent launcher<br/>[manager_launch.go]"]
end

subgraph group_github["GitHub workflow"]
  node_github_api["GitHub client<br/>[client.go]"]
  node_pull_requests["Pull request handling<br/>[pullrequest.go]"]
  node_merge_gate["Merge gating<br/>[merge_ci_gate.go]"]
  node_advisory["Advisories<br/>[advisory.go]"]
  node_convergence["Change convergence<br/>[convergence.go]"]
end

subgraph group_operator["Operator interfaces"]
  node_dashboard["Web dashboard<br/>[server.go]"]
  node_tui["Terminal dashboard<br/>[app.go]"]
  node_cli["Hive CLI<br/>[root.go]"]
  node_discord["Discord bot<br/>[bot.go]"]
end

subgraph group_fleet["Fleet and knowledge"]
  node_hub["Fleet hub<br/>[server.go]"]
  node_extwork["External work adapters<br/>[adapter.go]"]
end

node_operator(("Operator"))
node_github_service(("GitHub"))
node_agent_backend(("Agent backends"))

node_operator -->|"operates"| node_dashboard
node_operator -->|"operates"| node_tui
node_operator -->|"commands"| node_cli
node_hive -->|"loads"| node_config
node_hive -->|"orchestrates"| node_intake
node_intake -->|"queries"| node_github_api
node_github_api -->|"calls"| node_github_service
node_intake -->|"classifies"| node_classify
node_hive -->|"schedules"| node_governor
node_governor -->|"dispatches"| node_agents
node_agents -->|"launches"| node_launch
node_launch -->|"starts"| node_agent_backend
node_agents -->|"coordinates"| node_pull_requests
node_pull_requests -->|"uses"| node_github_api
node_merge_gate -->|"checks"| node_github_api
node_hive -->|"governs"| node_merge_gate
node_hive -->|"coordinates"| node_advisory
node_hive -->|"coordinates"| node_convergence
node_hive -->|"persists work"| node_beads
node_dashboard -->|"controls and observes"| node_agents
node_tui -->|"uses API"| node_dashboard
node_cli -->|"uses API"| node_dashboard
node_discord -.->|"bridges status"| node_dashboard
node_hub -->|"coordinates"| node_extwork
node_github_service -.->|"fleet events"| node_hub

click node_hive "https://github.com/hivecommons/hive/blob/v5/src/cmd/hive/main.go"
click node_config "https://github.com/hivecommons/hive/blob/v5/src/pkg/config/config.go"
click node_intake "https://github.com/hivecommons/hive/blob/v5/src/pkg/github/issue_admitter.go"
click node_classify "https://github.com/hivecommons/hive/blob/v5/src/pkg/classify/classifier.go"
click node_governor "https://github.com/hivecommons/hive/blob/v5/src/pkg/governor/governor.go"
click node_beads "https://github.com/hivecommons/hive/blob/v5/src/pkg/beads/beads.go"
click node_agents "https://github.com/hivecommons/hive/blob/v5/src/pkg/agent/manager.go"
click node_launch "https://github.com/hivecommons/hive/blob/v5/src/pkg/agent/manager_launch.go"
click node_github_api "https://github.com/hivecommons/hive/blob/v5/src/pkg/github/client.go"
click node_pull_requests "https://github.com/hivecommons/hive/blob/v5/src/pkg/github/pullrequest.go"
click node_merge_gate "https://github.com/hivecommons/hive/blob/v5/src/pkg/github/merge_ci_gate.go"
click node_advisory "https://github.com/hivecommons/hive/blob/v5/src/pkg/advisory/advisory.go"
click node_convergence "https://github.com/hivecommons/hive/blob/v5/src/pkg/convergence/convergence.go"
click node_dashboard "https://github.com/hivecommons/hive/blob/v5/src/pkg/dashboard/server.go"
click node_tui "https://github.com/hivecommons/hive/blob/v5/src/pkg/tui/app.go"
click node_cli "https://github.com/hivecommons/hive/blob/v5/src/pkg/hivectl/commands/root.go"
click node_discord "https://github.com/hivecommons/hive/blob/v5/src/pkg/discord/bot.go"
click node_hub "https://github.com/hivecommons/hive/blob/v5/src/pkg/hub/server.go"
click node_extwork "https://github.com/hivecommons/hive/blob/v5/src/pkg/extwork/adapter.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_hive,node_config,node_intake,node_classify,node_governor,node_beads toneBlue
class node_agents,node_launch toneAmber
class node_github_api,node_pull_requests,node_merge_gate,node_advisory,node_convergence toneMint
class node_dashboard,node_tui,node_cli,node_discord toneRose
class node_hub,node_extwork,node_operator,node_github_service,node_agent_backend toneIndigo
```

## Components

### Work orchestration

- [Hive runtime](https://github.com/hivecommons/hive/blob/v5/src/cmd/hive/main.go): `src/cmd/hive/main.go`
- [Hive config](https://github.com/hivecommons/hive/blob/v5/src/pkg/config/config.go): `src/pkg/config/config.go`
- [Issue intake](https://github.com/hivecommons/hive/blob/v5/src/pkg/github/issue_admitter.go): `src/pkg/github/issue_admitter.go`
- [Work classification](https://github.com/hivecommons/hive/blob/v5/src/pkg/classify/classifier.go): `src/pkg/classify/classifier.go`
- [Cadence governor](https://github.com/hivecommons/hive/blob/v5/src/pkg/governor/governor.go): `src/pkg/governor/governor.go`
- [Work knowledge](https://github.com/hivecommons/hive/blob/v5/src/pkg/beads/beads.go): `src/pkg/beads/beads.go`

### Agent runtime

- [Agent manager](https://github.com/hivecommons/hive/blob/v5/src/pkg/agent/manager.go): `src/pkg/agent/manager.go`
- [Agent launcher](https://github.com/hivecommons/hive/blob/v5/src/pkg/agent/manager_launch.go): `src/pkg/agent/manager_launch.go`

### GitHub workflow

- [GitHub client](https://github.com/hivecommons/hive/blob/v5/src/pkg/github/client.go): `src/pkg/github/client.go`
- [Pull request handling](https://github.com/hivecommons/hive/blob/v5/src/pkg/github/pullrequest.go): `src/pkg/github/pullrequest.go`
- [Merge gating](https://github.com/hivecommons/hive/blob/v5/src/pkg/github/merge_ci_gate.go): `src/pkg/github/merge_ci_gate.go`
- [Advisories](https://github.com/hivecommons/hive/blob/v5/src/pkg/advisory/advisory.go): `src/pkg/advisory/advisory.go`
- [Change convergence](https://github.com/hivecommons/hive/blob/v5/src/pkg/convergence/convergence.go): `src/pkg/convergence/convergence.go`

### Operator interfaces

- [Web dashboard](https://github.com/hivecommons/hive/blob/v5/src/pkg/dashboard/server.go): `src/pkg/dashboard/server.go`
- [Terminal dashboard](https://github.com/hivecommons/hive/blob/v5/src/pkg/tui/app.go): `src/pkg/tui/app.go`
- [Hive CLI](https://github.com/hivecommons/hive/blob/v5/src/pkg/hivectl/commands/root.go): `src/pkg/hivectl/commands/root.go`
- [Discord bot](https://github.com/hivecommons/hive/blob/v5/src/pkg/discord/bot.go): `src/pkg/discord/bot.go`

### Fleet and knowledge

- [Fleet hub](https://github.com/hivecommons/hive/blob/v5/src/pkg/hub/server.go): `src/pkg/hub/server.go`
- [External work adapters](https://github.com/hivecommons/hive/blob/v5/src/pkg/extwork/adapter.go): `src/pkg/extwork/adapter.go`

### Other components

- **Operator**
- **GitHub**
- **Agent backends**

## Connections

- Operator → Web dashboard: operates
- Operator → Terminal dashboard: operates
- Operator → Hive CLI: commands
- Hive runtime → Hive config: loads
- Hive runtime → Issue intake: orchestrates
- Issue intake → GitHub client: queries
- GitHub client → GitHub: calls
- Issue intake → Work classification: classifies
- Hive runtime → Cadence governor: schedules
- Cadence governor → Agent manager: dispatches
- Agent manager → Agent launcher: launches
- Agent launcher → Agent backends: starts
- Agent manager → Pull request handling: coordinates
- Pull request handling → GitHub client: uses
- Merge gating → GitHub client: checks
- Hive runtime → Merge gating: governs
- Hive runtime → Advisories: coordinates
- Hive runtime → Change convergence: coordinates
- Hive runtime → Work knowledge: persists work
- Web dashboard → Agent manager: controls and observes
- Terminal dashboard → Web dashboard: uses API
- Hive CLI → Web dashboard: uses API
- Discord bot → Web dashboard: bridges status
- Fleet hub → External work adapters: coordinates
- GitHub → Fleet hub: fleet events