# mcbeet/beet architecture

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

- Interactive diagram: https://gitdiagram.com/mcbeet/beet
- Repository: https://github.com/mcbeet/beet

## Overview

##### Main Components
- CLI/Interface: This is the entry point for users. It accepts commands (e.g., build, cache, link, watch) and options. It is implemented primarily via the “beet/toolchain/cli.py” and orchestrates actions.
- Toolchain/Pipeline Engine: Located in “beet/toolchain/”, this subsystem composes the build pipeline. It is responsible for interpreting the configuration, invoking plugins, spawning workers, coordinating the build process, and managing the overall project context.
- Plugin System: The design must show how custom plugins (such as those in “beet/contrib/”) integrate into the toolchain. These plugins can modify the build behavior, integrate pre-processors (like auto_yaml, template_sandbox, etc.), and add extra commands.
- Core Services: Under “beet/core/” lie central utilities for file management, caching, error handling, and file-watching. Represent these as supporting services that are used across the toolchain and library.
- Library Module: The “beet/library/” submodule provides higher-level APIs to read, write, edit, merge, and lazily load Minecraft data packs and resource packs. This module can be depicted as the abstraction layer that encapsulates the Minecraft pack formats.
- Examples/Tests: Although not part of the production runtime, the examples and tests validate integration between these components and demonstrate usage.

##### Relationships and Data Flow
- The CLI invokes the toolchain’s commands which, in turn, instantiates and passes a “Context” (see “beet/toolchain/context.py”) that acts as the central object carrying project configuration and state across components.
- The toolchain coordinates the pipeline across several stages: reading configuration, loading and processing files (using modules from “beet/core/”), running plugins from the “contrib” directory, and ultimately constructing output from the “beet/library/” primitives.
- External interactions include linking the generated resource pack and data pack to an external Minecraft environment (triggered by the “link” command) and a watch mode that uses file system watchers.
- Caching, logging, and error messages from the core are used throughout the system to ensure fast and robust building.

##### Architectural Patterns and Design Principles
- Pipeline/Worker Pattern: Show how several modules (such as “pipeline.py” and “worker.py”) collaborate to enable concurrent operations or staged processing.
- Separation of Concerns: The clear partition between the CLI interface, pipeline orchestration, core utilities, and library ensures that each component is focused on a separate responsibility, making the system modular and testable.

##### Relevant Technologies and Frameworks
- Python is used as the primary language.
- Static typing and integration with tools like pyright enable rich IntelliSense.
- Testing uses pytest (with custom plugins such as pytest-minecraft).
- The project embraces modern CLI design patterns and code formatting standards (via black and isort).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer
    subgraph "User Interface Layer"
        CLI["Beet CLI"]:::cli
    end

    %% Middle Layer
    subgraph "Toolchain & Pipeline Layer"
        TOOLCHAIN["Toolchain Engine"]:::toolchain
        CTX["Context"]:::toolchainNote
        PLUGIN["Plugin System"]:::plugin
    end

    %% Bottom Layer
    subgraph "Core & Library Layer"
        CORE["Core Services"]:::core
        LIB["Library Module"]:::library
        EXT["External Integration (Minecraft)"]:::external
    end

    %% Validation Layer
    subgraph "Validation"
        EX["Examples"]:::example
        TEST["Tests"]:::example
    end

    %% Connections
    CLI -->|"invokes"| TOOLCHAIN
    TOOLCHAIN -->|"passes"| CTX
    TOOLCHAIN -->|"coordinates with"| PLUGIN
    TOOLCHAIN -->|"utilizes"| CORE
    TOOLCHAIN -->|"builds"| LIB
    CORE -->|"supports"| EXT
    LIB -->|"outputs to"| EXT
    EX -->|"demonstrates"| TOOLCHAIN
    TEST -->|"verifies"| CORE

    %% Click Events
    click CLI "https://github.com/mcbeet/beet/blob/main/beet/toolchain/cli.py"
    click TOOLCHAIN "https://github.com/mcbeet/beet/tree/main/beet/toolchain/"
    click PLUGIN "https://github.com/mcbeet/beet/tree/main/beet/contrib/"
    click CORE "https://github.com/mcbeet/beet/tree/main/beet/core/"
    click LIB "https://github.com/mcbeet/beet/tree/main/beet/library/"
    click EX "https://github.com/mcbeet/beet/tree/main/examples/"
    click TEST "https://github.com/mcbeet/beet/tree/main/tests/"

    %% Styles
    classDef cli fill:#f9a,stroke:#333,stroke-width:2px;
    classDef toolchain fill:#bbf,stroke:#333,stroke-width:2px;
    classDef plugin fill:#afa,stroke:#333,stroke-width:2px;
    classDef core fill:#ffb,stroke:#333,stroke-width:2px;
    classDef library fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px;
    classDef example fill:#cfc,stroke:#333,stroke-width:2px;
    classDef toolchainNote fill:#eee,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px;
```
