# theaniketraj/scan architecture

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

- Interactive diagram: https://gitdiagram.com/theaniketraj/scan
- Repository: https://github.com/theaniketraj/scan

## Overview

#### Purpose and Entry Points
SCAN is a Kotlin/JVM Gradle plugin for detecting secrets in project files and optionally failing builds. Consumers apply the published Gradle plugin and run its scan task; plugin metadata is registered at `src/main/resources/META-INF/gradle-plugins/com.scan.properties`. The root implementation is under `src/main/kotlin/com/scan/plugin/ScanPlugin.kt`; a separate sample/functional plugin module exists at `plugin/src/main/kotlin/org/example/ScanPlugin.kt`.

#### Gradle Integration Boundary
`ScanPlugin` installs the `scan` extension and scan task into a target Gradle build. `ScanExtension` exposes build-facing configuration, while `ScanTask` orchestrates execution and determines build failure behavior. Core paths: `src/main/kotlin/com/scan/plugin/ScanPlugin.kt`, `src/main/kotlin/com/scan/plugin/ScanExtension.kt`, `src/main/kotlin/com/scan/plugin/ScanTask.kt`.

#### Scan Orchestration and Domain Model
The engine receives a `ScanConfiguration` and scan context, coordinates file scanning, and returns structured findings/results rather than Gradle-specific objects. This separates reusable detection logic from task lifecycle concerns. Core paths: `src/main/kotlin/com/scan/core/ScanEngine.kt`, `src/main/kotlin/com/scan/core/FileScanner.kt`, `src/main/kotlin/com/scan/core/ScanResult.kt`.

#### File Selection and Filtering
Before content analysis, filters constrain scan scope by extension, path, test-file status, and whitelisted content. This is the primary noise/performance boundary between repository files and detection stages. Core paths: `src/main/kotlin/com/scan/filters/FilterInterface.kt`, `src/main/kotlin/com/scan/filters/PathFilter.kt`, `src/main/kotlin/com/scan/filters/WhitelistFilter.kt`.

#### Multi-Strategy Detection
Eligible file content is evaluated through composable detectors: regex/pattern matching, entropy analysis, and context-aware classification. Findings carry secret type, severity, confidence, validation state, and location-oriented result data. Core paths: `src/main/kotlin/com/scan/detectors/CompositeDetector.kt`, `src/main/kotlin/com/scan/detectors/PatternDetector.kt`, `src/main/kotlin/com/scan/detectors/EntropyDetector.kt`.

#### Pattern and Configuration Inputs
Built-in secret definitions are packaged as YAML resources; category classes represent API, crypto, database, and general secret patterns. Configuration loading supports repository-specific scan settings and custom patterns, with examples under `config-examples/`. Core paths: `src/main/resources/patterns/default-patterns.yml`, `src/main/kotlin/com/scan/utils/ConfigurationLoader.kt`, `config-examples/scan-config.yml`.

#### Reporting and External Integrations
Results flow into a reporting abstraction with console, JSON, HTML, and SARIF emitters. SARIF is the boundary for code-scanning consumers; a GitHub integration component supports GitHub Code Scanning workflows. Core paths: `src/main/kotlin/com/scan/reporting/ReportGenerator.kt`, `src/main/kotlin/com/scan/reporting/SarifReporter.kt`, `src/main/kotlin/com/scan/integration/GitHubCodeScanning.kt`.

#### Runtime, Delivery, and Documentation Site
The scanner runs in the Gradle/Kotlin JVM ecosystem and is built from the multi-project Gradle setup in `settings.gradle.kts` and `build.gradle.kts`. GitHub Actions provide CI and Pages deployment. The independent `landing/` Next.js/TypeScript application publishes product and documentation content, not scanner execution. Core paths: `.github/workflows/ci.yml`, `.github/workflows/pages.yml`, `landing/app/page.tsx`.

