# ernail/verscout architecture

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

- Interactive diagram: https://gitdiagram.com/ernail/verscout
- Repository: https://github.com/ernail/verscout

## Overview

##### Project Purpose & Type
- This is a single-binary CLI tool written in Go. Its purpose is to analyze a Git repository’s tags and commit history (using Conventional Commits) to print the latest version and compute the next version. It does not perform any automatic tagging, bumping, or publishing.
- The README clarifies key use cases (“verscout latest” and “verscout next”) and explains its lightweight nature for use in CI pipelines.

##### Key Components
a. Entry Point & Command Routing:
- “main.go” as the entry point which initializes the CLI application.
- “cmd” directory components (latest.go, next.go, root.go) that handle command-specific logic. These files essentially parse the commands and flags, and delegate work.
b. Core Internal Modules:
- “semverutils” package which contains logic for semantic version parsing/updating based on Conventional Commits.
c. External Dependencies & CI/CD:
- Although the tool is self-contained, note the presence of GitHub workflows, .golangci, and other configuration files that support CI/CD and quality control.
d. Configuration & Testing Infrastructure:
- Supporting tool configurations (pre-commit configuration, linting configs, Taskfile for testing/building). These ensure code quality but are not directly in the runtime flow.

##### Interactions & Data Flow
- From each command’s execution, indicate that the control flows into the “internal” modules:
- “gitutils” is used to extract the Git data (e.g., list of tags, commits).
- “semverutils” interprets that Git data following semantic versioning rules and Conventional Commits to either determine a latest version or compute the next version.
- Optionally, note that if no valid version or commit bumping candidate is found, the tool simply prints nothing and exits with code 0.

##### Architectural Patterns & Design Principles
- The design shows a clear separation of concerns:
- Command parsing (cmd package) is separated from business logic (internal packages).
- This modular design improves testability and reusability (as seen with separate test files for cmd and internal modules).
- The repository structure (with a dedicated “internal” folder) emphasizes encapsulation of core logic away from the CLI interface.

- A node representing “User/CLI Input” invoking the application.
- “main.go” as the entry point that routes commands.
- “cmd/latest” and “cmd/next” components handling specific flags and behaviors.
- “internal/gitutils” for repository interactions (note responsibilities like tag extraction and commit fetching).
- “internal/semverutils” for semantic version processing (logic for parsing, comparing, and bumping versions).
- A visual element indicating the Git repository as an external dependency providing version tags and commits.
- Optionally, include supporting infrastructure like CI/CD pipelines (GitHub Actions) and testing/linting tools but keep these as annotations rather than core runtime parts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    user("User/CLI Input"):::entry
    main("main.go"):::entry
    gitRepo(("Git Repository")):::external

    %% CLI Commands Subgraph
    subgraph "CLI Commands"
        cmdRoot("cmd/root.go"):::cli
        cmdLatest("cmd/latest.go"):::cli
        cmdNext("cmd/next.go"):::cli
    end

    %% Internal Modules Subgraph
    subgraph "Internal Modules"
        gitutils("internal/gitutils"):::internal
        semverutils("internal/semverutils\n(Conventional Commits)"):::internal
    end

    %% CI/CD & Quality Control Configurations
    subgraph "CI/CD & Quality Configs"
        cicd(".github/workflows/cicd.yaml"):::config
        golangci(".golangci.yaml"):::config
        precommit(".pre-commit-config.yaml"):::config
        taskfile("taskfile.yaml"):::config
    end

    %% Data Flow
    user -->|"invokes"| main
    main -->|"routes"| cmdRoot
    cmdRoot -->|"triggers Latest Command"| cmdLatest
    cmdRoot -->|"triggers Next Command"| cmdNext
    cmdLatest -->|"fetchTags"| gitutils
    cmdLatest -->|"determineLatest"| semverutils
    cmdNext -->|"fetchTags"| gitutils
    cmdNext -->|"computeNext"| semverutils
    gitutils -->|"retrievesGitData"| gitRepo

    %% Click Events
    click main "https://github.com/ernail/verscout/blob/main/main.go"
    click cmdRoot "https://github.com/ernail/verscout/blob/main/cmd/root.go"
    click cmdLatest "https://github.com/ernail/verscout/blob/main/cmd/latest.go"
    click cmdNext "https://github.com/ernail/verscout/blob/main/cmd/next.go"
    click gitutils "https://github.com/ernail/verscout/blob/main/internal/gitutils/gitutils.go"
    click semverutils "https://github.com/ernail/verscout/blob/main/internal/semverutils/semverutils.go"
    click cicd "https://github.com/ernail/verscout/blob/main/.github/workflows/cicd.yaml"
    click golangci "https://github.com/ernail/verscout/blob/main/.golangci.yaml"
    click precommit "https://github.com/ernail/verscout/blob/main/.pre-commit-config.yaml"
    click taskfile "https://github.com/ernail/verscout/blob/main/taskfile.yaml"

    %% Styles
    classDef entry fill:#A8DBA8,stroke:#333,stroke-width:2px;
    classDef cli fill:#BEE3F8,stroke:#333,stroke-width:2px;
    classDef internal fill:#FFF5BA,stroke:#333,stroke-width:2px;
    classDef external fill:#F9D5E5,stroke:#333,stroke-width:2px;
    classDef config fill:#E6E6E6,stroke:#333,stroke-width:2px;
```
