Architecture Diagrams

Visual representations of govman's architecture and workflows.

System Architecture

High-Level Component Diagram

┌──────────────────────────────────────────────────────────────┐
│                          User                                │
└───────────────┬──────────────────────────────────────────────┘
                │
                │ Commands
                ▼
┌───────────────────────────────────────────────────────────────┐
│                      CLI Layer                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ install  │ │   use    │ │   list   │ │  init    │  ...   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘        │
│       └────────────┴────────────┴─────────────┘              │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────────────────┐
│                    Manager Layer                              │
│  ┌─────────────────────────────────────────────────────┐     │
│  │  Orchestrate:                                       │     │
│  │  - Workflows    - State Management                  │     │
│  │  - Coordination - Error Recovery                    │     │
│  └─────────────────────────────────────────────────────┘     │
└─┬──────┬──────┬───────┬──────┬──────┬──────────────────────┘
  │      │      │       │      │      │
  ▼      ▼      ▼       ▼      ▼      ▼
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────────┐
│Cfg │ │Dldr│ │ Go │ │Shll│ │Syml│ │Progress│
│    │ │    │ │API │ │    │ │ink │ │        │
└────┘ └─┬──┘ └──┬─┘ └────┘ └────┘ └────────┘
         │       │
         ▼       ▼
    ┌─────────────────┐
    │  External APIs  │
    │  - go.dev/dl    │
    │  - Downloads    │
    └─────────────────┘

Installation Workflow

Install Command Sequence Diagram

User        CLI          Manager      Golang       Downloader    FileSystem
 │           │              │            │              │             │
 │ install   │              │            │              │             │
 │ 1.21.5    │              │            │              │             │
 ├──────────►│              │            │              │             │
 │           │              │            │              │             │
 │           │ Install()    │            │              │             │
 │           ├─────────────►│            │              │             │
 │           │              │            │              │             │
 │           │              │ GetRelease()              │             │
 │           │              ├───────────►│              │             │
 │           │              │            │              │             │
 │           │              │            │ Fetch API    │             │
 │           │              │            ├─────────────►│             │
 │           │              │            │ (https://    │             │
 │           │              │            │  go.dev/dl)  │             │
 │           │              │            │◄─────────────┤             │
 │           │              │            │ JSON data    │             │
 │           │              │◄───────────┤              │             │
 │           │              │ Release    │              │             │
 │           │              │            │              │             │
 │           │              │ Download() │              │             │
 │           │              ├────────────┼─────────────►│             │
 │           │              │            │              │             │
 │           │              │            │              │ HTTP GET    │
 │           │              │            │              ├────────────►│
 │           │              │            │              │ tar.gz      │
 │           │              │            │              │◄────────────┤
 │           │              │            │              │             │
 │           │              │            │              │ Verify      │
 │           │              │            │              │ SHA-256     │
 │           │              │            │              │             │
 │           │              │◄───────────┼──────────────┤             │
 │           │              │            │              │             │
 │           │              │ Extract()  │              │             │
 │           │              ├────────────┼─────────────►│             │
 │           │              │            │              │             │
 │           │              │            │              │ Extract     │
 │           │              │            │              │ to versions/│
 │           │              │            │              ├────────────►│
 │           │              │            │              │◄────────────┤
 │           │              │◄───────────┼──────────────┤             │
 │           │              │            │              │             │
 │           │              │ UpdateSymlink()           │             │
 │           │              ├───────────────────────────┼────────────►│
 │           │              │            │              │ current →   │
 │           │              │            │              │ go1.21.5    │
 │           │              │◄──────────────────────────┼─────────────┤
 │           │◄─────────────┤            │              │             │
 │           │              │            │              │             │
 │ Success   │              │            │              │             │
 │◄──────────┤              │            │              │             │

Version Switching Workflow

Use Command Flow

┌─────────┐
│  Start  │
└────┬────┘
     │
     ▼
┌──────────────────┐
│ Parse version    │
│ govman use 1.20.5│
└────┬─────────────┘
     │
     ▼
┌──────────────────────┐      ┌─────────────────┐
│ Version installed?   │─No──►│ Show error      │
│ Check filesystem     │      │ Suggest install │
└────┬─────────────────┘      └─────────────────┘
     │Yes
     ▼
┌──────────────────────┐
│ Read current symlink │
│ Get active version   │
└────┬─────────────────┘
     │
     ▼
┌──────────────────────┐      ┌─────────────────┐
│ Same as requested?   │─Yes─►│ Already active  │
└────┬─────────────────┘      │ No action       │
     │No                       └─────────────────┘
     ▼
┌──────────────────────┐
│ Remove old symlink   │
│ os.Remove(current)   │
└────┬─────────────────┘
     │
     ▼
┌──────────────────────┐
│ Create new symlink   │
│ current → go1.20.5   │
└────┬─────────────────┘
     │
     ▼
