# cybrota/scharf architecture

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

- Interactive diagram: https://gitdiagram.com/cybrota/scharf
- Repository: https://github.com/cybrota/scharf

## Overview

##### Main Components
- CLI Frontend: The entry point of the application (main.go) handles command-line arguments, routing commands (such as “find” and “lookup”), and displaying outputs.
- Workflow Analyzer (Scanner Module): This is represented by scanner.go and its associated tests (scanner_test.go). Its role is to traverse directories (as provided by the “--root” flag) and parse GitHub workflow files to identify third-party actions.
- Resolver/Lookup Module: The resolver component (resolver.go with tests in resolver_test.go) is dedicated to determining the correct commit SHA for a given GitHub Action reference.
- Git Integration Module: The git.go (with git_test.go) likely interfaces with GitHub repositories or local Git data to verify or fetch commit information.
- Reporting Engine: Although implicit, this part of the system takes the output from scan and lookup operations and formats it into CSV, JSON, or Syslog reports for analysis.
- CI/CD Pipeline and Release Automation: The .github/workflows directory with YAML files (ci.yml, release.yml, security.yml), along with .goreleaser.yaml, indicate automated testing, building, and release processes.
- Installer Script: install.sh provides a user-friendly script for installing the binary on supported systems.

##### Relationships and Interactions
- Command invocations (find or lookup) are handled by the CLI frontend, which then delegates functionality:
– For “find” – it calls the Workflow Analyzer to scan file trees and parse workflow files.
– For “lookup” – it utilizes the Resolver to determine the appropriate commit SHA.
- The Git Integration Module is likely used by both the scanner and resolver components to interact with Git repositories or query remote GitHub APIs.
- The Reporting Engine takes processed data from either the scanning or lookup flows to generate the desired output formats.
- The CI/CD components (represented by the GitHub workflows) ensure that code quality and security checks are automated, and that releases are generated automatically via the release configuration.

##### Architectural Patterns/Design Principles
- Separation of Concerns: Each major functionality (“scanning”, “resolving”, and “reporting”) is handled in its own module, making the code modular and easier to maintain.
- Test-Driven Approach: Multiple test files (e.g., git_test.go, resolver_test.go, scanner_test.go) show that the project emphasizes unit testing and code robustness.
- CLI Design Pattern: The tool uses a common CLI pattern to parse and route commands along with command-specific options.
- Automation and Continuous Integration: CI/CD workflows and release automation reflect mature software development practices.

##### Relevant Technologies and Frameworks
- Go Language: The entire project is written in Go, leveraging its native binary compilation.
- GitHub Actions: Used in the project’s workflow files (.github/workflows) to manage CI/CD.
- goreleaser: As indicated by the .goreleaser.yaml, this tool is used for releasing the binary.
- Shell Scripting: The install.sh script provides an installation mechanism for end users on Linux and Mac OS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Layer
    subgraph "Core Modules"
        CLI["CLI Frontend"]:::cli
        Analyzer["Workflow Analyzer"]:::module
        Resolver["Resolver/Lookup Module"]:::module
        Reporting["Reporting Engine"]:::report
        Git["Git Integration Module"]:::module
    end

    %% Unit Tests Layer
    subgraph "Unit Tests"
        ScannerTests["Scanner Tests"]:::test
        ResolverTests["Resolver Tests"]:::test
        GitTests["Git Tests"]:::test
    end

    %% CI/CD and Release Automation Layer
    subgraph "CI/CD Pipeline & Release Automation"
        Workflows["GitHub Workflows"]:::ci
        ReleaseConfig["Release Config"]:::ci
    end

    %% Supporting Utilities
    Installer["Installer Script"]:::util

    %% Relationships
    %% CLI commands delegation
    CLI -->|"find"| Analyzer
    CLI -->|"lookup"| Resolver

    %% Modules communicate with Reporting
    Analyzer -->|"sends data"| Reporting
    Resolver -->|"sends data"| Reporting

    %% Modules dependent on Git functions
    Analyzer -->|"queries"| Git
    Resolver -->|"queries"| Git

    %% Unit Tests connections (associated with modules)
    Analyzer --> ScannerTests
    Resolver --> ResolverTests
    Git --> GitTests

    %% CI/CD process supports build/release
    Workflows -->|"triggers"| ReleaseConfig
    ReleaseConfig -->|"publish binary"| CLI

    %% Installer is used separately to deploy the CLI binary
    Installer --- CLI

    %% Styles
    classDef cli fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef module fill:#C8FACC,stroke:#333,stroke-width:2px;
    classDef report fill:#FFF3B0,stroke:#333,stroke-width:2px;
    classDef ci fill:#E0E0E0,stroke:#333,stroke-width:2px;
    classDef util fill:#F7C6C7,stroke:#333,stroke-width:2px;
    classDef test fill:#E6CCFF,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/cybrota/scharf/blob/main/main.go"
    click Analyzer "https://github.com/cybrota/scharf/blob/main/scanner.go"
    click Resolver "https://github.com/cybrota/scharf/blob/main/resolver.go"
    click Git "https://github.com/cybrota/scharf/blob/main/git.go"
    click ScannerTests "https://github.com/cybrota/scharf/blob/main/scanner_test.go"
    click ResolverTests "https://github.com/cybrota/scharf/blob/main/resolver_test.go"
    click GitTests "https://github.com/cybrota/scharf/blob/main/git_test.go"
    click Workflows "https://github.com/cybrota/scharf/tree/main/.github/workflows"
    click ReleaseConfig "https://github.com/cybrota/scharf/blob/main/.goreleaser.yaml"
    click Installer "https://github.com/cybrota/scharf/blob/main/install.sh"
```
