# maxioum/peeler architecture

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

- Interactive diagram: https://gitdiagram.com/maxioum/peeler
- Repository: https://github.com/maxioum/peeler

## Overview

##### Project Type and Purpose
- The tool is not a full-stack web application but rather a CLI-based packaging tool focused on Blender add-ons.
- Its primary purpose is twofold:
- Generating a Blender-compatible manifest file (using data from pyproject.toml).
- Managing dependencies by downloading wheels for the project’s dependencies.
- It also integrates with the external tool “uv” for some functionality related to wheels.

##### File Structure
- Key directories:
- The root directory contains general configuration files (e.g., .gitignore, CHANGELOG.md, LICENSE, pyproject.toml) and CI/CD configurations under the .github directory.
- “peeler-json-schema” handles JSON schemas used for validating some project aspects (likely for the manifest).
- “peeler” is the core module where functionalities are implemented:
▫ The CLI entry point is defined in peeler/cli.py.
▫ Subdirectories under “peeler/command” encapsulate different commands (manifest generation, version handling, wheels management).
▫ “peeler/manifest” holds the functions for validating and writing out the manifest.
▫ “peeler/pyproject” handles parsing, validation, and utilities for processing pyproject.toml.
▫ “peeler/wheels” manages downloading and locking of wheels.
▫ Utility modules (e.g., toml_utils.py, uv_utils.py, utils.py) provide supporting features.
- “tests” mirrors the project structure for comprehensive unit testing.
- The directory structure reveals a modular architecture that separates concerns by command (manifest, wheels, etc.) and utility areas (parsing, validation, downloading).

##### README for Additional Insights
- The README clearly shows two major functionalities: “Manifest” and “Wheels.”
- It details how the tool converts information from pyproject.toml to blender_manifest.toml.
- It describes the dependency resolution process, including handling nested dependencies.
- Integration with the external tool “uv” is critical, particularly for handling wheels.
- The flow from specifying dependencies in pyproject.toml, running the peeler command, and updating the manifest is the backbone of the tool.

