# src-d/hercules architecture

> Architecture diagram of the GitHub repository src-d/hercules, 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/src-d/hercules
- Repository: https://github.com/src-d/hercules

## Overview

Hercules analyzes Git commit history through a configurable Go pipeline of analysis tasks, then emits YAML or Protocol Buffers for Labours, its Python plotting tool. The graph shows the documented workflow and major analysis capabilities, plus selected internal processing and embedding layers. Some analysis modules and CLI/reader wiring are unsampled; those subsystems are represented by their existing directories, and undocumented calls are omitted.

Main entry points: [`internal/core/pipeline.go`](https://github.com/src-d/hercules/blob/master/internal/core/pipeline.go) (Analysis pipeline), [`cmd/hercules/root.go`](https://github.com/src-d/hercules/blob/master/cmd/hercules/root.go) (Hercules CLI), [`internal/plumbing`](https://github.com/src-d/hercules/tree/master/internal/plumbing) (Git plumbing), [`python/labours/cli.py`](https://github.com/src-d/hercules/blob/master/python/labours/cli.py) (Labours CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Repository analysis"]
  node_hercules["Hercules CLI<br/>[root.go]"]
  node_pipeline["Analysis pipeline<br/>[pipeline.go]"]
end

subgraph group_analysis["Analysis tasks"]
  node_burndown["Project burndown<br/>[burndown.go]"]
  node_couples["File couples<br/>[couples.go]"]
  node_hotness["Structural hotness<br/>[shotness.go]"]
  node_otheranalyses["Other analyses"]
  node_typos["Typo analysis<br/>[typos.go]"]
end

subgraph group_output["Results and plots"]
  node_serializer["Result serialization"]
  node_labours["Labours CLI<br/>[cli.py]"]
  node_readers["Result readers<br/>[readers.py]"]
  node_plotmodes["Plot modes"]
  node_plotting["Plot rendering<br/>[plotting.py]"]
  node_embeddings["Embedding export<br/>[embeddings.py]"]
  node_swivel["Swivel trainer<br/>[swivel.py]"]
  node_webserver["Local web server<br/>[cors_web_server.py]"]
end

subgraph group_internal["Processing internals"]
  node_plumbing["Git plumbing"]
  node_identity["Identity detection<br/>[identity.go]"]
  node_renames["Rename analysis<br/>[renames.go]"]
  node_uast["UAST processing<br/>[uast.go]"]
  node_burndownstate["File burndown state<br/>[file.go]"]
end

node_user(("Engineer"))
node_gitrepo[("Git repository")]

node_user -->|"runs"| node_hercules
node_gitrepo -->|"provides history"| node_hercules
node_hercules -->|"configures and runs"| node_pipeline
node_pipeline -.->|"analyzes commits"| node_plumbing
node_pipeline -->|"dispatches tasks"| node_burndown
node_pipeline -->|"dispatches tasks"| node_couples
node_pipeline -->|"dispatches tasks"| node_hotness
node_pipeline -->|"dispatches tasks"| node_otheranalyses
node_pipeline -.->|"dispatches tasks"| node_typos
node_plumbing -.->|"detects authors"| node_identity
node_plumbing -.->|"detects renames"| node_renames
node_plumbing -.->|"extracts syntax"| node_uast
node_burndown -->|"updates file history"| node_burndownstate
node_typos -->|"uses syntax changes"| node_uast
node_hercules -->|"pipes results"| node_labours
node_labours -->|"reads result data"| node_readers
node_labours -->|"selects plot mode"| node_plotmodes
node_plotmodes -->|"renders plots"| node_plotting
node_hercules -->|"writes protobuf"| node_serializer
node_embeddings -->|"trains embeddings"| node_swivel
node_embeddings -->|"starts server"| node_webserver

click node_hercules "https://github.com/src-d/hercules/blob/master/cmd/hercules/root.go"
click node_pipeline "https://github.com/src-d/hercules/blob/master/internal/core/pipeline.go"
click node_plumbing "https://github.com/src-d/hercules/tree/master/internal/plumbing"
click node_identity "https://github.com/src-d/hercules/blob/master/internal/plumbing/identity/identity.go"
click node_renames "https://github.com/src-d/hercules/blob/master/internal/plumbing/renames.go"
click node_uast "https://github.com/src-d/hercules/blob/master/internal/plumbing/uast/uast.go"
click node_burndownstate "https://github.com/src-d/hercules/blob/master/internal/burndown/file.go"
click node_burndown "https://github.com/src-d/hercules/blob/master/leaves/burndown.go"
click node_couples "https://github.com/src-d/hercules/blob/master/leaves/couples.go"
click node_hotness "https://github.com/src-d/hercules/blob/master/leaves/shotness.go"
click node_otheranalyses "https://github.com/src-d/hercules/tree/master/leaves"
click node_typos "https://github.com/src-d/hercules/blob/master/leaves/research/typos.go"
click node_serializer "https://github.com/src-d/hercules/tree/master/internal/pb"
click node_labours "https://github.com/src-d/hercules/blob/master/python/labours/cli.py"
click node_readers "https://github.com/src-d/hercules/blob/master/python/labours/readers.py"
click node_plotmodes "https://github.com/src-d/hercules/tree/master/python/labours/modes"
click node_plotting "https://github.com/src-d/hercules/blob/master/python/labours/plotting.py"
click node_embeddings "https://github.com/src-d/hercules/blob/master/python/labours/embeddings.py"
click node_swivel "https://github.com/src-d/hercules/blob/master/python/labours/_vendor/swivel.py"
click node_webserver "https://github.com/src-d/hercules/blob/master/python/labours/cors_web_server.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_hercules,node_pipeline toneBlue
class node_burndown,node_couples,node_hotness,node_otheranalyses,node_typos,node_gitrepo toneAmber
class node_serializer,node_labours,node_readers,node_plotmodes,node_plotting,node_embeddings,node_swivel,node_webserver toneMint
class node_plumbing,node_identity,node_renames,node_uast,node_burndownstate toneRose
class node_user toneIndigo
```

## Components

### Repository analysis

- [Hercules CLI](https://github.com/src-d/hercules/blob/master/cmd/hercules/root.go): `cmd/hercules/root.go`
- [Analysis pipeline](https://github.com/src-d/hercules/blob/master/internal/core/pipeline.go): `internal/core/pipeline.go`

### Analysis tasks

- [Project burndown](https://github.com/src-d/hercules/blob/master/leaves/burndown.go): `leaves/burndown.go`
- [File couples](https://github.com/src-d/hercules/blob/master/leaves/couples.go): `leaves/couples.go`
- [Structural hotness](https://github.com/src-d/hercules/blob/master/leaves/shotness.go): `leaves/shotness.go`
- [Other analyses](https://github.com/src-d/hercules/tree/master/leaves): `leaves`
- [Typo analysis](https://github.com/src-d/hercules/blob/master/leaves/research/typos.go): `leaves/research/typos.go`

### Results and plots

- [Result serialization](https://github.com/src-d/hercules/tree/master/internal/pb): `internal/pb`
- [Labours CLI](https://github.com/src-d/hercules/blob/master/python/labours/cli.py): `python/labours/cli.py`
- [Result readers](https://github.com/src-d/hercules/blob/master/python/labours/readers.py): `python/labours/readers.py`
- [Plot modes](https://github.com/src-d/hercules/tree/master/python/labours/modes): `python/labours/modes`
- [Plot rendering](https://github.com/src-d/hercules/blob/master/python/labours/plotting.py): `python/labours/plotting.py`
- [Embedding export](https://github.com/src-d/hercules/blob/master/python/labours/embeddings.py): `python/labours/embeddings.py`
- [Swivel trainer](https://github.com/src-d/hercules/blob/master/python/labours/_vendor/swivel.py): `python/labours/_vendor/swivel.py`
- [Local web server](https://github.com/src-d/hercules/blob/master/python/labours/cors_web_server.py): `python/labours/cors_web_server.py`

### Processing internals

- [Git plumbing](https://github.com/src-d/hercules/tree/master/internal/plumbing): `internal/plumbing`
- [Identity detection](https://github.com/src-d/hercules/blob/master/internal/plumbing/identity/identity.go): `internal/plumbing/identity/identity.go`
- [Rename analysis](https://github.com/src-d/hercules/blob/master/internal/plumbing/renames.go): `internal/plumbing/renames.go`
- [UAST processing](https://github.com/src-d/hercules/blob/master/internal/plumbing/uast/uast.go): `internal/plumbing/uast/uast.go`
- [File burndown state](https://github.com/src-d/hercules/blob/master/internal/burndown/file.go): `internal/burndown/file.go`

### Other components

- **Engineer**
- **Git repository**

## Connections

- Engineer → Hercules CLI: runs
- Git repository → Hercules CLI: provides history
- Hercules CLI → Analysis pipeline: configures and runs (evidence: `cmd/hercules/root.go`)
- Analysis pipeline → Git plumbing: analyzes commits
- Analysis pipeline → Project burndown: dispatches tasks
- Analysis pipeline → File couples: dispatches tasks
- Analysis pipeline → Structural hotness: dispatches tasks
- Analysis pipeline → Other analyses: dispatches tasks
- Analysis pipeline → Typo analysis: dispatches tasks
- Git plumbing → Identity detection: detects authors
- Git plumbing → Rename analysis: detects renames
- Git plumbing → UAST processing: extracts syntax (evidence: `internal/plumbing/uast/uast.go`)
- Project burndown → File burndown state: updates file history (evidence: `leaves/burndown.go`)
- Typo analysis → UAST processing: uses syntax changes (evidence: `leaves/research/typos.go`)
- Hercules CLI → Labours CLI: pipes results
- Labours CLI → Result readers: reads result data (evidence: `python/labours/readers.py`)
- Labours CLI → Plot modes: selects plot mode
- Plot modes → Plot rendering: renders plots (evidence: `python/labours/modes/burndown.py`)
- Hercules CLI → Result serialization: writes protobuf (evidence: `cmd/hercules/root.go`)
- Embedding export → Swivel trainer: trains embeddings (evidence: `python/labours/embeddings.py`)
- Embedding export → Local web server: starts server (evidence: `python/labours/embeddings.py`)