Main entry points: [`src/main/kotlin/com/scan/detectors/CompositeDetector.kt`](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/CompositeDetector.kt) (CompositeDetector), [`src/main/kotlin/com/scan/plugin/ScanTask.kt`](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanTask.kt) (ScanTask), [`src/main/kotlin/com/scan/core/ScanEngine.kt`](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/ScanEngine.kt) (ScanEngine), [`src/main/kotlin/com/scan/filters/FilterInterface.kt`](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/FilterInterface.kt) (Scope filters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gradle["Gradle plugin"]
  node_plugin_metadata["Plugin metadata<br/>Gradle descriptor"]
  node_scan_plugin["ScanPlugin<br/>Gradle plugin<br/>[ScanPlugin.kt]"]
  node_scan_extension["ScanExtension<br/>build configuration<br/>[ScanExtension.kt]"]
  node_scan_task["ScanTask<br/>Gradle task<br/>[ScanTask.kt]"]
end

subgraph group_engine["Scan engine"]
  node_configuration_loader["ConfigurationLoader<br/>config loader"]
  node_scan_config_example["Scan config example<br/>YAML configuration<br/>[scan-config.yml]"]
  node_scan_engine["ScanEngine<br/>scan orchestrator<br/>[ScanEngine.kt]"]
  node_file_scanner["FileScanner<br/>file traversal<br/>[FileScanner.kt]"]
  node_scan_result["ScanResult<br/>findings model<br/>[ScanResult.kt]"]
end

subgraph group_detection["Detection pipeline"]
  node_filters["Scope filters<br/>filter chain<br/>[FilterInterface.kt]"]
  node_path_filter["PathFilter<br/>path filter<br/>[PathFilter.kt]"]
  node_whitelist_filter["WhitelistFilter<br/>content filter<br/>[WhitelistFilter.kt]"]
  node_composite_detector["CompositeDetector<br/>detector coordinator"]
  node_pattern_detector["PatternDetector<br/>pattern detector<br/>[PatternDetector.kt]"]
  node_entropy_detector["EntropyDetector<br/>entropy detector<br/>[EntropyDetector.kt]"]
  node_default_patterns["Default patterns<br/>YAML pattern catalog"]
end

subgraph group_outputs["Reporting"]
  node_report_generator["ReportGenerator<br/>reporting abstraction<br/>[ReportGenerator.kt]"]
  node_sarif_reporter["SarifReporter<br/>SARIF emitter<br/>[SarifReporter.kt]"]
  node_github_scanning["GitHub Code Scanning<br/>GitHub integration"]
end

subgraph group_delivery["Delivery"]
  node_gradle_build["Gradle multi-project build<br/>build system<br/>[build.gradle.kts]"]
  node_ci_workflow["CI workflow<br/>GitHub Actions<br/>[ci.yml]"]
  node_pages_workflow["Pages workflow<br/>GitHub Actions<br/>[pages.yml]"]
  node_landing_site["Landing site<br/>Next.js application<br/>[page.tsx]"]
end

node_plugin_metadata -->|"registers"| node_scan_plugin
node_scan_plugin -->|"installs"| node_scan_extension
node_scan_plugin -->|"registers"| node_scan_task
node_scan_extension -->|"configures"| node_scan_task
node_scan_task -->|"loads settings"| node_configuration_loader
node_scan_config_example -.->|"example input"| node_configuration_loader
node_configuration_loader -->|"provides ScanConfiguration"| node_scan_engine
node_scan_task -->|"executes"| node_scan_engine
node_scan_engine -->|"coordinates"| node_file_scanner
node_file_scanner -->|"screens files"| node_filters
node_path_filter -.->|"implements"| node_filters
node_whitelist_filter -.->|"implements"| node_filters
node_filters -->|"eligible content"| node_composite_detector
node_composite_detector -->|"uses"| node_pattern_detector
node_composite_detector -->|"uses"| node_entropy_detector
node_default_patterns -->|"definitions"| node_pattern_detector
node_composite_detector -->|"findings"| node_scan_result
node_scan_engine -->|"returns"| node_scan_result
node_scan_result -->|"reported as"| node_report_generator
node_report_generator -->|"emits"| node_sarif_reporter
node_sarif_reporter -->|"code-scanning output"| node_github_scanning
node_gradle_build -->|"built in"| node_ci_workflow
node_landing_site -->|"deployed by"| node_pages_workflow

click node_plugin_metadata "https://github.com/theaniketraj/scan/blob/main/src/main/resources/META-INF/gradle-plugins/com.scan.properties"
click node_scan_plugin "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanPlugin.kt"
click node_scan_extension "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanExtension.kt"
click node_scan_task "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanTask.kt"
click node_configuration_loader "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/utils/ConfigurationLoader.kt"
click node_scan_config_example "https://github.com/theaniketraj/scan/blob/main/config-examples/scan-config.yml"
click node_scan_engine "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/ScanEngine.kt"
click node_file_scanner "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/FileScanner.kt"
click node_filters "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/FilterInterface.kt"
click node_path_filter "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/PathFilter.kt"
click node_whitelist_filter "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/WhitelistFilter.kt"
click node_composite_detector "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/CompositeDetector.kt"
click node_pattern_detector "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/PatternDetector.kt"
click node_entropy_detector "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/EntropyDetector.kt"
click node_default_patterns "https://github.com/theaniketraj/scan/blob/main/src/main/resources/patterns/default-patterns.yml"
click node_scan_result "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/ScanResult.kt"
click node_report_generator "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/reporting/ReportGenerator.kt"
click node_sarif_reporter "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/reporting/SarifReporter.kt"
click node_github_scanning "https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/integration/GitHubCodeScanning.kt"
click node_gradle_build "https://github.com/theaniketraj/scan/blob/main/build.gradle.kts"
click node_ci_workflow "https://github.com/theaniketraj/scan/blob/main/.github/workflows/ci.yml"
click node_pages_workflow "https://github.com/theaniketraj/scan/blob/main/.github/workflows/pages.yml"
click node_landing_site "https://github.com/theaniketraj/scan/blob/main/landing/app/page.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_plugin_metadata,node_scan_plugin,node_scan_extension,node_scan_task toneBlue
class node_configuration_loader,node_scan_config_example,node_scan_engine,node_file_scanner,node_scan_result toneAmber
class node_filters,node_path_filter,node_whitelist_filter,node_composite_detector,node_pattern_detector,node_entropy_detector,node_default_patterns toneMint
class node_report_generator,node_sarif_reporter,node_github_scanning toneRose
class node_gradle_build,node_ci_workflow,node_pages_workflow,node_landing_site toneIndigo
```

## Components

### Gradle plugin

- [Plugin metadata](https://github.com/theaniketraj/scan/blob/main/src/main/resources/META-INF/gradle-plugins/com.scan.properties): Gradle descriptor · Registers the published plugin ID. · `src/main/resources/META-INF/gradle-plugins/com.scan.properties`
- [ScanPlugin](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanPlugin.kt): Gradle plugin · Installs scan configuration and task. · `src/main/kotlin/com/scan/plugin/ScanPlugin.kt`
- [ScanExtension](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanExtension.kt): build configuration · `src/main/kotlin/com/scan/plugin/ScanExtension.kt`
- [ScanTask](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/plugin/ScanTask.kt): Gradle task · Orchestrates scanning and fails builds when configured. · `src/main/kotlin/com/scan/plugin/ScanTask.kt`

### Scan engine

- [ConfigurationLoader](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/utils/ConfigurationLoader.kt): config loader · Loads repository settings and custom patterns. · `src/main/kotlin/com/scan/utils/ConfigurationLoader.kt`
- [Scan config example](https://github.com/theaniketraj/scan/blob/main/config-examples/scan-config.yml): YAML configuration · `config-examples/scan-config.yml`
- [ScanEngine](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/ScanEngine.kt): scan orchestrator · Coordinates reusable scan logic outside Gradle lifecycle. · `src/main/kotlin/com/scan/core/ScanEngine.kt`
- [FileScanner](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/FileScanner.kt): file traversal · `src/main/kotlin/com/scan/core/FileScanner.kt`
- [ScanResult](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/core/ScanResult.kt): findings model · Carries typed, located, severity and confidence-aware findings. · `src/main/kotlin/com/scan/core/ScanResult.kt`

### Detection pipeline

- [Scope filters](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/FilterInterface.kt): filter chain · Limits files by path, extension, test status, and whitelisted content. · `src/main/kotlin/com/scan/filters/FilterInterface.kt`
- [PathFilter](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/PathFilter.kt): path filter · `src/main/kotlin/com/scan/filters/PathFilter.kt`
- [WhitelistFilter](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/filters/WhitelistFilter.kt): content filter · `src/main/kotlin/com/scan/filters/WhitelistFilter.kt`
- [CompositeDetector](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/CompositeDetector.kt): detector coordinator · Combines detection strategies for eligible content. · `src/main/kotlin/com/scan/detectors/CompositeDetector.kt`
- [PatternDetector](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/PatternDetector.kt): pattern detector · `src/main/kotlin/com/scan/detectors/PatternDetector.kt`
- [EntropyDetector](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/detectors/EntropyDetector.kt): entropy detector · `src/main/kotlin/com/scan/detectors/EntropyDetector.kt`
- [Default patterns](https://github.com/theaniketraj/scan/blob/main/src/main/resources/patterns/default-patterns.yml): YAML pattern catalog · Built-in API, crypto, database, and general secret definitions. · `src/main/resources/patterns/default-patterns.yml`

### Reporting

- [ReportGenerator](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/reporting/ReportGenerator.kt): reporting abstraction · Emits console, JSON, HTML, and SARIF reports. · `src/main/kotlin/com/scan/reporting/ReportGenerator.kt`
- [SarifReporter](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/reporting/SarifReporter.kt): SARIF emitter · Produces code-scanning interchange output. · `src/main/kotlin/com/scan/reporting/SarifReporter.kt`
- [GitHub Code Scanning](https://github.com/theaniketraj/scan/blob/main/src/main/kotlin/com/scan/integration/GitHubCodeScanning.kt): GitHub integration · `src/main/kotlin/com/scan/integration/GitHubCodeScanning.kt`

### Delivery

- [Gradle multi-project build](https://github.com/theaniketraj/scan/blob/main/build.gradle.kts): build system · Builds the Kotlin/JVM plugin. · `build.gradle.kts`
- [CI workflow](https://github.com/theaniketraj/scan/blob/main/.github/workflows/ci.yml): GitHub Actions · `.github/workflows/ci.yml`
- [Pages workflow](https://github.com/theaniketraj/scan/blob/main/.github/workflows/pages.yml): GitHub Actions · Deploys the independent documentation site. · `.github/workflows/pages.yml`
- [Landing site](https://github.com/theaniketraj/scan/blob/main/landing/app/page.tsx): Next.js application · Publishes product and documentation content, not scanner execution. · `landing/app/page.tsx`

## Connections

- Plugin metadata → ScanPlugin: registers
- ScanPlugin → ScanExtension: installs
- ScanPlugin → ScanTask: registers
- ScanExtension → ScanTask: configures
- ScanTask → ConfigurationLoader: loads settings
- Scan config example → ConfigurationLoader: example input
- ConfigurationLoader → ScanEngine: provides ScanConfiguration
- ScanTask → ScanEngine: executes
- ScanEngine → FileScanner: coordinates
- FileScanner → Scope filters: screens files
- PathFilter → Scope filters: implements
- WhitelistFilter → Scope filters: implements
- Scope filters → CompositeDetector: eligible content
- CompositeDetector → PatternDetector: uses
- CompositeDetector → EntropyDetector: uses
- Default patterns → PatternDetector: definitions
- CompositeDetector → ScanResult: findings
- ScanEngine → ScanResult: returns
- ScanResult → ReportGenerator: reported as
- ReportGenerator → SarifReporter: emits
- SarifReporter → GitHub Code Scanning: code-scanning output
- Gradle multi-project build → CI workflow: built in
- Landing site → Pages workflow: deployed by