How acceldata-io/wizard works
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)