# ewenquim/entropy architecture

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

- Interactive diagram: https://gitdiagram.com/ewenquim/entropy
- Repository: https://github.com/ewenquim/entropy

## Overview

##### Main Components
- Command-Line Interface (CLI) Handler: This component parses command-line arguments (flags such as –top, –ext, –ignore-ext) and gathers the list of target files and directories.
- File System Interface: Responsible for traversing directories (e.g., the provided “testdata” samples and user-specified folders/files) and reading file contents.
- Scanning / Core Logic Engine:
- Core Scanner: Contains the main algorithm that reads each file data line-by-line.
- Entropy Calculator: Implements the entropy calculation logic (likely based on Shannon entropy) to measure the randomness of each line.
- Secret Detector: Applies thresholds (or rank ordering as indicated by the –top flag) to determine which lines are considered “suspicious.”
- Output Formatter / Reporter: Formats the discovered high entropy lines and routes the output to the console (or other mediums if extended).
- (Optional) Testing Harness: Represented by main_test.go and the testdata directory. This part validates the scanning logic against various sample files (e.g., sample Python, Go, JavaScript files in testdata).

##### Relationships and Interactions
- The CLI component initiates the process by capturing user inputs and then passes configuration parameters to the core scanning engine.
- The File System Interface reads from the given file paths and feeds content to the Core Scanner.
- The Scanner computes entropy for each line using the Entropy Calculator, flags lines based on the Secret Detector’s criteria, and then funnels results to the Output Formatter.
- Testing interacts with the scanning engine to verify accuracy and performance against a suite of controlled examples.

##### Core Architectural Patterns and Design Principles
- Separation of Concerns: Each component (CLI, File IO, Core Scanning, and Output) is distinctly separated to ensure easier testing and potential future replacement.
- Modularity: The design allows for isolated improvements (such as enhancing the entropy algorithm) without touching components like file reading or CLI parsing.
- Extensibility: Given multiple installation options (source, brew, docker) and various input flags, the design accommodates additional options or improved scanning logic without major refactoring.

##### Relevant Technologies and Frameworks
- Programming Language: Go
- Build and Dependency management: go.mod, go.sum, and Makefile show that operations including testing and building are automated.
- CI/CD Components: GitHub workflows (.github/workflows/*) automate testing and publishing.
- Containerization: Dockerfile and Docker support show that the app is also packaged for containerized deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        cli["CLI Handler (parses flags: -ext, -ignore-ext, -top)"]:::runtime
    end

    %% File System Layer
    subgraph "File System Layer"
        fs["File System Interface (traverses directories & reads file contents)"]:::runtime
    end

    %% Core Scanning Module with detailed core logic
    subgraph "Core Scanning Module"
        scanner["Core Scanner (performs file-by-file & line-by-line analysis)"]:::core
        entropy["Entropy Calculator (read line→calc_Shannon_entropy→compare_threshold→flag)"]:::core
        detector["Secret Detector (applies thresholds & ranks based on -top flag)"]:::core
    end

    %% Output & Reporting Layer
    subgraph "Output & Reporting"
        output["Output Formatter/Reporter (aggregates & displays high entropy lines)"]:::runtime
    end

    %% Testing Components
    subgraph "Testing"
        testing["Testing Harness (validates scanning logic)"]:::aux
        testdata["Testdata Samples (sample files for traversal & testing)"]:::aux
    end

    %% Flow connections
    cli -->|"configures"| fs
    fs -->|"feeds file content"| scanner
    scanner -->|"analyzes each line"| entropy
    entropy -->|"passes entropy metrics"| detector
    detector -->|"produces flagged results"| output
    testing -->|"validates"| scanner
    testdata -->|"supplies sample files"| testing

    %% Click Events for component mapping
    click cli "https://github.com/ewenquim/entropy/blob/master/main.go"
    click fs "https://github.com/ewenquim/entropy/blob/master/main.go"
    click scanner "https://github.com/ewenquim/entropy/blob/master/main.go"
    click output "https://github.com/ewenquim/entropy/blob/master/main.go"
    click testing "https://github.com/ewenquim/entropy/blob/master/main_test.go"
    click testdata "https://github.com/ewenquim/entropy/tree/master/testdata"

    %% Styles
    classDef runtime fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef core fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef aux fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
```
