# ipinfo/cli architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, multi-binary CLI toolkit written in Go, centered on the `ipinfo` command and a suite of subsidiary networking utilities (grepip, grepdomain, cidr2ip, etc.).
- Its primary purpose is to perform IP‐related lookups (geolocation, ASN, range conversions, summarization) against the IPinfo.io API and format results, with broad cross-platform distribution via package managers, Docker, and direct binaries.

##### File structure
- Top‐level coordinates:
- `.github/workflows/` – CI/CD pipelines for packaging (Chocolatey, DockerHub, Winget, Gemfury, GitHub Releases).
- `scripts/` – local build, lint, release helpers.
- Multiple subdirectories like `ipinfo/`, `grepip/`, `cidr2ip/`, etc. Each houses:
– `main.go` (entry point).
– `cmd_*.go` (subcommands).
– Platform build scripts (`build.sh`, `build-all-platforms.sh`, `.ps1`, `macos.sh`, `docker.sh`, `deb.sh`, etc.).
– `dist/DEBIAN/control` for Debian packaging.
- `lib/` – shared libraries (argument completion, IP utilities, domain logic, output helpers).
- `go.mod`, `go.sum` and `vendor/` for dependency management.
- Pattern: A single‐repo “monorepo” of multiple Go CLI binaries that share common libraries and CI/CD workflows for multi-platform packaging.

##### README for additional insights
- Describes core functionality: subcommands, installation modalities.
- Highlights supported platforms and packaging methods (Homebrew, PPA, Debian, Arch AUR, FreeBSD ports, Scoop, Winget, Chocolatey, Docker).
- Mentions auto-completion support via shared `complete` library.

a. Main components
1. Developer Environment
– Source code in GitHub (monorepo) → Go toolchain → Local scripts for build/test.
2. Version Control & CI/CD
– GitHub Actions workflows trigger on push/tag → run build/test → package.
3. Shared Libraries
– `lib/complete` (shell completion) and `lib/iputil` (IP/domain logic), plus helper modules.
4. CLI Binaries
– `ipinfo` (core CLI)
– Subsidiary tools: `grepip`, `grepdomain`, `cidr2ip`, `cidr2range`, `range2cidr`, `range2ip`, `randip`, `splitcidr`, `matchip`, `prips`, `mmdb`, etc.
5. Packaging & Distribution
– Artifacts: Docker images, Debian packages, Windows installers, Homebrew bottles, Winget manifests, Chocolatey packages, Gemfury releases, direct GitHub Releases assets.
6. End Users & Runtimes
– Users on Linux/Mac/Windows/FreeBSD/Arch → install via native manager or Docker
– Runtime: CLI binary → parse args → call IPinfo.io API (external service) → render console output (optionally CSV/JSON/map).

b. Relationships and interactions
- Developer → pushes code → GitHub
- GitHub Actions → orchestrate build/test → generate binaries & packages
- Packages → published to registries (DockerHub, GitHub Releases, APT PPA, Homebrew, Chocolatey, Winget, Gemfury)
- End users → install from registry → run CLI → interact with IPinfo.io API over HTTPS → display results
- Shared `lib` packages used at compile time by all binaries.

c. Architectural patterns & design principles
- Monorepo for multi-binary CLI delivery
- Shared library code (DRY) via `lib/` and Go modules
- Single responsibility for each binary (one tool = one function)
- CI/CD as code (workflows in `.github/workflows`)
- Multi-platform packaging baked into per-binary scripts + centralized workflows

