# xcodecraft/rigger-ng architecture

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

- Interactive diagram: https://gitdiagram.com/xcodecraft/rigger-ng
- Repository: https://github.com/xcodecraft/rigger-ng

## Overview

##### Project Type and Purpose
- rigger‑ng is an open‑source CLI framework/tool for project scaffolding, configuration management, resource packaging, and deployment.
- It is implemented in Python, driven by YAML configuration and shell scripts, and built to be extensible via “modules” and “resources.”

##### File Structure
- Top‑level:
- src/ (all Python code)
- demo/ (example usage and templates)
- doc/ (architecture, usage, and HOWTOs)
- test/ (unit and integration tests)
- composer.json, shell entry scripts, and config files.
- src/ breaks down into:
- core/ – core engine:
– conf/ (defines and loads dev/run configurations)
– impl/ (command implementations: rg_args, rg_cmd_*, rg_run, rg_res, etc.)
– res/ (built‑in resource handlers: file templating, shell, nodes)
– run_env.py (environment orchestration)
- etc/ – OS environment templates per distro (Ubuntu, CentOS)
- extends/ – extension point:
– moduls/ (YAML descriptions of modules)
– res/ (plug‑in resource handlers grouped by domain: check, deploy, pylon, websys)
- lib/ – public interfaces and common utilities (YAML, JSON, shell, templating engine)
- bin/ – wrapper shell scripts that invoke Python core
- Supporting files:
- tpl/ – templates for new projects
- demo/_rg and demo/conf – example runtime configs
- simple_setup.sh, setting.py – bootstrap and configuration

##### Readme/Doc Insights
- Although the top‑level README is minimal, the doc/ folder contains extensive guides (e.g. doc/dev_guide.md, doc/prj_conf.md) that describe the configuration schema and plugin model.
- The design follows a plugin/resource architecture: the core engine discovers commands (rg_cmd_*), loads resources (built‑in or extended), processes user YAML, then dispatches shell calls or file operations.

