Developer Guide

Architecture overview, contribution guidelines, and API reference for Parallax

This document describes the architecture of Parallax, how to contribute, and provides a brief API overview.

Architecture Overview

+-------------+      +---------------+      +----------------+
| CLI (cobra) | -->  | Core Packages | -->  | Module Runtime |
+-------------+      +---------------+      +----------------+

1. CLI Layer: Located under cmd/ and pkg/cmd. It defines commands such as play and handles configuration.
2. Core Packages: Found in pkg/, these handle inventory parsing, playbook parsing, remote connections, and module execution.
3. Module Runtime: Implemented in pkg/module and module-sdk, providing built-in modules and a framework for custom modules.

Contribution Guidelines

• Use Conventional Commits: type(scope): brief description, with an optional scope. Examples: fix(play): preserve handler host scope, feat(ci): add Windows runners, and docs: clarify setup. Use ! or a BREAKING CHANGE: footer for breaking changes.
• Run task lint, task test, and task acceptance before submitting a merge request. task test includes both the controller and nested module SDK with race detection.
• Format code with gofmt.
• Documentation updates should accompany code changes when relevant.

API Overview

The key packages are:

• inventory: Parses INI, YAML, and dynamic inventory sources and resolves host patterns.
• playbook: Loads and validates YAML playbooks.
• remote: Provides SSH, WinRM, and local connection implementations.
• module: Contains the module executor and registry.

Each package exposes well-documented Go types and functions. See the source files under pkg/ for details.