d. Relevant technologies
- Go (modules, `go install`, cross-compilation)
- GitHub Actions (CI/CD)
- Shell scripts & PowerShell for platform builds
- Package ecosystems: Debian (`.deb`), Homebrew, AUR, Chocolatey, Winget, Scoop, Docker
- External service: IPinfo.io REST API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment" 
        direction TB
        DevEnv["Local Scripts & Go Toolchain"]:::code
    end

    %% Version Control & CI/CD
    subgraph "Version Control & CI/CD" 
        direction TB
        GitHub["GitHub Monorepo"]:::code
        CICD["GitHub Actions Workflows"]:::build
    end

    %% Dependency Management
    DepMgmt["Dependency Management\n(go.mod, go.sum, vendor/)"]:::code

    %% Shared Libraries
    subgraph "Shared Libraries" 
        direction TB
        LibComplete["Argument Completion (lib/complete/)"]:::code
        LibDomain["Domain & Utilities (lib/domain.go, help_detailed.go, stack.go)"]:::code
        LibIPUtil["IP & CIDR Logic (lib/iputil/)"]:::code
    end

    %% CLI Binaries
    subgraph "CLI Binaries" 
        direction TB
        IPINFO["ipinfo CLI"]:::code
        GREPIP["grepip CLI"]:::code
        GREPDOMAIN["grepdomain CLI"]:::code
        CIDR2IP["cidr2ip CLI"]:::code
        CIDR2RANGE["cidr2range CLI"]:::code
        RANGE2CIDR["range2cidr CLI"]:::code
        RANGE2IP["range2ip CLI"]:::code
        RANDIP["randip CLI"]:::code
        SPLITCIDR["splitcidr CLI"]:::code
        MATCHIP["matchip CLI"]:::code
        PRIPS["prips CLI"]:::code
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution" 
        direction TB
        Chocolatey["Chocolatey Packages"]:::cylinder
        DockerHub["Docker Images"]:::cylinder
        Debian["Debian/APT, Homebrew, AUR, Scoop, Winget"]:::cylinder
        GitHubRel["GitHub Releases"]:::cylinder
        Gemfury["Gemfury Releases"]:::cylinder
    end

    %% End Users & Runtime
    subgraph "End Users & Runtime" 
        direction TB
        Users["End Users (Linux/Mac/Windows/FreeBSD/Arch)"]:::cloud
        CliRun["Run CLI Binary"]:::code
        IPINFOAPI["IPinfo.io REST API"]:::db
    end

    %% Relationships
    DevEnv -->|push code| GitHub
    GitHub -->|trigger| CICD
    CICD -->|uses| DepMgmt
    CICD -->|builds| LibComplete
    CICD -->|builds| LibDomain
    CICD -->|builds| LibIPUtil
    CICD -->|compiles| IPINFO
    CICD -->|compiles| GREPIP
    CICD -->|compiles| GREPDOMAIN
    CICD -->|compiles| CIDR2IP
    CICD -->|compiles| CIDR2RANGE
    CICD -->|compiles| RANGE2CIDR
    CICD -->|compiles| RANGE2IP
    CICD -->|compiles| RANDIP
    CICD -->|compiles| SPLITCIDR
    CICD -->|compiles| MATCHIP
    CICD -->|compiles| PRIPS

    CICD -->|publishes| Chocolatey
    CICD -->|pushes images| DockerHub
    CICD -->|publishes packages| Debian
    CICD -->|releases assets| GitHubRel
    CICD -->|publishes| Gemfury

    Users -->|install| Chocolatey
    Users -->|docker pull| DockerHub
    Users -->|apt/brew/pacman/scoop/winget install| Debian
    Users -->|download| GitHubRel
    Users -->|gem install| Gemfury

    Users -->|run| CliRun
    CliRun -->|invoke| IPINFOAPI
    CliRun -->|output| Users

    %% Click Events
    click DevEnv "https://github.com/ipinfo/cli/tree/master/scripts/"
    click GitHub "https://github.com/ipinfo/cli/tree/master/.github/workflows/"
    click DepMgmt "https://github.com/ipinfo/cli/blob/master/go.mod"
    click DepMgmt "https://github.com/ipinfo/cli/blob/master/go.sum"
    click DepMgmt "https://github.com/ipinfo/cli/tree/master/vendor/"
    click LibComplete "https://github.com/ipinfo/cli/tree/master/lib/complete/"
    click LibDomain "https://github.com/ipinfo/cli/blob/master/lib/domain.go"
    click LibDomain "https://github.com/ipinfo/cli/blob/master/lib/help_detailed.go"
    click LibDomain "https://github.com/ipinfo/cli/blob/master/lib/stack.go"
    click LibIPUtil "https://github.com/ipinfo/cli/tree/master/lib/iputil/"
    click IPINFO "https://github.com/ipinfo/cli/tree/master/ipinfo/"
    click GREPIP "https://github.com/ipinfo/cli/tree/master/grepip/"
    click GREPDOMAIN "https://github.com/ipinfo/cli/tree/master/grepdomain/"
    click CIDR2IP "https://github.com/ipinfo/cli/tree/master/cidr2ip/"
    click CIDR2RANGE "https://github.com/ipinfo/cli/tree/master/cidr2range/"
    click RANGE2CIDR "https://github.com/ipinfo/cli/tree/master/range2cidr/"
    click RANGE2IP "https://github.com/ipinfo/cli/tree/master/range2ip/"
    click RANDIP "https://github.com/ipinfo/cli/tree/master/randip/"
    click SPLITCIDR "https://github.com/ipinfo/cli/tree/master/splitcidr/"
    click MATCHIP "https://github.com/ipinfo/cli/tree/master/matchip/"
    click PRIPS "https://github.com/ipinfo/cli/tree/master/prips/"
    click Chocolatey "https://github.com/ipinfo/cli/tree/master/chocolatey-packages/ipinfo/"

    %% Styles
    classDef code fill:#f9f,stroke:#333,stroke-width:1px
    classDef build fill:#ff9,stroke:#333,stroke-width:1px
    classDef cylinder fill:#9ff,stroke:#333,stroke-width:1px
    classDef cloud fill:#cfc,stroke:#333,stroke-width:1px
    classDef db fill:#fcc,stroke:#333,stroke-width:1px
```
