# acceldata-io/wizard architecture

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

- Interactive diagram: https://gitdiagram.com/acceldata-io/wizard
- Repository: https://github.com/acceldata-io/wizard

## Overview

##### Main Components
- JSON DSL Input: Represents the client’s configuration JSON that defines tasks, actions, priority, and conditional logic.
- Task Management Layer (“task” package): This is the entry point that reads the JSON input, loads embedded files (if any), and initializes a Task object using either task.New or task.NewWithLog.
- Parser & Config Generation: Under the “internal” directory, modules like “internal/parser” (with parser.go) and “internal/configen” process and validate the JSON configuration.
- Action Execution Modules: Located in “pkg/actions” and supported by the factory pattern in the “factory” directory. These modules implement various actions such as copy, template, file, user, cmd, and systemd.
- Registration / Registry: The “pkg/register” module holds the register map. This component is used to store and retrieve the results of each action’s execution.
- Logging: “pkg/wlog” handles logging across various levels (Info, Error, Warn, Debug). This is used both in direct output and through an optional logging channel.
- Example and Usage: The “example” directory demonstrates how an end-user would initialize and execute the wizard engine. This helps indicate the flow of control from the entry point in an actual deployment.

##### Depicting Relationships and Data Flow
- Within the Task Package, indicate that it calls the Parser and Config Generation modules under “internal” – the configuration is parsed and validated.
- After parsing, the Task Package sequentially picks tasks according to the “priority” field in the JSON and then delegates individual actions to the Action Execution Modules.
- The Action Execution Modules are created using a factory pattern (from the “factory” directory) and their implementations reside in “pkg/actions.”
- Each action, once executed, sends its outcome to:
- The Log System (“pkg/wlog”) which can work directly or via a log channel.
- The Registration Map (“pkg/register”) where details like Changed flag, StdOut, StdErr, and ExitCode are stored.
- Optional use-case: one flow using synchronous Execute() that returns logs as an array, and the other using asynchronous logging through a channel (from task.NewWithLog).

##### Architectural Patterns & Design Principles
- Modular Design: Clear separation between configuration parsing, task execution, action implementation, logging, and registration.
- Factory Pattern: The “factory” folder provides action creation logic and possible interface abstraction so that new actions can be added easily.
- DSL-Driven Execution: The architecture emphasizes interpreting a JSON DSL to drive the automation sequence.
- Error Handling & Conditional Logic: Note “when” clauses on actions controlling whether an action should run based on conditions (e.g., registered variables or command exit codes).

##### Relevant Technologies, Frameworks, or Libraries
- Go language as the primary implementation language.
- Utilization of Go modules (go.mod and go.sum files in various directories indicate dependency management).
- Embedded file systems (as seen in the task package usage with embed.FS).
- Testing frameworks (presence of *_test.go files) suggest unit testing integration.

##### Essential Elements
- Input: JSON DSL provided by the user.
- Task Loader / Executor: "task" package.
- Parser/Config Generator: "internal/parser" and "internal/configen."
- Action Factory: "factory" and its associated mocks.
- Action Handlers: Different actions from "pkg/actions."
- Logging: "pkg/wlog."
- Registration: "pkg/register."
- Example Usage: Include a node for the example directory showing how the system is invoked.
- The initialization sequence: JSON → Task Loader → Parser → Action Factory → Action Execution.
- Data flow post-action: Action Execution → Logger and → Registration map.
- Core processing modules (e.g., Task processing, Parser)
- Support modules (e.g., Logging, Registration)
- Action-specific modules (e.g., Copy, Template, etc., grouped under a common “Action” rectangle)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Layer"
        DSL["JSON DSL Input"] 
    end

    subgraph "Core Processing"
        TASK["Task Management (task package)"]
        PARSER["Parser (internal/parser)"]
        CONFIG["Config Generator (internal/configen)"]
        FACTORY["Action Factory (factory)"]
    end

    subgraph "Action Handling"
        ACTIONS["Action Execution Modules (pkg/actions)"]
        WHEN["'when' Clauses (Conditional Logic)"]
    end

    subgraph "Support Modules"
        LOGGER["Logging (pkg/wlog)"]
        REGISTRY["Registration (pkg/register)"]
    end

    subgraph "Usage"
        EXAMPLE["Example Usage (example)"]
    end

    %% Data Flow
    EXAMPLE -->|"initializes"| TASK
    DSL  -->|"provides configuration"| TASK
    TASK -->|"parses config"| PARSER
    TASK -->|"generates config"| CONFIG
    PARSER -->|"returns parsed config"| FACTORY
    CONFIG  -->|"supplies config"| FACTORY
    FACTORY -->|"creates actions"| ACTIONS
    ACTIONS -->|"executes tasks"| LOGGER
    ACTIONS -->|"saves outcomes"| REGISTRY
    ACTIONS -->|"evaluates"| WHEN
    TASK ---|"sync/async logging"| LOGGER

    %% Click Events
    click DSL "https://github.com/acceldata-io/wizard/tree/main/example/tasks/files"
    click TASK "https://github.com/acceldata-io/wizard/blob/main/task/task.go"
    click PARSER "https://github.com/acceldata-io/wizard/blob/main/internal/parser/parser.go"
    click CONFIG "https://github.com/acceldata-io/wizard/blob/main/internal/configen/configen.go"
    click FACTORY "https://github.com/acceldata-io/wizard/blob/main/factory/action/actions_factory.go"
    click ACTIONS "https://github.com/acceldata-io/wizard/tree/main/pkg/actions"
    click REGISTRY "https://github.com/acceldata-io/wizard/tree/main/pkg/register"
    click LOGGER "https://github.com/acceldata-io/wizard/blob/main/pkg/wlog/wlog.go"
    click EXAMPLE "https://github.com/acceldata-io/wizard/tree/main/example"

    %% Class Definitions
    class DSL input;
    class TASK,PARSER,CONFIG,FACTORY core;
    class ACTIONS,WHEN action;
    class LOGGER,REGISTRY support;
    class EXAMPLE usage;

    %% Style Definitions
    classDef input fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef action fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef support fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef usage fill:#e6ccff,stroke:#333,stroke-width:2px;
```
