# secfathy/flash architecture

> Architecture diagram of the GitHub repository secfathy/flash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/secfathy/flash
- Repository: https://github.com/secfathy/flash

## Overview

##### Project Type and Purpose
- Flash is a command-line, AI-powered code vulnerability scanner.
- It’s structured as a modular, monolithic Go application, with clear separation between:
- CLI orchestration (main.go + scanner.go)
- Configuration management (config/*.go + config.json)
- Scanning logic (internal/scanner)
- AI integrations (internal/ai/openai, internal/ai/azureai)
- Report generation (internal/markdown)

##### File Structure
- Top-level:
- main.go & scanner.go: entry points, CLI flags
- config.json + config/: config loader/structs
- internal/scanner: code parsing & tokenization
- internal/ai: adapters for OpenAI & Azure OpenAI
- internal/markdown: formatting results
- No web UI, no external database—solely external AI APIs and file I/O.

##### Key Components
- CLI Orchestrator
– Parses flags (`-file`, `-dir`, `-save`, `-use-azure`)
– Reads config.json via config module
– Invokes scanner
- Scanner Module
– Reads source files
– Tokenizes or splits into analyzable chunks
– Hands off code snippets to AI adapters
- AI Adapters
– OpenAI Adapter (internal/ai/openai)
– Azure OpenAI Adapter (internal/ai/azureai)
– Each implements a common interface: SendPrompt() → ReceiveAnalysis()
- Vulnerability Analyzer
– Interprets AI responses, extracts vulnerabilities, PoCs, fixes
- Markdown Report Generator
– Formats findings into Markdown
– Saves to disk under `-save` directory
- External Services
– OpenAI REST API
– Azure OpenAI REST API

##### Relationships & Data Flow
1. User invokes CLI → CLI Orchestrator
2. Orchestrator loads configuration
3. Orchestrator calls Scanner Module with file/path
4. Scanner reads files → splits into chunks → passes chunks to AI Adapter
5. AI Adapter calls external API → retrieves analysis
6. Vulnerability Analyzer processes AI response
7. Markdown Generator builds report → writes files locally

##### Architectural Patterns & Principles
- Modular Monolith: clear package boundaries, single binary
- Adapter Pattern: interchangeable AI backends (OpenAI vs. Azure)
- Single Responsibility: each package has a focused purpose
- Dependency Injection: CLI passes config and choice of AI adapter

##### Putting It All Together
- Center the “CLI Orchestrator” at the top.
- Branch down to Config Loader and Scanner.
- Both adapters connect to respective External API clouds.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Orchestrator"]:::internal
    ConfigLoader["Config Loader"]:::internal
    Scanner["Scanner Module"]:::internal
    Decision{"use-azure?"}
    OpenAIAdapter["OpenAI Adapter"]:::external
    AzureAdapter["Azure OpenAI Adapter"]:::external
    VulnerAnalyzer["Vulnerability Analyzer"]:::internal
    MarkdownGen["Markdown Generator"]:::internal
    FileSystem[("File System")]:::fs
    OpenAIAPI(("OpenAI REST API")):::cloud
    AzureAPI(("Azure OpenAI REST API")):::cloud

    CLI -->|parses flags & loads config| ConfigLoader
    CLI -->|invokes scanner| Scanner
    ConfigLoader -->|provides config| Scanner
    Scanner --> Decision
    Decision -->|false| OpenAIAdapter
    Decision -->|true| AzureAdapter
    OpenAIAdapter -->|sends prompt| OpenAIAPI
    AzureAdapter -->|sends prompt| AzureAPI
    OpenAIAPI -->|returns analysis| OpenAIAdapter
    AzureAPI -->|returns analysis| AzureAdapter
    OpenAIAdapter --> VulnerAnalyzer
    AzureAdapter --> VulnerAnalyzer
    VulnerAnalyzer --> MarkdownGen
    MarkdownGen -->|writes report| FileSystem

    click CLI "https://github.com/secfathy/flash/blob/main/main.go"
    click CLI "https://github.com/secfathy/flash/blob/main/scanner.go"
    click ConfigLoader "https://github.com/secfathy/flash/blob/main/config/config.go"
    click ConfigLoader "https://github.com/secfathy/flash/blob/main/config/ascii.go"
    click ConfigLoader "https://github.com/secfathy/flash/blob/main/config.json"
    click Scanner "https://github.com/secfathy/flash/blob/main/internal/scanner/scanner.go"
    click OpenAIAdapter "https://github.com/secfathy/flash/blob/main/internal/ai/openai/openai.go"
    click AzureAdapter "https://github.com/secfathy/flash/blob/main/internal/ai/azureai/azureai.go"
    click MarkdownGen "https://github.com/secfathy/flash/blob/main/internal/markdown/markdown.go"

    classDef internal fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef external fill:#d4edda,stroke:#000,stroke-width:1px
    classDef fs fill:#e2e3e5,stroke:#000,stroke-width:1px
    classDef cloud fill:#f8d7da,stroke:#000,stroke-width:1px
```
