# crystal-lang/shards architecture

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

- Interactive diagram: https://gitdiagram.com/crystal-lang/shards
- Repository: https://github.com/crystal-lang/shards

## Overview

##### Main Components
- Command Line Interface (CLI) Module:
- Located in the src directory (src/cli.cr and src/commands/*), this module parses user commands such as init, install, update, prune, and version.
- It routes input commands to the corresponding functionality.
- Dependency Configuration & Parsing:
- Handles reading, parsing, and writing the shard.yml and shard.lock files.
- This component is responsible for interpreting the user-defined dependency definitions.
- Dependency Resolution Engine:
- The heart of the project lies in the dependency resolution logic.
- Two parts here:
▪ The core resolution logic in the src (files like src/molinillo_solver.cr, src/resolvers/*) initiates dependency checks and applies resolution rules.
▪ The “molinillo” library (found in lib/molinillo) implements general dependency graph handling. It includes modules for dealing with the dependency graph, handling delegates (resolution state, specification providers), and error handling.
- Resolvers for External Sources:
- Found in src/resolvers (with specific files for git, hg, fossil, path, crystal, etc.), these components retrieve dependency versions and metadata from external sources.
- Build/Infrastructure and Testing Components:
- Makefiles, CI configurations (.circleci, .github/workflows) and the specs (unit and integration tests) ensure a robust development and deployment process.

##### Relationships and Interactions
- The CLI accepts commands and delegates tasks to the application core.
- The configuration component reads shard.yml/shard.lock to supply dependency definitions.
- The main dependency resolution engine, supported by the molinillo library, consumes these definitions and builds/updates a dependency graph.
- Based on dependency requirements, the specific resolvers (git, hg, etc.) are invoked to fetch metadata, retrieve available versions, and enforce semver rules.
- Interaction flows:
▪ The CLI triggers the resolution process.
▪ The resolution engine uses the molinillo dependency graph to compute a valid set of dependencies.
▪ Resolvers interact with external repositories or local sources as needed.
▪ Results get stored back into shard.lock.

##### Architectural Patterns and Design Principles
- Modular Design: Separating the CLI layer, the core dependency resolution engine, and external source resolvers.
- Separation of Concerns: Each directory (src, lib, spec) is clearly segmented to manage commands, logic, and tests independently.
- Reusability & Extensibility: The molinillo library is a reusable dependency solver, and the resolvers are cleanly abstracted to allow extension to new source types.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Frontend"]:::blue
    end

    %% Configuration Layer
    subgraph "Configuration"
        Config["Configuration Parser"]:::green
    end

    %% Dependency Resolution Engine
    subgraph "Dependency Resolution Engine"
        Core["Core Resolver"]:::blue
        Mol["Molinillo Library"]:::green
        Ext["External Resolvers"]:::orange
    end

    %% Testing & Build Infrastructure
    subgraph "Testing & Build Infrastructure"
        Makefile["Makefile"]:::purple
        CircleCI["CircleCI (.circleci/config.yml)"]:::purple
        GitHub["GitHub Workflows (.github/workflows/)"]:::purple
        Specs["Specs (spec/)"]:::purple
    end

    %% Connections
    CLI -->|"reads"| Config
    CLI -->|"executes"| Core
    Config -->|"suppliesConfig"| Core
    Core -->|"managesGraph"| Mol
    Core -->|"fetchesDependency"| Ext
    Core -->|"writesLockFile"| Config
    Core -->|"returnsResult"| CLI

    %% Styles
    classDef blue fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef green fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef orange fill:#ffcc99,stroke:#000,stroke-width:1px;
    classDef purple fill:#dda0dd,stroke:#000,stroke-width:1px;

    %% Click Events
    click CLI "https://github.com/crystal-lang/shards/blob/master/src/cli.cr"
    click Config "https://github.com/crystal-lang/shards/blob/master/src/config.cr"
    click Core "https://github.com/crystal-lang/shards/blob/master/src/molinillo_solver.cr"
    click Ext "https://github.com/crystal-lang/shards/tree/master/src/resolvers/"
    click Mol "https://github.com/crystal-lang/shards/tree/master/lib/molinillo"
    click Makefile "https://github.com/crystal-lang/shards/tree/master/Makefile"
    click CircleCI "https://github.com/crystal-lang/shards/blob/master/.circleci/config.yml"
    click GitHub "https://github.com/crystal-lang/shards/tree/master/.github/workflows/"
    click Specs "https://github.com/crystal-lang/shards/tree/master/spec/"
```
