# aaronhaddad/nvm architecture

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

- Interactive diagram: https://gitdiagram.com/aaronhaddad/nvm
- Repository: https://github.com/aaronhaddad/nvm

## Overview

##### Project type and purpose
- This is an open-source command-line tool (nvm: Node Version Manager) written in shell script.
- It provides a shell-function interface to install, switch between, and manage multiple Node.js (and io.js) versions per user/shell.
- It is invoked by the user’s POSIX shell, sources core scripts, interacts with the file system (in $NVM_DIR), and fetches binaries (or source) from remote servers.

##### Key components
a. User & Shell Environment
- User’s terminal (bash, zsh, ksh, dash) → sources `nvm.sh` → exposes `nvm` commands.
b. CLI Entrypoint & Core Scripts
- install.sh (bootstrapper)
- nvm.sh (core library of functions: install, use, alias, ls, rm, etc.)
- bash_completion (auto-completion support)
c. Local Storage (File System under $NVM_DIR)
- versions/…
- alias/…
- default-packages
- ‘current’ symlink (if enabled)
d. External Tools & Shell Utilities
- curl / wget / git (for download/clone)
- tar / make / gcc (for building from source)
- tarball extractor, checksum utilities (sha256sum)
e. Remote Services
- Node.js / io.js distribution servers (e.g. https://nodejs.org/dist)
- GitHub (for git-based installs & updates)
f. Test Suite & CI
- Urchin-based test harness: fast tests (mocked filesystem calls) and slow tests (actual installs)
- GitHub Actions, Travis CI, Docker (nvm-dev container) orchestrating test runs

##### Relationships & Data Flows
- User → Shell → `nvm` function → core script (nvm.sh)
- Core script ↔ Local Storage ($NVM_DIR):
- read/write version directories, alias files, default-packages file
- create/remove symlinks
- Core script → External Tools (curl/git/tar) → Remote Service (download binary or source)
- Core script → External Tools (make, gcc) when building from source
- Test Suite → mocks or real core scripts → Local Storage → External Tools/Remote Services (in slow tests)
- CI Platform → triggers tests, lint, releases, coverage

##### Architectural patterns & design principles
- Monolithic CLI layered design:
- Bootstrap layer (install.sh) → library layer (nvm.sh) → completion layer
- Filesystem-driven state: all installed versions, aliases, and defaults stored in well-known directories under $NVM_DIR.
- Plugin-style shell integration: deeper integration via avn/nvshim hooks or shell functions.
- Idempotent and declarative commands: user invokes commands; state changes on disk.
- Extensibility points: alias mechanism, custom default-packages file, mirror URLs via env vars.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & Shell Environment"
        ShellUser["Terminal"]:::internal
        nvm_sh["nvm.sh"]:::internal
        bash_completion["bash_completion"]:::internal
    end
    ShellUser -->|sources| nvm_sh
    ShellUser -->|sources| bash_completion

    subgraph "CLI Entry & Core Scripts"
        install_sh["install.sh"]:::internal
        core_nvm["nvm.sh"]:::internal
        nvm_exec["nvm-exec"]:::internal
    end
    install_sh --> core_nvm
    core_nvm --> nvm_exec

    subgraph "Local Storage ($NVM_DIR)"
        versions["versions/…"]:::storage
        aliasDir["alias/…"]:::storage
        default_pkgs["default-packages"]:::storage
        current_link["current (symlink)"]:::storage
    end
    core_nvm -->|read/write| versions
    core_nvm -->|read/write| aliasDir
    core_nvm -->|read/write| default_pkgs
    core_nvm -->|manage symlink| current_link

    subgraph "External Tools"
        curl["curl / wget / git"]:::externalTools
        tarMake["tar / make / gcc / sha256sum"]:::externalTools
    end
    core_nvm -->|download/install| curl
    core_nvm -->|extract/build| tarMake

    subgraph "Remote Services"
        nodeDist["Node.js dist servers"]:::externalServices
        githubServ["GitHub"]:::externalServices
    end
    curl -->|fetch binaries| nodeDist
    curl -->|clone repos| githubServ
    tarMake -->|build from source| nodeDist

    subgraph "Test Suite & CI"
        testSuite["Test Harness (fast & slow)"]:::testCi
        githubActions["GitHub Actions"]:::testCi
        travisCI["Travis CI"]:::testCi
        docker["Docker (nvm-dev container)"]:::testCi
    end
    githubActions --> testSuite
    travisCI --> testSuite
    testSuite -->|invokes| core_nvm
    testSuite -->|mocks FS| versions
    testSuite -->|uses tools| curl
    testSuite -->|uses tools| tarMake

    click nvm_sh "https://github.com/aaronhaddad/nvm/blob/master/nvm.sh"
    click bash_completion "https://github.com/aaronhaddad/nvm/tree/master/bash_completion"
    click install_sh "https://github.com/aaronhaddad/nvm/blob/master/install.sh"
    click core_nvm "https://github.com/aaronhaddad/nvm/blob/master/nvm.sh"
    click nvm_exec "https://github.com/aaronhaddad/nvm/tree/master/nvm-exec"
    click testSuite "https://github.com/aaronhaddad/nvm/tree/master/test/"
    click githubActions "https://github.com/aaronhaddad/nvm/blob/master/.github/workflows/tests.yml"
    click travisCI "https://github.com/aaronhaddad/nvm/blob/master/.travis.yml"
    click docker "https://github.com/aaronhaddad/nvm/tree/master/Dockerfile"

    classDef internal fill:#cfe2ff,stroke:#004085;
    classDef storage fill:#d4edda,stroke:#155724;
    classDef externalTools fill:#fff3cd,stroke:#856404;
    classDef externalServices fill:#e2e3e5,stroke:#6c757d;
    classDef testCi fill:#f8d7da,stroke:#721c24;
```
