# harshan-ks/sonar-scanner-agent architecture

> Architecture diagram of the GitHub repository harshan-ks/sonar-scanner-agent, 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/harshan-ks/sonar-scanner-agent
- Repository: https://github.com/harshan-ks/sonar-scanner-agent

## Overview

This repository automates SonarQube issue triage and optionally applies guarded fixes. The main workflow is a SonarQube gate-failure webhook (or a direct CLI run) into a LangGraph scan stage, confidence-based fix routing, read-only safety review, then edits or human-review suggestions. The scanner also supports optional LLM rescue for non-whitelisted code smells; dependency fan-in informs confidence scores. Source excerpts do not show every scanner helper or generated-file loading detail, so those internal links are limited to documented behavior.

Main entry points: [`fix_agent.py`](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/fix_agent.py) (Fix agent), [`sonar_agent.py`](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/sonar_agent.py) (Issue scanner), [`main.py`](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/main.py) (CLI front door), [`pipeline_graph.py`](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/pipeline_graph.py) (Pipeline graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["CLI front door<br/>[main.py]"]
  node_webhook["Webhook listener"]
  node_pipeline["Pipeline graph<br/>[pipeline_graph.py]"]
end

subgraph group_scan["Issue scanning"]
  node_scanner["Issue scanner<br/>[sonar_agent.py]"]
  node_rules["Rule whitelist<br/>[fix_rules.yaml]"]
  node_issues["Scored issues"]
end

subgraph group_fix["Fix workflow"]
  node_fixer["Fix agent<br/>[fix_agent.py]"]
  node_backups["Fix backups"]
  node_report["Fix report"]
end

subgraph group_support["AI and risk support"]
  node_fan_in["Fan-in analyzer"]
  node_cli_wrapper["Claude wrapper<br/>[claude_cli.py]"]
end

node_operator(("Operator"))
node_sonarqube["SonarQube"]
node_claude["Claude CLI"]
node_project["Scanned project"]

node_operator -->|"runs commands"| node_main
node_operator -->|"sends webhook"| node_webhook
node_main -->|"runs pipeline"| node_pipeline
node_main -->|"starts listener"| node_webhook
node_main -->|"runs scan"| node_scanner
node_main -->|"runs fix"| node_fixer
node_webhook -->|"dispatches failures"| node_pipeline
node_sonarqube -->|"posts gate status"| node_webhook
node_pipeline -->|"runs scan stage"| node_scanner
node_pipeline -->|"routes eligible issues"| node_fixer
node_scanner -->|"fetches issues"| node_sonarqube
node_scanner -->|"reads whitelist"| node_rules
node_scanner -->|"uses fan-in scoring"| node_fan_in
node_scanner -->|"writes issues"| node_issues
node_fixer -->|"reads issues"| node_issues
node_fixer -->|"reviews and edits"| node_project
node_fixer -->|"saves originals"| node_backups
node_fixer -->|"writes results"| node_report
node_scanner -.->|"requests rescue review"| node_cli_wrapper
node_fixer -->|"requests review and edits"| node_cli_wrapper
node_fixer -->|"requests suggestions"| node_cli_wrapper
node_cli_wrapper -->|"invokes CLI"| node_claude

click node_main "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/main.py"
click node_webhook "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/webhook_listener.py"
click node_pipeline "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/pipeline_graph.py"
click node_scanner "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/sonar_agent.py"
click node_rules "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/fix_rules.yaml"
click node_fan_in "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/dependency_graph.py"
click node_fixer "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/fix_agent.py"
click node_cli_wrapper "https://github.com/harshan-ks/sonar-scanner-agent/blob/master/claude_cli.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_main,node_webhook,node_pipeline toneBlue
class node_scanner,node_rules,node_issues toneAmber
class node_fixer,node_backups,node_report toneMint
class node_fan_in,node_cli_wrapper toneRose
class node_operator,node_sonarqube,node_claude,node_project toneIndigo
```

## Components

### Entry points

- [CLI front door](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/main.py): `main.py`
- [Webhook listener](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/webhook_listener.py): `webhook_listener.py`
- [Pipeline graph](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/pipeline_graph.py): `pipeline_graph.py`

### Issue scanning

- [Issue scanner](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/sonar_agent.py): `sonar_agent.py`
- [Rule whitelist](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/fix_rules.yaml): `fix_rules.yaml`
- **Scored issues**

### Fix workflow

- [Fix agent](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/fix_agent.py): `fix_agent.py`
- **Fix backups**
- **Fix report**

### AI and risk support

- [Fan-in analyzer](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/dependency_graph.py): `dependency_graph.py`
- [Claude wrapper](https://github.com/harshan-ks/sonar-scanner-agent/blob/master/claude_cli.py): `claude_cli.py`

### Other components

- **Operator**
- **SonarQube**
- **Claude CLI**
- **Scanned project**

## Connections

- Operator → CLI front door: runs commands
- Operator → Webhook listener: sends webhook
- CLI front door → Pipeline graph: runs pipeline
- CLI front door → Webhook listener: starts listener
- CLI front door → Issue scanner: runs scan
- CLI front door → Fix agent: runs fix
- Webhook listener → Pipeline graph: dispatches failures
- SonarQube → Webhook listener: posts gate status
- Pipeline graph → Issue scanner: runs scan stage
- Pipeline graph → Fix agent: routes eligible issues
- Issue scanner → SonarQube: fetches issues
- Issue scanner → Rule whitelist: reads whitelist
- Issue scanner → Fan-in analyzer: uses fan-in scoring
- Issue scanner → Scored issues: writes issues
- Fix agent → Scored issues: reads issues
- Fix agent → Scanned project: reviews and edits
- Fix agent → Fix backups: saves originals
- Fix agent → Fix report: writes results
- Issue scanner → Claude wrapper: requests rescue review
- Fix agent → Claude wrapper: requests review and edits
- Fix agent → Claude wrapper: requests suggestions
- Claude wrapper → Claude CLI: invokes CLI