# codescan-ai/codescan architecture

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

## Overview

CodeScanAI is a CLI security scanner. The primary workflow parses scan options, selects all files or changed files, analyzes each file with a structured AI agent, and prints findings; PR scans can also post review comments to GitHub. The V2 agent scanner is the documented current workflow, with separate legacy provider-based scanning still present in the tree. The sampled source supports the V2 wiring shown here; unsampled modules are represented only where README capabilities or paths support them.

Main entry points: [`core/code_scanner/agent_scanner.py`](https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py) (Agent Scanner), [`core/runner_v2.py`](https://github.com/codescan-ai/codescan/blob/main/core/runner_v2.py) (V2 Runner), [`core/utils/file_extractor.py`](https://github.com/codescan-ai/codescan/blob/main/core/utils/file_extractor.py) (Changed Files), [`core/agent.py`](https://github.com/codescan-ai/codescan/blob/main/core/agent.py) (Agent Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_args["Argument Parser<br/>[argument_parser.py]"]
  node_runner["V2 Runner<br/>[runner_v2.py]"]
  node_console["Console Findings<br/>[agent_scanner.py]"]
end

subgraph group_selection["File Selection"]
  node_scanner["Agent Scanner<br/>[agent_scanner.py]"]
  node_fullscan["Directory Scan<br/>[agent_scanner.py]"]
  node_changedfiles["Changed Files<br/>[file_extractor.py]"]
  node_diffmarkers["Changed Lines<br/>[file_extractor.py]"]
end

subgraph group_analysis["AI Analysis"]
  node_agentconfig["Agent Setup<br/>[agent.py]"]
  node_schemas["Finding Schema<br/>[agent.py]"]
  node_agentframework["Pydantic AI"]
  node_legacy["Legacy Scanner<br/>[code_scanner.py]"]
end

subgraph group_integrations["Integrations"]
  node_ghintegration["PR Commenter"]
  node_legacyproviders["Legacy Providers"]
end

node_user(("CLI User"))
node_localgit["Local Git"]
node_githubapi["GitHub API"]
node_aiservice["AI Model Service"]
node_prcomments["PR Review Comments"]

node_user -->|"starts scan"| node_runner
node_runner -->|"parses options"| node_args
node_runner -->|"starts scan"| node_scanner
node_scanner -->|"walks directory"| node_fullscan
node_scanner -->|"requests changed files"| node_changedfiles
node_scanner -->|"requests changed lines"| node_diffmarkers
node_changedfiles -->|"reads local diff"| node_localgit
node_diffmarkers -->|"reads local diff"| node_localgit
node_changedfiles -->|"fetches PR files"| node_githubapi
node_diffmarkers -->|"fetches PR patches"| node_githubapi
node_scanner -->|"configures agent"| node_agentconfig
node_agentconfig -->|"sets output type"| node_schemas
node_agentconfig -->|"creates agent"| node_agentframework
node_scanner -->|"submits file content"| node_agentframework
node_agentframework -->|"requests analysis"| node_aiservice
node_agentframework -->|"returns findings"| node_scanner
node_scanner -->|"prints findings"| node_console
node_scanner -->|"posts findings"| node_ghintegration
node_ghintegration -->|"creates review comment"| node_githubapi
node_githubapi -->|"publishes comments"| node_prcomments
node_legacy -->|"uses provider"| node_legacyproviders

click node_args "https://github.com/codescan-ai/codescan/blob/main/core/utils/argument_parser.py"
click node_runner "https://github.com/codescan-ai/codescan/blob/main/core/runner_v2.py"
click node_scanner "https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py"
click node_fullscan "https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py"
click node_changedfiles "https://github.com/codescan-ai/codescan/blob/main/core/utils/file_extractor.py"
click node_diffmarkers "https://github.com/codescan-ai/codescan/blob/main/core/utils/file_extractor.py"
click node_agentconfig "https://github.com/codescan-ai/codescan/blob/main/core/agent.py"
click node_schemas "https://github.com/codescan-ai/codescan/blob/main/core/agent.py"
click node_console "https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py"
click node_ghintegration "https://github.com/codescan-ai/codescan/blob/main/core/utils/github_integration.py"
click node_legacy "https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/code_scanner.py"
click node_legacyproviders "https://github.com/codescan-ai/codescan/tree/main/core/providers"

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_args,node_runner,node_console,node_user,node_prcomments toneBlue
class node_scanner,node_fullscan,node_changedfiles,node_diffmarkers toneAmber
class node_agentconfig,node_schemas,node_agentframework,node_legacy,node_githubapi toneMint
class node_ghintegration,node_legacyproviders toneRose
class node_localgit,node_aiservice toneIndigo
```

## Components

### CLI

- [Argument Parser](https://github.com/codescan-ai/codescan/blob/main/core/utils/argument_parser.py): `core/utils/argument_parser.py`
- [V2 Runner](https://github.com/codescan-ai/codescan/blob/main/core/runner_v2.py): `core/runner_v2.py`
- [Console Findings](https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py): `core/code_scanner/agent_scanner.py`

### File Selection

- [Agent Scanner](https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py): `core/code_scanner/agent_scanner.py`
- [Directory Scan](https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/agent_scanner.py): `core/code_scanner/agent_scanner.py`
- [Changed Files](https://github.com/codescan-ai/codescan/blob/main/core/utils/file_extractor.py): `core/utils/file_extractor.py`
- [Changed Lines](https://github.com/codescan-ai/codescan/blob/main/core/utils/file_extractor.py): `core/utils/file_extractor.py`

### AI Analysis

- [Agent Setup](https://github.com/codescan-ai/codescan/blob/main/core/agent.py): `core/agent.py`
- [Finding Schema](https://github.com/codescan-ai/codescan/blob/main/core/agent.py): `core/agent.py`
- **Pydantic AI**
- [Legacy Scanner](https://github.com/codescan-ai/codescan/blob/main/core/code_scanner/code_scanner.py): `core/code_scanner/code_scanner.py`

### Integrations

- [PR Commenter](https://github.com/codescan-ai/codescan/blob/main/core/utils/github_integration.py): `core/utils/github_integration.py`
- [Legacy Providers](https://github.com/codescan-ai/codescan/tree/main/core/providers): `core/providers`

### Other components

- **CLI User**
- **Local Git**
- **GitHub API**
- **AI Model Service**
- **PR Review Comments**

## Connections

- CLI User → V2 Runner: starts scan
- V2 Runner → Argument Parser: parses options
- V2 Runner → Agent Scanner: starts scan
- Agent Scanner → Directory Scan: walks directory
- Agent Scanner → Changed Files: requests changed files
- Agent Scanner → Changed Lines: requests changed lines
- Changed Files → Local Git: reads local diff
- Changed Lines → Local Git: reads local diff
- Changed Files → GitHub API: fetches PR files
- Changed Lines → GitHub API: fetches PR patches
- Agent Scanner → Agent Setup: configures agent
- Agent Setup → Finding Schema: sets output type
- Agent Setup → Pydantic AI: creates agent
- Agent Scanner → Pydantic AI: submits file content
- Pydantic AI → AI Model Service: requests analysis
- Pydantic AI → Agent Scanner: returns findings
- Agent Scanner → Console Findings: prints findings
- Agent Scanner → PR Commenter: posts findings
- PR Commenter → GitHub API: creates review comment
- GitHub API → PR Review Comments: publishes comments
- Legacy Scanner → Legacy Providers: uses provider