# lokesh-balla/gvm architecture

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

- Interactive diagram: https://gitdiagram.com/lokesh-balla/gvm
- Repository: https://github.com/lokesh-balla/gvm

## Overview

##### Project Type and Purpose
- gvm is a command-line tool (CLI) written in Go that provides version management for Go installations.
- It follows the Command Pattern: a root command (`gvm`) delegates to subcommands (`install`, `list`, `use`, `uninstall`).

##### File Structure Analysis
- Top-level:
- cmd/           → contains subcommand implementations (install.go, list.go, use.go, uninstall.go, root.go)
- main.go        → entrypoint that initializes the CLI
- install.sh     → bootstrap installer script
- docs/          → user documentation for GitHub Pages
- .github/       → CI/CD workflows (build, lint, release)
- Makefile       → build, test, release targets
- Patterns:
- Modular CLI commands
- Zero external Go dependencies (standard library only)
- Configuration via file system (`~/.gvm`, `~/.gvm/bin`)

##### Key README Insights
- Zero-dependency Go binary
- Supports standard OSes (Linux, Darwin, FreeBSD, etc.)
- Installs Go versions by downloading archives from official Go releases
- Manages PATH entries to switch Go versions

##### Main Components
A. CLI Layer
- Entry Point (main.go)
- Command Dispatcher (root command)
- Subcommand Modules (install, list, use, uninstall)
B. Core Logic Layer
- Version Resolver (determines download URL based on requested version)
- Downloader (HTTP client to fetch Go archives)
- Installer (unpack into `~/.gvm/versions/<version>`)
- Environment Manager (symlinks in `~/.gvm/bin`, PATH adjustments)
C. Persistence Layer
- File System
- `~/.gvm/versions/` (installed Go versions)
- `~/.gvm/bin/` (active version shim)
- Config files (if any)
D. External Services
- Go official downloads
- GitHub (for release binaries, CI status)
E. Developer Tooling / CI (optional separate view)
- GitHub Actions workflows (.github/workflows)
- golangci-lint, CodeQL scans
- Build & Release pipeline

##### Interactions & Data Flows
- User invokes `gvm <subcommand> [args]` → CLI Layer
- CLI calls Core Logic
- install: resolves version → downloads archive → writes to FS → updates shim
- Reads `~/.gvm/versions/` → returns versions
- use: updates symlink in `~/.gvm/bin` → modifies PATH for shell
- uninstall: removes version directory from FS
- Core Logic reads/writes File System
- On install/uninstall: may call external HTTP API (Go download server)

##### Architectural Patterns & Principles
- Command Pattern for extendability (add new subcommands easily)
- Layered architecture: CLI → Core Logic → Persistence → External
- Single responsibility per module (each command only handles its own logic)
- Minimal external dependencies (ease of compilation & portability)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        User["User"]:::external
        Main["main.go"]:::module
        RootCmd["Command Dispatcher<br/>(root.go)"]:::module
        InstallCmd["Install Subcommand<br/>(install.go)"]:::module
        ListCmd["List Subcommand<br/>(list.go)"]:::module
        UseCmd["Use Subcommand<br/>(use.go)"]:::module
        UninstallCmd["Uninstall Subcommand<br/>(uninstall.go)"]:::module
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        direction TB
        Resolver["Version Resolver"]:::module
        Downloader["Downloader"]:::module
        Installer["Installer"]:::module
        EnvManager["Environment Manager"]:::module
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        FileSystem[("File System<br/>(~/.gvm)")]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoServer["Go Download Server"]:::external
        GitHub["GitHub"]:::external
    end

    %% CI/CD & Tooling
    subgraph "Developer Tooling / CI"
        direction TB
        CI["CI/CD Workflows<br/>(.github/workflows/)"]:::ci
        Make["Makefile"]:::ci
        GoMod["go.mod & go.sum"]:::ci
        Docs["Documentation<br/>(docs/)"]:::ci
        InstallerScript["Bootstrap Script<br/>(install.sh)"]:::ci
    end

    %% Runtime Flow
    User -->|"invokes gvm"| Main
    Main -->|"initializes"| RootCmd
    RootCmd -->|"dispatches install"| InstallCmd
    RootCmd -->|"dispatches list"| ListCmd
    RootCmd -->|"dispatches use"| UseCmd
    RootCmd -->|"dispatches uninstall"| UninstallCmd

    InstallCmd -->|"resolve version"| Resolver
    InstallCmd -->|"download archive"| Downloader
    InstallCmd -->|"unpack install"| Installer
    Installer -->|"write to"| FileSystem
    Downloader -.->|"HTTP download"| GoServer

    ListCmd -->|"read versions"| FileSystem

    UseCmd -->|"update symlink"| EnvManager
    EnvManager -->|"modify PATH/symlink"| FileSystem

    UninstallCmd -->|"remove version"| FileSystem

    %% Dev Tooling Connections
    CI --> Make
    CI --> GoMod
    CI --> Docs
    CI --> InstallerScript

    %% Click Events
    click Main "https://github.com/lokesh-balla/gvm/blob/main/main.go"
    click RootCmd "https://github.com/lokesh-balla/gvm/blob/main/cmd/root.go"
    click InstallCmd "https://github.com/lokesh-balla/gvm/blob/main/cmd/install.go"
    click ListCmd "https://github.com/lokesh-balla/gvm/blob/main/cmd/list.go"
    click UseCmd "https://github.com/lokesh-balla/gvm/blob/main/cmd/use.go"
    click UninstallCmd "https://github.com/lokesh-balla/gvm/blob/main/cmd/uninstall.go"
    click InstallerScript "https://github.com/lokesh-balla/gvm/blob/main/install.sh"
    click Docs "https://github.com/lokesh-balla/gvm/tree/main/docs/"
    click CI "https://github.com/lokesh-balla/gvm/tree/main/.github/workflows/"
    click Make "https://github.com/lokesh-balla/gvm/tree/main/Makefile"
    click GoMod "https://github.com/lokesh-balla/gvm/blob/main/go.mod"

    %% Styles
    classDef module fill:#D0E8FF,stroke:#005B9F,color:#000000
    classDef storage fill:#DFF2D8,stroke:#3C763D,color:#000000
    classDef external fill:#F2F2F2,stroke:#A6A6A6,color:#000000,stroke-dasharray: 5 5
    classDef ci fill:#F9E79F,stroke:#B7950B,color:#000000
```
