# swiftlang/swiftly architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlang/swiftly
- Repository: https://github.com/swiftlang/swiftly

## Overview

##### Project type and purpose
- swiftly is a cross-platform (Linux/macOS) command-line tool written in Swift for installing, managing, and switching between multiple Swift toolchains.
- It communicates with external Swift.org APIs, downloads archived toolchains, extracts them, manages local installation directories, and updates shell environment settings.

##### File structure
- Top-level “Sources/Swiftly” contains the CLI entrypoint and subcommands (Install, Use, Update, Uninstall, List, Run, SelfUpdate, etc.).
- “Sources/SwiftlyCore” holds shared logic: HTTPClient, file‐management, error handling, version modeling, platform abstractions.
- “Sources/SwiftlyDownloadAPI” and “Sources/SwiftlyWebsiteAPI” each contain generated OpenAPI clients for external servers.
- “Sources/CLibArchive” provides a C wrapper for .tar/.zip extraction.
- “Sources/LinuxPlatform” and “Sources/MacOSPlatform” adapt platform‐specific behaviors.
- Plugins and Tools directories implement ancillary tasks (documentation generation, release builds).
- Tests exercise each CLI command and core module.
- Configuration and build by Swift Package Manager (Package.swift, Package.resolved). CI pipelines in .github/workflows.

a. CLI Frontend
- Single executable (“swiftly”) exposing subcommands.
- Parses user input and invokes corresponding command handler in SwiftlyCore.
b. Core Library
- ModeledCommandLine, Commands, Messages, Error types, version/file‐path utilities.
- HTTPClient for REST calls.
- Platform adapters select Linux vs. macOS logic.
c. Download & Website API Clients
- OpenAPI-generated modules for querying available toolchains and fetching release metadata.
d. Archive Extraction Layer
- CLibArchive bridging to libarchive for unpacking toolchain archives.
e. File System & Env Manager
- Creates installation directory structure (e.g. ~/.swiftpm or ~/.local/share/swiftly), symlinks binaries, writes env.sh/env.fish.
f. External Services
- Swift.org download servers and website APIs.
g. Shell Integration
- Sourced scripts modifying $PATH to point at selected toolchain.
h. Plugins & Tools

##### Relationships & data flows
- User types “swiftly install <version>” → CLI Frontend → CoreLibrary.InstallCommand
→ HTTPClient calls DownloadAPI to get URL and checksum
→ HTTPClient downloads archive
→ ArchiveExtraction extracts into local install root
→ FileSystem writes binaries and updates symlinks
→ CoreLibrary reports success via Messages.
- “swiftly use <version>” → CoreLibrary switches active symlink + updates shell env script.
- All commands go through the shared CoreLibrary and may call Platform adapters.
- Self-update works similarly but downloads a new CLI executable and replaces the current one.

