# agentgg-dev/agentgg architecture

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

- Interactive diagram: https://gitdiagram.com/agentgg-dev/agentgg
- Repository: https://github.com/agentgg-dev/agentgg

## Overview

agentgg is an agentic SAST scanner with CLI scanning, finding validation, persisted reports, and a local findings viewer. The main workflow runs a repository or diff scan, uses recon to brief analysis agents, checks candidate findings, and saves results for status, revalidation, and browsing. The README documents provider choice, agent catalogs and creation, Semgrep, and fix/dedup workflows; these remain represented where the tree supports them. Relationships are limited to README statements and excerpted or indexed references; unsampled subsystem links are omitted or marked unverified.

Main entry points: [`packages/cli/src/commands/scan.ts`](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/commands/scan.ts) (Scan orchestration), [`packages/cli/src/detect.ts`](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/detect.ts) (Agent detection), [`packages/viewer/app/page.tsx`](https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/page.tsx) (Local report viewer), [`packages/cli/src/cli.ts`](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/cli.ts) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scanning"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_scanflow["Scan orchestration<br/>[scan.ts]"]
  node_recon["Repository recon<br/>[recon.ts]"]
  node_agents["Agent catalog<br/>[agent-catalog.ts]"]
  node_filter["Scope filtering<br/>[pre-filter.ts]"]
end

subgraph group_analysis["Analysis"]
  node_detector["Agent detection<br/>[detect.ts]"]
  node_providers["Model providers<br/>[index.ts]"]
  node_semgrep["Semgrep analysis<br/>[semgrep.ts]"]
  node_validator["Finding validation<br/>[validator.ts]"]
  node_reproduce["Live reproduction<br/>[reproduce.ts]"]
  node_scoring["Finding scoring<br/>[scoring.ts]"]
  node_dedup["Finding deduplication<br/>[deduper.ts]"]
  node_fixer["Finding fixes<br/>[fixer.ts]"]
end

subgraph group_state["Results"]
  node_core[("Domain and persistence<br/>[persistence.ts]")]
  node_report["Markdown reports<br/>[md.ts]"]
end

subgraph group_viewer["Viewer"]
  node_viewer["Local report viewer<br/>[page.tsx]"]
  node_viewerstate["Viewer state loader<br/>[state.ts]"]
  node_findings["Findings table<br/>[FindingsTable.tsx]"]
end

