# alire-project/alire architecture

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

- Interactive diagram: https://gitdiagram.com/alire-project/alire
- Repository: https://github.com/alire-project/alire

## Overview

##### Main project domains and modules
- Command‐line Interface (CLI): The “alr” components (located under src/alr) form the front end that users interact with. They parse user commands (like “alr build”, “alr printenv”, or “alr get”) and then drive the workflow.
- Core Dependency Management & Library Repository: The “alire” modules (under src/alire) include the engine for fetching, resolving, caching, and organizing Ada libraries. They employ TOML configuration files (alire.toml) both locally and from community indexes.
- Build Environment Integration: With provided GNAT (Ada 2012) project files (e.g., alr_env.gpr) and support scripts in the “dev” and “scripts” directories, the tool automates setting up the GPR_PROJECT_PATH and invoking gprbuild.
- Platform-Specific Adaptations: Directories like src/alire/os_* and src/alr/os_* indicate that the project contains OS-specific modules (for Linux, macOS, Windows, FreeBSD, OpenBSD) to manage platform variations and possibly trigger “sudo” installations for platform package managers.
- Auxiliary Components: Additional folders such as “deps”, “testsuite”, “doc”, “support”, and “templates” cover dependencies management, continuous integration tests, documentation, and installer or embedder support.

##### Out key interactions within the system
- The CLI module accepts user commands and delegates tasks to the Dependency Resolution Engine.
- The Dependency Resolver reads from configuration files (e.g., alire.toml) and interacts with the Community Index (which is maintained as local TOML files in the index) to determine which libraries (crates) need to be fetched or built.
- The Build Orchestrator sets up the environment (by configuring GPR_PROJECT_PATH) and calls the GNAT build tools (gprbuild) to compile projects and dependencies.
- The Platform Abstraction layer adjusts behavior according to ALIRE_OS, reading from OS-specific modules.
- The system may also call external package managers (with user authorization via sudo when required) to install certain platform packages.

##### Architectural patterns and design principles
- Modularity: Separate modules for CLI, dependency resolution, library management, and build orchestration.
- Layering: The architecture separates the user interface (CLI) from core business logic and from the build environment interface.
- Extensibility: The use of TOML metadata and separate modules for different OS platforms makes it easy to extend ALIRE to support new library formats or build workflows.
- Environment Isolation: Similar to Python’s virtualenv, ALIRE encapsulates dependencies via locally configured build environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Interface (alr)"]:::presentation
    end

    %% Core Services Layer
    subgraph "Core Services Layer"
        DM["Dependency Management Engine (alire)"]:::core
        CI["Community Index (Local TOML)"]:::external
    end

    %% Build & Environment Layer
    subgraph "Build & Environment Layer"
        BO["Build Orchestrator"]:::build
        GNAT["GNAT Project File"]:::build
        DS["Dev Scripts"]:::build
        US["Utility Scripts"]:::build
    end

    %% Platform-Specific Layer
    subgraph "Platform-Specific Layer"
        PA["Platform Abstraction"]:::platform
        PC["Platform Modules (Core)"]:::platform
        PL["Platform Modules (CLI)"]:::platform
        EPM["External Package Manager"]:::external
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        AUX1["deps"]:::auxiliary
        AUX2["testsuite"]:::auxiliary
        AUX3["doc"]:::auxiliary
        AUX4["support"]:::auxiliary
        AUX5["templates"]:::auxiliary
    end

    %% Connections between Layers
    CLI -->|"UserCommand:Build/Fetch/PrintEnv"| DM
    DM -->|"ReadMetadata:alire.toml"| CI
    DM -->|"TriggerBuild"| BO
    BO -->|"Invoke:gprbuild"| GNAT
    BO -->|"Run"| DS
    BO -->|"Run"| US
    BO -->|"CheckOS"| PA
    PA -->|"LoadCore"| PC
    PA -->|"LoadCLI"| PL
    PA -->|"CallSudo"| EPM
    DM -->|"Uses"| AUX1

    %% Styles
    classDef presentation fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef build fill:#cfc,stroke:#333,stroke-width:2px;
    classDef platform fill:#fc9,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#ffc,stroke:#f66,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/alire-project/alire/tree/master/src/alr"
    click DM "https://github.com/alire-project/alire/tree/master/src/alire"
    click GNAT "https://github.com/alire-project/alire/blob/master/alr_env.gpr"
    click DS "https://github.com/alire-project/alire/tree/master/dev"
    click US "https://github.com/alire-project/alire/tree/master/scripts"
    click PC "https://github.com/alire-project/alire/tree/master/src/alire/os_linux"
    click PL "https://github.com/alire-project/alire/tree/master/src/alr/os_linux"
    click AUX1 "https://github.com/alire-project/alire/tree/master/deps"
    click AUX2 "https://github.com/alire-project/alire/tree/master/testsuite"
    click AUX3 "https://github.com/alire-project/alire/tree/master/doc"
    click AUX4 "https://github.com/alire-project/alire/tree/master/support"
    click AUX5 "https://github.com/alire-project/alire/tree/master/templates"
```
