# sdkman/sdkman-cli architecture

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

- Interactive diagram: https://gitdiagram.com/sdkman/sdkman-cli
- Repository: https://github.com/sdkman/sdkman-cli

## Overview

##### Project type and purpose
- This is an open-source command-line tool (SDKMAN! CLI) written primarily in Bash with a Gradle-driven Groovy test suite and supporting release scripts.
- Purpose: let users on Unix-based systems install, switch, list, and remove SDK versions (called “candidates”) by invoking simple shell commands. It interacts with the remote SDKMAN! REST API and local file system (caching, configuration, unpacking archives).

##### File structure
- Top level
- bin/ – release wrapper scripts
- src/main/bash/ – all CLI command implementations as shell scripts
- src/jreleaser/ & build.gradle/gradle/ – Gradle build and release config
- contrib/completion/bash/ – shell completion definitions
- src/test/groovy & src/test/resources/features/ – Cucumber BDD tests + fixtures
- Patterns
- Monolithic CLI: no separate frontend/backend, but a layered shell-function architecture
- Test harness over Groovy + Cucumber driving the bash scripts via a stubbed environment
- Config & deployment
- Gradle wrapper for builds, Dockerfile for containerized testing/release
- .github/workflows for CI/CD (build, test, release pipelines)

##### README for additional insights
- Confirms CLI-only surface, written in Bash, tested with Cucumber
- Notes the eventual migration of core commands to a Rust implementation; this repo will become a wrapper/launcher

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "User Interface"
    Terminal["User Terminal / Shell"]:::external
  end

  subgraph "CLI Application"
    Launcher["SDKMAN! Launcher"]:::local
    CLIEngine["Core CLI Engine\n(src/main/bash)"]:::local
    Completion["Shell Completion Scripts\n(contrib/completion/bash)"]:::local
    Config["Configuration Store\n(~/.sdkman/config)"]:::local
    Cache["Candidate Cache\n(~/.sdkman/candidates/)"]:::local
    Hooks["Hooks Directory\n(~/.sdkman/hooks)"]:::local
  end

  subgraph "Remote SDKMAN! Services"
    API["REST API Endpoint"]:::external
    Repo["Artifact Repository"]:::external
  end

  subgraph "Test Harness"
    BuildFiles["Gradle Build Files\n(build.gradle, settings.gradle)"]:::test
    GradleScripts["Gradle Scripts\n(gradle/)"]:::test
    JReleaser["JReleaser Config\n(src/jreleaser/)"]:::test
    TestGroovy["Groovy Tests\n(src/test/groovy/)"]:::test
    TestFeatures["Cucumber Features\n(src/test/resources/features/)"]:::test
    HookFixtures["Hook Fixtures\n(src/test/resources/__files/hooks)"]:::test
    Stubs["HTTP Stub Definitions\n(src/test/groovy/sdkman/stubs)"]:::test
    EnvBuilders["Environment Builders\n(src/test/groovy/sdkman/env)"]:::test
    Docker["Docker Container"]:::test
    Workflows["CI/CD Workflows\n(.github/workflows/)"]:::test
  end

  Terminal --> Launcher
  Launcher --> CLIEngine
  CLIEngine --> Config
  CLIEngine --> Cache
  CLIEngine --> Hooks
  Terminal --> Completion

  CLIEngine -->|"HTTP Metadata"| API
  CLIEngine -->|"Download Archives"| Repo
  Repo -->|"Archives"| CLIEngine

  Workflows --> Docker
  Workflows --> BuildFiles
  Workflows --> GradleScripts
  Workflows --> JReleaser
  BuildFiles --> TestGroovy
  BuildFiles --> TestFeatures
  TestGroovy --> Stubs
  TestGroovy --> EnvBuilders
  TestGroovy --> HookFixtures
  TestGroovy --> CLIEngine

  click Launcher "https://github.com/sdkman/sdkman-cli/blob/master/bin/release-binary.sh"
  click CLIEngine "https://github.com/sdkman/sdkman-cli/tree/master/src/main/bash/"
  click Completion "https://github.com/sdkman/sdkman-cli/tree/master/contrib/completion/bash/sdk"
  click BuildFiles "https://github.com/sdkman/sdkman-cli/blob/master/build.gradle"
  click BuildFiles "https://github.com/sdkman/sdkman-cli/blob/master/settings.gradle"
  click GradleScripts "https://github.com/sdkman/sdkman-cli/tree/master/gradle/"
  click JReleaser "https://github.com/sdkman/sdkman-cli/tree/master/src/jreleaser/"
  click TestGroovy "https://github.com/sdkman/sdkman-cli/tree/master/src/test/groovy/"
  click TestFeatures "https://github.com/sdkman/sdkman-cli/tree/master/src/test/resources/features/"
  click HookFixtures "https://github.com/sdkman/sdkman-cli/tree/master/src/test/resources/__files/hooks"
  click Stubs "https://github.com/sdkman/sdkman-cli/tree/master/src/test/groovy/sdkman/stubs"
  click EnvBuilders "https://github.com/sdkman/sdkman-cli/tree/master/src/test/groovy/sdkman/env"
  click Docker "https://github.com/sdkman/sdkman-cli/tree/master/Dockerfile"
  click Workflows "https://github.com/sdkman/sdkman-cli/tree/master/.github/workflows/"

  classDef local fill:#b7e4c7,stroke:#2d6a4f,color:#1b4332
  classDef external fill:#a0c4ff,stroke:#4361ee,color:#1d3557
  classDef test fill:#dee2e6,stroke:#adb5bd,color:#495057
```