node_user(("CLI user"))
node_provider_service(("Model service"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"starts scans"| node_scanflow
node_scanflow -->|"runs recon"| node_recon
node_scanflow -->|"loads agents"| node_agents
node_scanflow -->|"filters scope"| node_filter
node_scanflow -->|"runs analysis"| node_detector
node_detector -.->|"uses provider"| node_providers
node_providers -.->|"sends requests"| node_provider_service
node_scanflow -.->|"uses Semgrep"| node_semgrep
node_detector -->|"validates findings"| node_validator
node_validator -.->|"requests reproduction"| node_reproduce
node_detector -.->|"scores findings"| node_scoring
node_scanflow -->|"deduplicates findings"| node_dedup
node_scanflow -->|"applies fix phase"| node_fixer
node_scanflow -->|"reads and writes state"| node_core
node_scanflow -.->|"writes reports"| node_report
node_user -->|"opens results"| node_viewer
node_viewer -->|"loads scan state"| node_viewerstate
node_viewer -->|"renders findings"| node_findings
node_viewerstate -->|"reads domain state"| node_core

click node_cli "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/cli.ts"
click node_scanflow "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/commands/scan.ts"
click node_recon "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/recon.ts"
click node_agents "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/agent-catalog.ts"
click node_filter "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/pre-filter.ts"
click node_detector "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/detect.ts"
click node_providers "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/providers/index.ts"
click node_semgrep "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/semgrep.ts"
click node_validator "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/validator.ts"
click node_reproduce "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/validation/reproduce.ts"
click node_scoring "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/scoring.ts"
click node_dedup "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/deduper.ts"
click node_fixer "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/fixer.ts"
click node_core "https://github.com/agentgg-dev/agentgg/blob/main/packages/core/src/persistence.ts"
click node_report "https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/reporters/md.ts"
click node_viewer "https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/page.tsx"
click node_viewerstate "https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/lib/state.ts"
click node_findings "https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/components/FindingsTable.tsx"

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_cli,node_scanflow,node_recon,node_agents,node_filter,node_user toneBlue
class node_detector,node_providers,node_semgrep,node_validator,node_reproduce,node_scoring,node_dedup,node_fixer toneAmber
class node_core,node_report toneMint
class node_viewer,node_viewerstate,node_findings toneRose
class node_provider_service toneIndigo
```

## Components

### Scanning

- [CLI commands](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/cli.ts): `packages/cli/src/cli.ts`
- [Scan orchestration](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/commands/scan.ts): `packages/cli/src/commands/scan.ts`
- [Repository recon](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/recon.ts): `packages/cli/src/recon.ts`
- [Agent catalog](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/agent-catalog.ts): `packages/cli/src/agent-catalog.ts`
- [Scope filtering](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/pre-filter.ts): `packages/cli/src/pre-filter.ts`

### Analysis

- [Agent detection](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/detect.ts): `packages/cli/src/detect.ts`
- [Model providers](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/providers/index.ts): `packages/cli/src/providers/index.ts`
- [Semgrep analysis](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/semgrep.ts): `packages/cli/src/semgrep.ts`
- [Finding validation](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/validator.ts): `packages/cli/src/validator.ts`
- [Live reproduction](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/validation/reproduce.ts): `packages/cli/src/validation/reproduce.ts`
- [Finding scoring](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/scoring.ts): `packages/cli/src/scoring.ts`
- [Finding deduplication](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/deduper.ts): `packages/cli/src/deduper.ts`
- [Finding fixes](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/fixer.ts): `packages/cli/src/fixer.ts`

### Results

- [Domain and persistence](https://github.com/agentgg-dev/agentgg/blob/main/packages/core/src/persistence.ts): `packages/core/src/persistence.ts`
- [Markdown reports](https://github.com/agentgg-dev/agentgg/blob/main/packages/cli/src/reporters/md.ts): `packages/cli/src/reporters/md.ts`

### Viewer

- [Local report viewer](https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/page.tsx): `packages/viewer/app/page.tsx`
- [Viewer state loader](https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/lib/state.ts): `packages/viewer/app/lib/state.ts`
- [Findings table](https://github.com/agentgg-dev/agentgg/blob/main/packages/viewer/app/components/FindingsTable.tsx): `packages/viewer/app/components/FindingsTable.tsx`

### Other components

- **CLI user**
- **Model service**

## Connections

- CLI user → CLI commands: runs commands
- CLI commands → Scan orchestration: starts scans
- Scan orchestration → Repository recon: runs recon (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Agent catalog: loads agents (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Scope filtering: filters scope (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Agent detection: runs analysis (evidence: `packages/cli/src/commands/scan.ts`)
- Agent detection → Model providers: uses provider
- Model providers → Model service: sends requests
- Scan orchestration → Semgrep analysis: uses Semgrep (evidence: `packages/cli/src/commands/scan.ts`)
- Agent detection → Finding validation: validates findings (evidence: `packages/cli/src/detectors/vercel-agent.ts`)
- Finding validation → Live reproduction: requests reproduction
- Agent detection → Finding scoring: scores findings (evidence: `packages/cli/src/scoring.ts`)
- Scan orchestration → Finding deduplication: deduplicates findings (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Finding fixes: applies fix phase (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Domain and persistence: reads and writes state (evidence: `packages/cli/src/commands/scan.ts`)
- Scan orchestration → Markdown reports: writes reports (evidence: `packages/cli/src/commands/scan.ts`)
- CLI user → Local report viewer: opens results
- Local report viewer → Viewer state loader: loads scan state (evidence: `packages/viewer/app/page.tsx`)
- Local report viewer → Findings table: renders findings (evidence: `packages/viewer/app/page.tsx`)
- Viewer state loader → Domain and persistence: reads domain state (evidence: `packages/viewer/app/lib/state.ts`)