a. CLI Frontend
– Entry scripts (simple_setup.sh, src/bin/proc_op.sh) invoke the Python CLI launcher.
b. Core Engine
– Argument parser (rg_args)
– Command dispatcher (rg_cmd_base + rg_cmd_dev/prj/pub)
– Config loader (run_conf, dev_conf)
– Run‑time orchestrator (rg_run, run_env.py)
c. Plugin/Extension Manager
– Module loader (extends/moduls)
– Resource loader (extends/res and src/core/res)
– Interface layer (lib/interface)
d. Resource Handlers
– Built‑in: file templating, shell execution, node operations (src/core/res)
– Extended: check, deploy, websys, pylon (src/extends/res/…)
e. Utility Libraries
– YAML/JSON parsing, templating engine (lib/utls)
– Common patterns and error definitions (lib/interface/rg_err, rg_conf, etc.)
f. OS Environment Templates
– Distro‑specific scripts (src/etc/*.py)
g. Demo & Test Harness
– demo/ shows a sample end‑to‑end run
– test/ drives core and extension tests

##### Relationships and Interactions
- The user runs the CLI script → invokes Python core
- Core parses CLI args → loads dev/run YAML config
- Core discovers and dispatches to the requested rg_cmd_* plugin
- Command implementation requests resources by name → extension manager locates appropriate handler in src/core/res or src/extends/res
- Resource handler executes actions: file generation via templating engine, shell commands, service definitions, etc.
- OS‑specific modules supply templates or commands per environment
- Utilities (lib/utls) serve as common building blocks for file I/O, JSON/YAML, templating

##### Architectural Patterns & Principles
- Plugin Architecture: Commands and resources are discoverable modules
- Separation of Concerns: Core engine vs. extensions vs. utilities
- Convention over Configuration: YAML schema and directory layouts
- Dependency Injection: configs drive behavior, not hard‑coded paths
- Test‑Driven Design: extensive unit tests in test/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Frontend
    subgraph "CLI Frontend"
        simple_setup["simple_setup.sh"]:::external
        proc_op["proc_op.sh"]:::external
    end

    %% Core Engine
    subgraph "Core Engine"
        subgraph "Argument Parser"
            rg_args["rg_args.py"]:::core
        end
        subgraph "Command Dispatcher"
            rg_cmd_base["rg_cmd_base.py"]:::core
            rg_cmd_dev["rg_cmd_dev.py"]:::core
            rg_cmd_prj["rg_cmd_prj.py"]:::core
            rg_cmd_pub["rg_cmd_pub.py"]:::core
        end
        subgraph "Configuration Loader"
            dev_conf["dev_conf.py"]:::core
            run_conf["run_conf.py"]:::core
            define_conf["define.py"]:::core
        end
        subgraph "Run-time Orchestrator"
            rg_run["rg_run.py"]:::core
            run_env["run_env.py"]:::core
        end
    end

    %% Plugin/Extension Manager
    subgraph "Plugin/Extension Manager"
        module_loader["moduls/"]:::ext
        resource_loader["res/ (built-in & ext)"]:::ext
        subgraph "Interface Layer"
            iface_conf["rg_conf.py"]:::ext
            iface_def["rg_def.py"]:::ext
            iface_err["rg_err.py"]:::ext
        end
    end

    %% Resource Handlers
    subgraph "Resource Handlers"
        subgraph "Built-in Handlers"
            files["files.py"]:::core
            shell_res["shell.py"]:::core
            node_res["node.py"]:::core
            inner_res["inner.py"]:::core
            base_res["base.py"]:::core
        end
        subgraph "Extended Handlers"
            check_impl["check_impl.py"]:::ext
            deploy_pkg["package.py"]:::ext
            pylon_res["pylon_res.py"]:::ext
            websys_res["websys/"]:::ext
        end
    end

    %% Utilities
    subgraph "Utility Libraries"
        yaml_lib["rg_yaml.py"]:::util
        json_lib["rg_json.py"]:::util
        tpl_engine["tpl_engine.py"]:::util
        sh_lib["rg_sh.py"]:::util
        io_lib["rg_io.py"]:::util
        err_lib["rg_err.py"]:::util
        conf_lib["rg_conf.py"]:::util
    end

    %% OS Environment Templates
    subgraph "OS Environment Templates"
        ubuntu_tpl["ubuntu.py"]:::core
        centos_mara["centos_mara.py"]:::core
        centos_xcc["centos_xcc.py"]:::core
        rg_env["rg_env.py"]:::core
        rgenv_tpl["rgenv_tpl.py"]:::core
    end

    %% Demo & Test
    subgraph "Demo & Test Harness"
        demo_dir["demo/"]:::external
        test_suite["test/"]:::external
    end

    %% Connections
    simple_setup -->|"invoke"| rg_args
    proc_op -->|"invoke"| rg_args
    rg_args -->|"load YAML"| dev_conf
    rg_args -->|"load YAML"| run_conf
    rg_args -->|"discover command"| rg_cmd_base
    rg_cmd_base -->|"dispatch to"| rg_run
    rg_run -->|"orchestrate"| run_env
    rg_cmd_base -->|"use Plugin Manager"| module_loader
    rg_cmd_base -->|"use Plugin Manager"| resource_loader

    module_loader -->|"get resource"| files
    module_loader -->|"get resource"| check_impl
    resource_loader -->|"get resource"| shell_res
    resource_loader -->|"get resource"| deploy_pkg

    files -->|"execute"| ubuntu_tpl
    shell_res -->|"execute"| centos_mara
    node_res -->|"execute"| centos_xcc
    inner_res -->|"execute"| rg_env
    base_res -->|"execute"| rgenv_tpl

    files -->|"use templating"| tpl_engine
    shell_res -->|"use utils"| sh_lib
    node_res -->|"use utils"| io_lib
    inner_res -->|"use utils"| yaml_lib
    base_res -->|"use utils"| json_lib

    demo_dir -->|"examples"| rg_cmd_dev
    test_suite -->|"tests core & ext"| rg_cmd_dev

    %% Click Events
    click simple_setup "https://github.com/xcodecraft/rigger-ng/blob/master/simple_setup.sh"
    click proc_op "https://github.com/xcodecraft/rigger-ng/blob/master/src/bin/proc_op.sh"
    click rg_args "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_args.py"
    click rg_cmd_base "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_cmd/rg_cmd_base.py"
    click rg_cmd_dev "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_cmd/rg_cmd_dev.py"
    click rg_cmd_prj "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_cmd/rg_cmd_prj.py"
    click rg_cmd_pub "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_cmd/rg_cmd_pub.py"
    click dev_conf "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/conf/dev_conf.py"
    click run_conf "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/conf/run_conf.py"
    click define_conf "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/conf/define.py"
    click rg_run "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/impl/rg_run.py"
    click run_env "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/run_env.py"
    click module_loader "https://github.com/xcodecraft/rigger-ng/tree/master/src/extends/moduls/"
    click resource_loader "https://github.com/xcodecraft/rigger-ng/tree/master/src/core/res/"
    click iface_conf "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/interface/rg_conf.py"
    click iface_def "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/interface/rg_def.py"
    click iface_err "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/interface/rg_err.py"
    click files "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/res/files.py"
    click shell_res "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/res/shell.py"
    click node_res "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/res/node.py"
    click inner_res "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/res/inner.py"
    click base_res "https://github.com/xcodecraft/rigger-ng/blob/master/src/core/res/base.py"
    click check_impl "https://github.com/xcodecraft/rigger-ng/blob/master/src/extends/res/check/check_impl.py"
    click deploy_pkg "https://github.com/xcodecraft/rigger-ng/blob/master/src/extends/res/deploy/package.py"
    click pylon_res "https://github.com/xcodecraft/rigger-ng/blob/master/src/extends/res/pylon/pylon_res.py"
    click websys_res "https://github.com/xcodecraft/rigger-ng/tree/master/src/extends/res/websys/"
    click yaml_lib "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/utls/rg_yaml.py"
    click json_lib "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/utls/rg_json.py"
    click tpl_engine "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/utls/tpl/tpl_engine.py"
    click sh_lib "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/utls/rg_sh.py"
    click io_lib "https://github.com/xcodecraft/rigger-ng/blob/master/src/lib/utls/rg_io.py"
    click ubuntu_tpl "https://github.com/xcodecraft/rigger-ng/blob/master/src/etc/ubuntu.py"
    click centos_mara "https://github.com/xcodecraft/rigger-ng/blob/master/src/etc/centos_mara.py"
    click centos_xcc "https://github.com/xcodecraft/rigger-ng/blob/master/src/etc/centos_xcc.py"
    click rg_env "https://github.com/xcodecraft/rigger-ng/blob/master/src/etc/rg_env.py"
    click rgenv_tpl "https://github.com/xcodecraft/rigger-ng/blob/master/src/etc/rgenv_tpl.py"
    click demo_dir "https://github.com/xcodecraft/rigger-ng/tree/master/demo/"
    click test_suite "https://github.com/xcodecraft/rigger-ng/tree/master/test/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef ext fill:#98FB98,stroke:#000
    classDef util fill:#FFDAB9,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
