# fugui/code-shield architecture

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

- Interactive diagram: https://gitdiagram.com/fugui/code-shield
- Repository: https://github.com/fugui/code-shield

## Overview

Code-Shield is an AI-assisted repository scanning and defect-management service with a React console. Users configure scan policies or trigger work; queued jobs are dispatched through task execution, analyze repositories with a selected engine and LLM CLI, then calibrate and track findings, reconcile report history, and expose reports and exports. Cron scheduling, throttling, issue tracking, feedback governance, and notifications are major supporting capabilities. README documents several integrations and subsystems whose detailed call paths were not sampled; those links are shown only where documented.

Main entry points: [`services/runner/runner.go`](https://github.com/fugui/code-shield/blob/main/services/runner/runner.go) (Task Runner), [`services/services.go`](https://github.com/fugui/code-shield/blob/main/services/services.go) (Engine Adapter), [`main.go`](https://github.com/fugui/code-shield/blob/main/main.go) (HTTP API), [`services/engines/engine.go`](https://github.com/fugui/code-shield/blob/main/services/engines/engine.go) (Scan Engines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Web Console"]
  node_frontend["React Console<br/>[App.tsx]"]
  node_scan_ui["Scan &amp; Campaign UI<br/>[ScanManagement.tsx]"]
  node_report_ui["Report Viewer<br/>[ReportViewer.tsx]"]
end

subgraph group_control["Task Control"]
  node_api["HTTP API<br/>[main.go]"]
  node_task_handlers["Task Handlers<br/>[task.go]"]
  node_schedule["Cron Scheduling<br/>[jobs.go]"]
  node_queue["Persistent Queue<br/>[queue.go]"]
  node_dispatcher["Worker Dispatcher<br/>[dispatcher.go]"]
  node_runner["Task Runner<br/>[runner.go]"]
end

subgraph group_analysis["Scanning"]
  node_engine_adapter["Engine Adapter<br/>[services.go]"]
  node_engines["Scan Engines<br/>[engine.go]"]
  node_single["Single Scan<br/>[engine.go]"]
  node_chunked["Chunked Scan<br/>[engine.go]"]
  node_debate["Debate Scan<br/>[engine.go]"]
  node_invoker["LLM Invokers<br/>[invoker.go]"]
end

subgraph group_quality["Defect Lifecycle"]
  node_governance["Finding Governance<br/>[calibrator.go]"]
  node_fingerprints["Defect Fingerprints<br/>[diff_engine.go]"]
  node_reconciliation["Scan Reconciliation<br/>[engine.go]"]
  node_reports["Report Service &amp; Export<br/>[report_service.go]"]
end

subgraph group_delivery["Persistence &amp; Delivery"]
  node_models["Domain Models<br/>[models.go]"]
  node_report_handler["Report API<br/>[report_handler.go]"]
  node_issues["Issue Tracking API<br/>[issue.go]"]
end

node_user(("Engineer / Admin"))
node_llm_cli["LLM CLI Tools"]
node_database[("PostgreSQL")]
node_notifier["Email Notifier"]

node_user -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_scan_ui
node_frontend -->|"routes to"| node_report_ui
node_scan_ui -->|"requests scans"| node_api
node_report_ui -->|"requests reports"| node_api
node_api -->|"dispatches"| node_task_handlers
node_task_handlers -->|"enqueues tasks"| node_queue
node_schedule -->|"enqueues scheduled work"| node_queue
node_queue -->|"claims tasks"| node_dispatcher
node_dispatcher -->|"dispatches"| node_runner
node_runner -->|"runs analysis"| node_engine_adapter
node_engine_adapter -->|"selects engine"| node_engines
node_engines -->|"selects single mode"| node_single
node_engines -->|"selects chunked mode"| node_chunked
node_engines -->|"selects debate mode"| node_debate
node_single -->|"invokes analysis"| node_invoker
node_chunked -->|"invokes analysis"| node_invoker
node_debate -->|"invokes stages"| node_invoker
node_invoker -->|"runs CLI"| node_llm_cli
node_engine_adapter -->|"calibrates findings"| node_governance
node_engine_adapter -->|"enriches findings"| node_fingerprints
node_engine_adapter -->|"returns results"| node_runner
node_runner -->|"persists task state"| node_models
node_fingerprints -->|"reads/writes records"| node_database
node_reconciliation -->|"stores reconciliation"| node_database
node_runner -->|"reconciles scans"| node_reconciliation
node_report_handler -->|"requests report data"| node_reports
node_reports -->|"reads report records"| node_database
node_api -->|"dispatches"| node_report_handler
node_api -->|"dispatches"| node_issues
node_issues -->|"reads/writes issues"| node_database
node_report_handler -->|"returns report data"| node_frontend
node_runner -.->|"sends notifications"| node_notifier

click node_frontend "https://github.com/fugui/code-shield/blob/main/frontend/src/App.tsx"
click node_scan_ui "https://github.com/fugui/code-shield/blob/main/frontend/src/pages/ScanManagement.tsx"
click node_report_ui "https://github.com/fugui/code-shield/blob/main/frontend/src/components/report/ReportViewer.tsx"
click node_api "https://github.com/fugui/code-shield/blob/main/main.go"
click node_task_handlers "https://github.com/fugui/code-shield/blob/main/handlers/task.go"
click node_schedule "https://github.com/fugui/code-shield/blob/main/cron_jobs/jobs.go"
click node_queue "https://github.com/fugui/code-shield/blob/main/services/queue/queue.go"
click node_dispatcher "https://github.com/fugui/code-shield/blob/main/services/dispatcher/dispatcher.go"
click node_runner "https://github.com/fugui/code-shield/blob/main/services/runner/runner.go"
click node_engine_adapter "https://github.com/fugui/code-shield/blob/main/services/services.go"
click node_engines "https://github.com/fugui/code-shield/blob/main/services/engines/engine.go"
click node_single "https://github.com/fugui/code-shield/blob/main/services/engines/single/engine.go"
click node_chunked "https://github.com/fugui/code-shield/blob/main/services/engines/chunked/engine.go"
click node_debate "https://github.com/fugui/code-shield/blob/main/services/engines/debate/engine.go"
click node_invoker "https://github.com/fugui/code-shield/blob/main/services/invoker/invoker.go"
click node_governance "https://github.com/fugui/code-shield/blob/main/services/governance/calibrator.go"
click node_fingerprints "https://github.com/fugui/code-shield/blob/main/services/defects/diff_engine.go"
click node_reconciliation "https://github.com/fugui/code-shield/blob/main/services/reconciliation/engine.go"
click node_reports "https://github.com/fugui/code-shield/blob/main/services/reports/report_service.go"
click node_models "https://github.com/fugui/code-shield/blob/main/models/models.go"
click node_report_handler "https://github.com/fugui/code-shield/blob/main/handlers/report_handler.go"
click node_issues "https://github.com/fugui/code-shield/blob/main/handlers/issue.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_frontend,node_scan_ui,node_report_ui toneBlue
class node_api,node_task_handlers,node_schedule,node_queue,node_dispatcher,node_runner,node_database toneAmber
class node_engine_adapter,node_engines,node_single,node_chunked,node_debate,node_invoker toneMint
class node_governance,node_fingerprints,node_reconciliation,node_reports toneRose
class node_models,node_report_handler,node_issues,node_user,node_llm_cli,node_notifier toneIndigo
```

## Components

### Web Console

- [React Console](https://github.com/fugui/code-shield/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scan & Campaign UI](https://github.com/fugui/code-shield/blob/main/frontend/src/pages/ScanManagement.tsx): `frontend/src/pages/ScanManagement.tsx`
- [Report Viewer](https://github.com/fugui/code-shield/blob/main/frontend/src/components/report/ReportViewer.tsx): `frontend/src/components/report/ReportViewer.tsx`

### Task Control

- [HTTP API](https://github.com/fugui/code-shield/blob/main/main.go): `main.go`
- [Task Handlers](https://github.com/fugui/code-shield/blob/main/handlers/task.go): `handlers/task.go`
- [Cron Scheduling](https://github.com/fugui/code-shield/blob/main/cron_jobs/jobs.go): `cron_jobs/jobs.go`
- [Persistent Queue](https://github.com/fugui/code-shield/blob/main/services/queue/queue.go): `services/queue/queue.go`
- [Worker Dispatcher](https://github.com/fugui/code-shield/blob/main/services/dispatcher/dispatcher.go): `services/dispatcher/dispatcher.go`
- [Task Runner](https://github.com/fugui/code-shield/blob/main/services/runner/runner.go): `services/runner/runner.go`

### Scanning

- [Engine Adapter](https://github.com/fugui/code-shield/blob/main/services/services.go): `services/services.go`
- [Scan Engines](https://github.com/fugui/code-shield/blob/main/services/engines/engine.go): `services/engines/engine.go`
- [Single Scan](https://github.com/fugui/code-shield/blob/main/services/engines/single/engine.go): `services/engines/single/engine.go`
- [Chunked Scan](https://github.com/fugui/code-shield/blob/main/services/engines/chunked/engine.go): `services/engines/chunked/engine.go`
- [Debate Scan](https://github.com/fugui/code-shield/blob/main/services/engines/debate/engine.go): `services/engines/debate/engine.go`
- [LLM Invokers](https://github.com/fugui/code-shield/blob/main/services/invoker/invoker.go): `services/invoker/invoker.go`

### Defect Lifecycle

- [Finding Governance](https://github.com/fugui/code-shield/blob/main/services/governance/calibrator.go): `services/governance/calibrator.go`
- [Defect Fingerprints](https://github.com/fugui/code-shield/blob/main/services/defects/diff_engine.go): `services/defects/diff_engine.go`
- [Scan Reconciliation](https://github.com/fugui/code-shield/blob/main/services/reconciliation/engine.go): `services/reconciliation/engine.go`
- [Report Service & Export](https://github.com/fugui/code-shield/blob/main/services/reports/report_service.go): `services/reports/report_service.go`

### Persistence & Delivery

- [Domain Models](https://github.com/fugui/code-shield/blob/main/models/models.go): `models/models.go`
- [Report API](https://github.com/fugui/code-shield/blob/main/handlers/report_handler.go): `handlers/report_handler.go`
- [Issue Tracking API](https://github.com/fugui/code-shield/blob/main/handlers/issue.go): `handlers/issue.go`

### Other components

- **Engineer / Admin**
- **LLM CLI Tools**
- **PostgreSQL**
- **Email Notifier**

## Connections

- Engineer / Admin → React Console: uses
- React Console → Scan & Campaign UI: routes to
- React Console → Report Viewer: routes to
- Scan & Campaign UI → HTTP API: requests scans
- Report Viewer → HTTP API: requests reports
- HTTP API → Task Handlers: dispatches
- Task Handlers → Persistent Queue: enqueues tasks
- Cron Scheduling → Persistent Queue: enqueues scheduled work
- Persistent Queue → Worker Dispatcher: claims tasks
- Worker Dispatcher → Task Runner: dispatches
- Task Runner → Engine Adapter: runs analysis
- Engine Adapter → Scan Engines: selects engine
- Scan Engines → Single Scan: selects single mode
- Scan Engines → Chunked Scan: selects chunked mode
- Scan Engines → Debate Scan: selects debate mode
- Single Scan → LLM Invokers: invokes analysis
- Chunked Scan → LLM Invokers: invokes analysis
- Debate Scan → LLM Invokers: invokes stages
- LLM Invokers → LLM CLI Tools: runs CLI
- Engine Adapter → Finding Governance: calibrates findings
- Engine Adapter → Defect Fingerprints: enriches findings
- Engine Adapter → Task Runner: returns results
- Task Runner → Domain Models: persists task state
- Defect Fingerprints → PostgreSQL: reads/writes records
- Scan Reconciliation → PostgreSQL: stores reconciliation
- Task Runner → Scan Reconciliation: reconciles scans
- Report API → Report Service & Export: requests report data
- Report Service & Export → PostgreSQL: reads report records
- HTTP API → Report API: dispatches
- HTTP API → Issue Tracking API: dispatches
- Issue Tracking API → PostgreSQL: reads/writes issues
- Report API → React Console: returns report data
- Task Runner → Email Notifier: sends notifications