┌──────────────────────┐
│ Update PATH (shell)  │
│ Export new bin path  │
└────┬─────────────────┘
     │
     ▼
┌──────────────────────┐
│ Success              │
│ Show message         │
└────┬─────────────────┘
     │
     ▼
┌─────────┐
│   End   │
└─────────┘

Auto-Switch Mechanism

Directory Change Hook Flow

User Changes Directory
        │
        ▼
┌────────────────────┐
│ Shell Hook Trigger │
│ (chpwd/PROMPT_CMD) │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ govman refresh     │
│ --silent           │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐      ┌────────────────┐
│.govman-version     │─No──►│ Keep current   │
│exists in curr dir? │      │ No action      │
└────────┬───────────┘      └────────────────┘
         │Yes
         ▼
┌────────────────────┐
│ Read .govman-version│
│ version = "1.21.5" │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐      ┌────────────────┐
│ Already on version?│─Yes─►│ No change      │
└────────┬───────────┘      └────────────────┘
         │No
         ▼
┌────────────────────┐
│ Switch to version  │
│ Update symlink     │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ Reload PATH        │
│ (silent mode)      │
└────────┬───────────┘
         │
         ▼
    New version active

Data Flow Architecture

Request/Response Flow

┌──────────────────────────────────────────────────────────┐
│                    Request Flow                          │
└──────────────────────────────────────────────────────────┘

User Command
    │
    ├─► CLI Layer
    │       │
    │       ├─► Parse & Validate
    │       │
    │       └─► Manager Layer
    │               │
    │               ├─► Business Logic
    │               │
    │               └─► Service Layer
    │                       │
    │                       ├─► Execute Operation
    │                       │
    │                       └─► External Resources
    │
    ◄──────────────── Response Flow ─────────────────
    │
    ├─► Format Output
    │
    └─► Display to User

Component Interaction

Install Operation Components

┌──────────────────────────────────────────────────────────────┐
│                    Install Operation                         │
└──────────────────────────────────────────────────────────────┘

InstallCmd ──────► Manager.Install()
                      │
                      ├──► Config
                      │    └─► Get paths, settings
                      │
                      ├──► Golang API
                      │    ├─► Fetch releases
                      │    └─► Find version
                      │
                      ├──► Downloader
                      │    ├─► Download archive
                      │    ├─► Verify checksum
                      │    └─► Extract files
                      │
                      ├──► Symlink
                      │    └─► Update 'current'
                      │
                      └──► Logger
                           └─► Report progress

Shell Integration Architecture

┌────────────────────────────────────────────────────────────┐
│                  Shell Integration                         │
└────────────────────────────────────────────────────────────┘

┌──────────┐
│   Bash   │
└────┬─────┘
     │
┌────▼─────┐         ┌──────────────────────────────────┐
│   Zsh    │────────►│     Shell Interface              │
└────┬─────┘         │  ┌────────────────────────────┐  │
     │               │  │ Name()                     │  │
┌────▼─────┐         │  │ ConfigFile()               │  │
│   Fish   │────────►│  │ PathCommand()              │  │
└────┬─────┘         │  │ SetupCommands()            │  │
     │               │  │ IsAvailable()              │  │
┌────▼─────┐         │  └────────────────────────────┘  │
│PowerShell│────────►│                                  │
└──────────┘         └──────────────────────────────────┘
                                    │
                                    ▼
                          ┌──────────────────┐
                          │ Shell Config     │
                          │ ┌──────────────┐ │
                          │ │ PATH setup   │ │
                          │ │ Auto-switch  │ │
                          │ │ Hooks        │ │
                          │ └──────────────┘ │
                          └──────────────────┘

State Management

Version State Diagram

┌─────────────────────────────────────────────────────────┐
│                  Version States                         │
└─────────────────────────────────────────────────────────┘

        ┌─────────────┐
        │ Not Installed│
        └──────┬──────┘
               │ govman install
               ▼
        ┌─────────────┐
        │  Downloading │◄─────┐
        └──────┬──────┘       │
               │               │ Retry
               │ Complete      │ (on error)
               ▼               │
        ┌─────────────┐       │
        │  Verifying  │───────┘
        └──────┬──────┘
               │ Valid
               ▼
        ┌─────────────┐
        │  Extracting  │
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │  Installed   │
        └──────┬──────┘
               │
               ├──► govman use ──► ┌─────────┐
               │                    │ Active  │
               │                    └────┬────┘
               │                         │
               │    ◄────────────────────┘
               │         govman use (other)
               │
               └──► govman uninstall ──► ┌─────────────┐
                                          │Not Installed│
                                          └─────────────┘

Configuration Hierarchy

