# huocode-bot/huocode architecture

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

- Interactive diagram: https://gitdiagram.com/huocode-bot/huocode
- Repository: https://github.com/huocode-bot/huocode

## Overview

HuoCode is a Spring API and asynchronous worker that analyzes public GitHub repositories, returning file-level complexity/churn hotspot scores and cached reports. The principal path validates an analysis request, checks for a cached result, selects synchronous or queued work, retrieves repository content and history, measures and scores files, then stores and serves the report. The README documents the retrieval strategies, PMD complexity analysis, JGit churn analysis, S3 cache, and queue boundary; unsampled wiring is represented only where that documentation supports it.

Main entry points: [`src/main/java/io/huocode/api/aggregation/RepoAggregator.java`](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/aggregation/RepoAggregator.java) (Repository aggregator), [`src/main/java/io/huocode/api/service/AnalysisJobService.java`](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/AnalysisJobService.java) (Job coordinator), [`src/main/java/io/huocode/api/service/RepoUrlAnalyzerService.java`](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/RepoUrlAnalyzerService.java) (Analysis and cache), [`src/main/java/io/huocode/api/service/event/RepoAnalysisRequestedService.java`](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/event/RepoAnalysisRequestedService.java) (Async job runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_analysis_controller["Analysis endpoints"]
  node_report_controller["Report endpoints"]
end

subgraph group_workflow["Analysis workflow"]
  node_job_service["Job coordinator"]
  node_analyzer_service["Analysis and cache"]
  node_event_producer["Event producer<br/>[EventProducer.java]"]
  node_mailbox_handler["Queue handler"]
  node_event_invoker["Event dispatcher"]
  node_async_service["Async job runner"]
end

subgraph group_analysis["Repository analysis"]
  node_aggregator["Repository aggregator"]
  node_strategy["Retrieval selector"]
  node_direct_retriever["API retrieval"]
  node_clone_retriever["Clone retrieval"]
  node_scoring["Hotspot scoring<br/>[ScoreEngine.java]"]
end

subgraph group_integrations["External adapters"]
  node_pmd["Java complexity<br/>[PmdAdapter.java]"]
  node_github_adapter["GitHub API adapter"]
  node_git_adapter["JGit analysis"]
end

subgraph group_state["Jobs and reports"]
  node_job_store[("Job store<br/>[S3JobStore.java]")]
  node_report_store[("Report cache<br/>[S3ReportStore.java]")]
end

node_user(("API client"))
node_queue["Event queue"]
node_github["GitHub"]
node_s3[("Amazon S3")]

node_user -->|"submits request"| node_analysis_controller
node_analysis_controller -->|"submits or polls"| node_job_service
node_user -->|"requests report"| node_report_controller
node_report_controller -->|"loads latest report"| node_analyzer_service
node_job_service -->|"gets commit and size"| node_github_adapter
node_job_service -->|"runs analysis"| node_analyzer_service
node_job_service -->|"reads and registers jobs"| node_job_store
node_job_service -->|"dispatches job event"| node_event_producer
node_event_producer -->|"publishes event"| node_queue
node_queue -->|"delivers event"| node_mailbox_handler
node_mailbox_handler -->|"dispatches event"| node_event_invoker
node_event_invoker -->|"invokes handler"| node_async_service
node_async_service -->|"reads and updates job"| node_job_store
node_async_service -->|"runs analysis"| node_analyzer_service
node_analyzer_service -->|"checks and saves report"| node_report_store
node_analyzer_service -->|"analyzes repository"| node_aggregator
node_aggregator -->|"selects retrieval"| node_strategy
node_aggregator -->|"retrieves via API"| node_direct_retriever
node_aggregator -->|"retrieves via clone"| node_clone_retriever
node_direct_retriever -->|"fetches files and churn"| node_github_adapter
node_clone_retriever -->|"reads repository history"| node_git_adapter
node_aggregator -->|"measures complexity"| node_pmd
node_aggregator -->|"scores measurements"| node_scoring
node_github_adapter -->|"calls GitHub API"| node_github
node_git_adapter -->|"clones repository"| node_github
node_job_store -->|"persists jobs"| node_s3
node_report_store -->|"persists reports"| node_s3

click node_analysis_controller "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/rest/controller/AnalysisController.java"
click node_report_controller "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/rest/controller/ReportController.java"
click node_job_service "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/AnalysisJobService.java"
click node_analyzer_service "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/RepoUrlAnalyzerService.java"
click node_event_producer "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/event/EventProducer.java"
click node_mailbox_handler "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/handler/MailboxEventHandler.java"
click node_event_invoker "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/event/consumer/EventServiceInvoker.java"
click node_async_service "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/event/RepoAnalysisRequestedService.java"
click node_aggregator "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/aggregation/RepoAggregator.java"
click node_strategy "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/RetrievalStrategySelector.java"
click node_direct_retriever "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/ApiDirectRetriever.java"
click node_clone_retriever "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/CloneRetriever.java"
click node_pmd "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/pmd/PmdAdapter.java"
click node_scoring "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/scoring/ScoreEngine.java"
click node_github_adapter "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/github/HttpGitHubApiAdapter.java"
click node_git_adapter "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/git/JGitScmAdapter.java"
click node_job_store "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/s3/S3JobStore.java"
click node_report_store "https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/s3/S3ReportStore.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_analysis_controller,node_report_controller,node_user toneBlue
class node_job_service,node_analyzer_service,node_event_producer,node_mailbox_handler,node_event_invoker,node_async_service,node_s3 toneAmber
class node_aggregator,node_strategy,node_direct_retriever,node_clone_retriever,node_scoring toneMint
class node_pmd,node_github_adapter,node_git_adapter,node_queue toneRose
class node_job_store,node_report_store,node_github toneIndigo
```

## Components

### HTTP API

- [Analysis endpoints](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/rest/controller/AnalysisController.java): `src/main/java/io/huocode/api/endpoint/rest/controller/AnalysisController.java`
- [Report endpoints](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/rest/controller/ReportController.java): `src/main/java/io/huocode/api/endpoint/rest/controller/ReportController.java`

### Analysis workflow

- [Job coordinator](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/AnalysisJobService.java): `src/main/java/io/huocode/api/service/AnalysisJobService.java`
- [Analysis and cache](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/RepoUrlAnalyzerService.java): `src/main/java/io/huocode/api/service/RepoUrlAnalyzerService.java`
- [Event producer](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/event/EventProducer.java): `src/main/java/io/huocode/api/endpoint/event/EventProducer.java`
- [Queue handler](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/handler/MailboxEventHandler.java): `src/main/java/io/huocode/api/handler/MailboxEventHandler.java`
- [Event dispatcher](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/endpoint/event/consumer/EventServiceInvoker.java): `src/main/java/io/huocode/api/endpoint/event/consumer/EventServiceInvoker.java`
- [Async job runner](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/service/event/RepoAnalysisRequestedService.java): `src/main/java/io/huocode/api/service/event/RepoAnalysisRequestedService.java`

### Repository analysis

- [Repository aggregator](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/aggregation/RepoAggregator.java): `src/main/java/io/huocode/api/aggregation/RepoAggregator.java`
- [Retrieval selector](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/RetrievalStrategySelector.java): `src/main/java/io/huocode/api/retrieval/RetrievalStrategySelector.java`
- [API retrieval](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/ApiDirectRetriever.java): `src/main/java/io/huocode/api/retrieval/ApiDirectRetriever.java`
- [Clone retrieval](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/retrieval/CloneRetriever.java): `src/main/java/io/huocode/api/retrieval/CloneRetriever.java`
- [Hotspot scoring](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/scoring/ScoreEngine.java): `src/main/java/io/huocode/api/scoring/ScoreEngine.java`

### External adapters

- [Java complexity](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/pmd/PmdAdapter.java): `src/main/java/io/huocode/api/adapter/pmd/PmdAdapter.java`
- [GitHub API adapter](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/github/HttpGitHubApiAdapter.java): `src/main/java/io/huocode/api/adapter/github/HttpGitHubApiAdapter.java`
- [JGit analysis](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/git/JGitScmAdapter.java): `src/main/java/io/huocode/api/adapter/git/JGitScmAdapter.java`

### Jobs and reports

- [Job store](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/s3/S3JobStore.java): `src/main/java/io/huocode/api/adapter/s3/S3JobStore.java`
- [Report cache](https://github.com/huocode-bot/huocode/blob/preprod/src/main/java/io/huocode/api/adapter/s3/S3ReportStore.java): `src/main/java/io/huocode/api/adapter/s3/S3ReportStore.java`

### Other components

- **API client**
- **Event queue**
- **GitHub**
- **Amazon S3**

## Connections

- API client → Analysis endpoints: submits request
- Analysis endpoints → Job coordinator: submits or polls
- API client → Report endpoints: requests report
- Report endpoints → Analysis and cache: loads latest report
- Job coordinator → GitHub API adapter: gets commit and size
- Job coordinator → Analysis and cache: runs analysis
- Job coordinator → Job store: reads and registers jobs
- Job coordinator → Event producer: dispatches job event
- Event producer → Event queue: publishes event
- Event queue → Queue handler: delivers event
- Queue handler → Event dispatcher: dispatches event
- Event dispatcher → Async job runner: invokes handler
- Async job runner → Job store: reads and updates job
- Async job runner → Analysis and cache: runs analysis
- Analysis and cache → Report cache: checks and saves report
- Analysis and cache → Repository aggregator: analyzes repository
- Repository aggregator → Retrieval selector: selects retrieval
- Repository aggregator → API retrieval: retrieves via API
- Repository aggregator → Clone retrieval: retrieves via clone
- API retrieval → GitHub API adapter: fetches files and churn
- Clone retrieval → JGit analysis: reads repository history
- Repository aggregator → Java complexity: measures complexity
- Repository aggregator → Hotspot scoring: scores measurements
- GitHub API adapter → GitHub: calls GitHub API
- JGit analysis → GitHub: clones repository
- Job store → Amazon S3: persists jobs
- Report cache → Amazon S3: persists reports