a. Components to Include:
- CLI Interface: Represented by peeler/cli.py which acts as the entry point.
- Command Modules:
▫ Manifest Command Module (peeler/command/manifest.py) – handles parsing of pyproject.toml and writing the blender_manifest.toml.
▫ Wheels Command Module (peeler/command/wheels.py) – retrieves dependency wheels, organizes them, and updates the manifest.
▫ Version Command Module (peeler/command/version.py), if applicable.
- PyProject Parser and Validator (peeler/pyproject/parse.py, validator.py, utils.py) – responsible for reading and validating the pyproject.toml.
- Manifest Generator (peeler/manifest/validate.py, write.py) – applies schema rules (using schemas in peeler-json-schema/data) to generate a valid blender_manifest.
- Wheels Downloader and Locking Mechanism (peeler/wheels/download.py, lock.py) – fetches and manages dependency wheels including the dependency tree.
- Utilities Modules (uv_utils, toml_utils, etc.) – provide support for version control, uv integration, and file handling.
- JSON Schemas Component: Under “peeler-json-schema,” these provide the schema definitions for validating both the manifest and potentially the pyproject format.
- External Integration: “uv” for wheels and Blender commands for add-on builds.
b. Relationships & Workflow:
- The CLI component routes user commands to the relevant command modules.
- The Manifest Command reads the pyproject.toml using the PyProject Parser, validates and extracts required metadata, then uses the Manifest Generator to produce (or update) the blender_manifest.toml.
- When the Wheels Command is invoked, it leverages the Wheels Downloader to resolve and download all required wheels (including dependencies) while updating the manifest with their file paths.
- Utility modules interact across these components, particularly for configuration, file path resolution, and version checking (e.g., uv_utils interact with uv).
- The JSON Schema definitions are used by the parser/validator components to ensure the generated manifest complies with the expected structure.
c. Architectural Patterns & Design Principles:
- Modular design: Separation of concerns among CLI, commands, parsing/validation, wheels handling, and manifest generation.
- Single Responsibility Principle: Each module focuses on a specific aspect of the process.
- Extensibility: The clear structure and separation enable potential extension (e.g., adding new commands or support for additional packaging strategies later on).
d. Technologies, Frameworks, and Libraries:
- Python: The language used to build the tool.
- TOML parsing libraries (implied by use of pyproject.toml and mypy.ini, ruff.toml, etc.).
- Workflow configuration for CI/CD (GitHub Actions).
- External tool “uv” integration indicated in the readme.
- Relevant testing frameworks as seen from the “tests” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    CLI["\"CLI Interface\""]:::cli

    %% Commands
    subgraph "Commands"
        MAN["\"Manifest Command\""]:::command
        WHEEL["\"Wheels Command\""]:::command
        VERSION["\"Version Command\""]:::command
    end

    %% PyProject Processor
    subgraph "PyProject Processor"
        PPARSER["\"PyProject Parse\""]:::parser
        PVALID["\"PyProject Validator\""]:::parser
        PUTILS["\"PyProject Utils\""]:::parser
    end

    %% Manifest Generator
    subgraph "Manifest Generator"
        MVALID["\"Manifest Validate\""]:::generator
        MWRITE["\"Manifest Write\""]:::generator
    end

    %% Wheels Handler
    subgraph "Wheels Handler"
        WDLD["\"Wheels Download\""]:::wheels
        WLOCK["\"Wheels Lock\""]:::wheels
    end

    %% Utilities
    subgraph "Utilities"
        TOMLUTIL["\"TOML Utils\""]:::utility
        GENUTIL["\"General Utils\""]:::utility
        UVUTIL["\"UV Utils\""]:::utility
    end

    %% JSON Schemas
    subgraph "JSON Schemas"
        SCHEMA1["\"Blender Manifest Schema\""]:::schema
        SCHEMA2["\"Peeler Pyproject Schema\""]:::schema
        SCHEMA3["\"Peeler Schema\""]:::schema
    end

    %% External Integration
    subgraph "External Integration"
        UVEXT["\"External UV Integration\""]:::external
        BLENDER["\"Blender Commands\""]:::external
    end

    %% CI/CD
    subgraph "CI/CD"
        GHA["\"GitHub Actions\""]:::cicd
    end

    %% Connections from CLI to Commands
    CLI -->|"routes_to_manifest"| MAN
    CLI -->|"routes_to_wheels"| WHEEL
    CLI -->|"version_check"| VERSION

    %% Manifest Command flow
    MAN -->|"reads_pyproject.toml"| PPARSER
    PPARSER -->|"validates_config"| PVALID
    PVALID -->|"supports_with"| PUTILS
    MAN -->|"triggers_manifest_generation"| MVALID
    MVALID -->|"writes_manifest"| MWRITE
    MVALID -->|"validates_against_schema"| SCHEMA1

    %% PyProject Processor schema usage
    PPARSER -->|"uses_schema"| SCHEMA2
    PVALID -->|"uses_schema"| SCHEMA3

    %% Wheels Command flow
    WHEEL -->|"fetches_wheels"| WDLD
    WDLD -->|"locks_dependencies"| WLOCK
    WDLD -->|"integrates_uv"| UVEXT
    UVEXT -->|"assisted_by"| UVUTIL
    WDLD -->|"updates_manifest"| GENUTIL

    %% CI/CD triggers
    GHA -->|"triggers_packaging"| CLI

    %% Styling
    classDef cli fill:#fcebd5,stroke:#d35400,stroke-width:2px;
    classDef command fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef parser fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef generator fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef wheels fill:#f9ebea,stroke:#e74c3c,stroke-width:2px;
    classDef utility fill:#edf2f4,stroke:#2b2d42,stroke-width:2px;
    classDef schema fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#d5d8dc,stroke:#7f8c8d,stroke-width:2px;
    classDef cicd fill:#eafaf1,stroke:#28b463,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/maxioum/peeler/blob/main/peeler/cli.py"
    click MAN "https://github.com/maxioum/peeler/blob/main/peeler/command/manifest.py"
    click WHEEL "https://github.com/maxioum/peeler/blob/main/peeler/command/wheels.py"
    click VERSION "https://github.com/maxioum/peeler/blob/main/peeler/command/version.py"
    click PPARSER "https://github.com/maxioum/peeler/blob/main/peeler/pyproject/parse.py"
    click PVALID "https://github.com/maxioum/peeler/blob/main/peeler/pyproject/validator.py"
    click PUTILS "https://github.com/maxioum/peeler/blob/main/peeler/pyproject/utils.py"
    click MVALID "https://github.com/maxioum/peeler/blob/main/peeler/manifest/validate.py"
    click MWRITE "https://github.com/maxioum/peeler/blob/main/peeler/manifest/write.py"
    click WDLD "https://github.com/maxioum/peeler/blob/main/peeler/wheels/download.py"
    click WLOCK "https://github.com/maxioum/peeler/blob/main/peeler/wheels/lock.py"
    click TOMLUTIL "https://github.com/maxioum/peeler/blob/main/peeler/toml_utils.py"
    click GENUTIL "https://github.com/maxioum/peeler/blob/main/peeler/utils.py"
    click UVUTIL "https://github.com/maxioum/peeler/blob/main/peeler/uv_utils.py"
    click SCHEMA1 "https://github.com/maxioum/peeler/blob/main/peeler-json-schema/data/blender_manifest_schema.json"
    click SCHEMA2 "https://github.com/maxioum/peeler/blob/main/peeler-json-schema/data/peeler_pyproject_schema.json"
    click SCHEMA3 "https://github.com/maxioum/peeler/blob/main/peeler-json-schema/data/peeler_schema.json"
```