┌────────────────────────────────────────────────────────┐
│            Configuration Loading Priority              │
└────────────────────────────────────────────────────────┘

    ┌──────────────────────┐
    │  Command-line Flags  │  (Highest Priority)
    └──────────┬───────────┘
               │ Override
               ▼
    ┌──────────────────────┐
    │ Environment Variables│
    └──────────┬───────────┘
               │ Override
               ▼
    ┌──────────────────────┐
    │  Config File YAML    │
    └──────────┬───────────┘
               │ Override
               ▼
    ┌──────────────────────┐
    │   Default Values     │  (Lowest Priority)
    └──────────────────────┘

Final Configuration

Cache Strategy

Caching Architecture

┌────────────────────────────────────────────────────────┐
│                   Cache Flow                           │
└────────────────────────────────────────────────────────┘

Request for resource
        │
        ▼
┌───────────────┐
│ Check Cache   │
└───────┬───────┘
        │
        ├──► ┌─────────────┐     ┌──────────────┐
        │    │ Cache Hit   │────►│ Validate     │
        │    │ File exists │     │ Age < TTL    │
        │    └─────────────┘     └───┬──────────┘
        │                            │ Valid
        │                            ▼
        │                   ┌──────────────────┐
        │                   │ Return from cache│
        │                   └──────────────────┘
        │
        └──► ┌─────────────┐
             │ Cache Miss  │
             │ or Invalid  │
             └──────┬──────┘
                    │
                    ▼
           ┌────────────────┐
           │ Fetch Resource │
           │ from Source    │
           └────────┬───────┘
                    │
                    ▼
           ┌────────────────┐
           │ Store in Cache │
           └────────┬───────┘
                    │
                    ▼
           ┌────────────────┐
           │ Return Resource│
           └────────────────┘

Cache Types:
- Release data: 1 hour TTL
- Downloaded archives: Indefinite (verified by checksum)

Error Handling Flow

┌────────────────────────────────────────────────────────┐
│               Error Handling Strategy                  │
└────────────────────────────────────────────────────────┘

Operation Start
        │
        ▼
┌───────────────┐
│ Try Operation │
└───────┬───────┘
        │
        ├──► Success ──► Continue
        │
        └──► Error
                │
                ▼
        ┌───────────────┐
        │ Log Error     │
        │ With Context  │
        └───────┬───────┘
                │
                ▼
        ┌───────────────┐      ┌──────────────┐
        │ Recoverable?  │─Yes─►│ Retry Logic  │
        └───────┬───────┘      │ Backoff      │
                │No             └──────┬───────┘
                │                      │
                │              ┌───────▼───────┐
                │              │ Max Retries?  │
                │              └───────┬───────┘
                │                      │ Yes
                ▼                      │
        ┌───────────────┐            │
        │ Cleanup       │◄───────────┘
        │ Rollback      │
        └───────┬───────┘
                │
                ▼
        ┌───────────────┐
        │ Format Error  │
        │ Add Help Text │
        └───────┬───────┘
                │
                ▼
        ┌───────────────┐
        │ Return to User│
        │ With Guidance │
        └───────────────┘

File System Layout

~/.govman/
├── versions/                    # Installed Go versions
│   ├── go1.20.5/
│   │   ├── bin/
│   │   │   ├── go              # Go binary
│   │   │   └── gofmt           # Go tools
│   │   ├── src/                # Go source
│   │   └── pkg/                # Go packages
│   ├── go1.21.5/
│   │   └── (same structure)
│   └── current → go1.21.5      # Symlink to active version
│
├── cache/                       # Download cache
│   ├── go1.20.5.linux-amd64.tar.gz
│   ├── go1.21.5.linux-amd64.tar.gz
│   └── releases.json            # Cached release data
│
└── config.yaml                  # Configuration file

Deployment Architecture

┌────────────────────────────────────────────────────────┐
│                Distribution Methods                    │
└────────────────────────────────────────────────────────┘

┌──────────────┐         ┌──────────────┐
│ GitHub       │         │  Direct      │
│ Releases     │         │  Download    │
└──────┬───────┘         └──────┬───────┘
       │                        │
       ├────────────┬───────────┤
       │            │           │
       ▼            ▼           ▼
   ┌────────┐  ┌────────┐  ┌────────┐
   │ Linux  │  │ macOS  │  │Windows │
   │ Binary │  │ Binary │  │ Binary │
   └────┬───┘  └────┬───┘  └────┬───┘
        │           │           │
        └───────────┴───────────┘
                    │
                    ▼
           ┌────────────────┐
           │ Install Script │
           │ - Shell        │
           │ - PowerShell   │
           └────────┬───────┘
                    │
                    ▼
           ┌────────────────┐
           │ Local Install  │
           │ /usr/local/bin │
           └────────────────┘

See Also

• Architecture - Detailed architecture description
• Data Flow - Data flow documentation
• Project Structure - Code organization

Visual representations make complex systems easier to understand! 📊