##### Architectural patterns & design principles
- Modular layering: CLI runner → core logic → infrastructure (HTTP, FS, archive) → external APIs.
- Dependency inversion: high-level commands depend on abstract HTTPClient and FileManager interfaces.
- Separation of concerns: platform-specific code in dedicated modules; API clients auto-generated.
- Test coverage layer exercises each command through its public interface.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User interaction
    User["User"]:::external -->|"swiftly &lt;command&gt; "| CLI["CLI Frontend\n(Sources/Swiftly)"]:::frontend

    subgraph "CLI Frontend" 
        direction TB
        CLIExec["swiftly\n(Sources/Swiftly/Swiftly.swift)"]:::frontend
        Install["InstallCommand\n(Sources/Swiftly/Install.swift)"]:::frontend
        Use["UseCommand\n(Sources/Swiftly/Use.swift)"]:::frontend
        Update["UpdateCommand\n(Sources/Swiftly/Update.swift)"]:::frontend
        Uninstall["UninstallCommand\n(Sources/Swiftly/Uninstall.swift)"]:::frontend
        List["ListCommand\n(Sources/Swiftly/List.swift)"]:::frontend
        ListAvail["ListAvailableCommand\n(Sources/Swiftly/ListAvailable.swift)"]:::frontend
        Run["RunCommand\n(Sources/Swiftly/Run.swift)"]:::frontend
        SelfUpdate["SelfUpdateCommand\n(Sources/Swiftly/SelfUpdate.swift)"]:::frontend
        Link["LinkCommand\n(Sources/Swiftly/Link.swift)"]:::frontend
        Unlink["UnlinkCommand\n(Sources/Swiftly/Unlink.swift)"]:::frontend
        InitCmd["InitCommand\n(Sources/Swiftly/Init.swift)"]:::frontend
        Proxy["ProxyCommand\n(Sources/Swiftly/Proxy.swift)"]:::frontend
        Config["Config definitions\n(Sources/Swiftly/Config.swift)"]:::frontend
    end

    CLIExec -->|invokes| Install
    CLIExec -->|invokes| Use
    CLIExec -->|invokes| Update
    CLIExec -->|invokes| Uninstall
    CLIExec -->|invokes| List
    CLIExec -->|invokes| ListAvail
    CLIExec -->|invokes| Run
    CLIExec -->|invokes| SelfUpdate
    CLIExec -->|invokes| Link
    CLIExec -->|invokes| Unlink
    CLIExec -->|invokes| InitCmd
    CLIExec -->|invokes| Proxy

    subgraph "Core Library" 
        direction TB
        CoreFacade["SwiftlyCore\n(Sources/SwiftlyCore)"]:::core
        CmdParse["ModeledCommandLine & Commands\n(ModeledCommandLine.swift, Commands.swift)"]:::core
        HTTPAbstr["HTTPClient\n(HTTPClient.swift)"]:::infra
        FileUtil["FileManager+FilePath\n(FileManager+FilePath.swift)"]:::infra
        VersionModel["SwiftlyVersion & ToolchainVersion\n(SwiftlyVersion.swift, ToolchainVersion.swift)"]:::core
        ErrorType["Error handling\n(Error.swift)"]:::core
        Messages["Messages & Localization\n(Messages.swift)"]:::core
        PlatformIface["Platform interface\n(Platform.swift)"]:::core
        StringExt["String utilities\n(StringExtensions.swift)"]:::core
    end

    Install -->|calls| CoreFacade
    Use -->|calls| CoreFacade
    Update -->|calls| CoreFacade
    SelfUpdate -->|calls| CoreFacade

    CoreFacade --> CmdParse
    CoreFacade --> HTTPAbstr
    CoreFacade --> FileUtil
    CoreFacade --> VersionModel
    CoreFacade --> ErrorType
    CoreFacade --> Messages
    CoreFacade --> PlatformIface
    CoreFacade --> StringExt

    subgraph "API Clients"
        direction TB
        DownloadAPI["SwiftlyDownloadAPI\n(Sources/SwiftlyDownloadAPI)"]:::infra
        WebsiteAPI["SwiftlyWebsiteAPI\n(Sources/SwiftlyWebsiteAPI)"]:::infra
    end

    HTTPAbstr -->|GET metadata| DownloadAPI
    HTTPAbstr -->|GET metadata| WebsiteAPI

    subgraph "Archive Extraction\n(CLibArchive)"
        direction TB
        CLib["CLibArchive\n(Sources/CLibArchive)"]:::infra
    end

    DownloadAPI -->|provides URL & checksum| HTTPAbstr
    HTTPAbstr -->|download archive| CLib
    CLib -->|extract| FileUtil

    subgraph "Platform Adapters"
        direction TB
        LinuxPlat["LinuxPlatform\n(Sources/LinuxPlatform)"]:::core
        MacPlat["MacOSPlatform\n(Sources/MacOSPlatform)"]:::core
    end

    PlatformIface --> LinuxPlat
    PlatformIface --> MacPlat

    subgraph "File System & Env Manager"
        direction TB
        FileUtil --> EnvScript["Shell Env Scripts\n(generated)"]:::infra
        EnvScript -->|"update PATH"| Shell["Shell Integration"]:::external
    end

    CLib --> FileUtil

    subgraph "External Services"
        direction TB
        SwiftOrgDL["Swift.org Download Server"]:::external
        SwiftOrgWeb["Swift.org Website API"]:::external
    end

    DownloadAPI -->|fetch metadata| SwiftOrgWeb
    DownloadAPI -->|download archive| SwiftOrgDL

    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B4F72
    classDef core fill:#E8DAEF,stroke:#512E5F,color:#512E5F
    classDef infra fill:#D5F5E3,stroke:#1D8348,color:#1D8348
    classDef external fill:#FADBD8,stroke:#922B21,color:#922B21

    %% Click events
    click CLIExec "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Swiftly.swift"
    click Install "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Install.swift"
    click Use "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Use.swift"
    click Update "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Update.swift"
    click Uninstall "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Uninstall.swift"
    click List "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/List.swift"
    click ListAvail "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/ListAvailable.swift"
    click Run "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Run.swift"
    click SelfUpdate "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/SelfUpdate.swift"
    click Link "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Link.swift"
    click Unlink "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Unlink.swift"
    click InitCmd "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Init.swift"
    click Proxy "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Proxy.swift"
    click Config "https://github.com/swiftlang/swiftly/blob/main/Sources/Swiftly/Config.swift"
    click CoreFacade "https://github.com/swiftlang/swiftly/tree/main/Sources/SwiftlyCore"
    click HTTPAbstr "https://github.com/swiftlang/swiftly/blob/main/Sources/SwiftlyCore/HTTPClient.swift"
    click FileUtil "https://github.com/swiftlang/swiftly/blob/main/Sources/SwiftlyCore/FileManager+FilePath.swift"
    click DownloadAPI "https://github.com/swiftlang/swiftly/tree/main/Sources/SwiftlyDownloadAPI"
    click WebsiteAPI "https://github.com/swiftlang/swiftly/tree/main/Sources/SwiftlyWebsiteAPI"
    click CLib "https://github.com/swiftlang/swiftly/tree/main/Sources/CLibArchive"
    click LinuxPlat "https://github.com/swiftlang/swiftly/tree/main/Sources/LinuxPlatform"
    click MacPlat "https://github.com/swiftlang/swiftly/tree/main/Sources/MacOSPlatform"
```
