Developer Guide

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

  • Follow the commit message style type(scope): description.
  • Run go vet, golint, and go test ./... before submitting a pull request.
  • Format code with gofmt -s.
  • 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.

Plugin Porting Guide Migration Guide