Air-Gap Code Structure

Purpose: For contributors, provides Air-Gap Python package layout and build pipeline modules.

Package layout

openCenter-AirGap/
├── src/opencenter_build/       # Main package
│   ├── __init__.py
│   ├── cli.py                  # Typer CLI entry point
│   ├── orchestrator.py         # Build pipeline orchestration
│   ├── config.py               # Configuration loading and validation
│   ├── state.py                # Build state persistence
│   ├── transaction.py          # Transactional build steps
│   ├── manifest.py             # Image/chart manifest handling
│   ├── component_manifest.py   # Component-level manifest tracking
│   ├── image_utils.py          # Container image operations
│   ├── zarf_generator.py       # Zarf package YAML generation
│   ├── zarf_utils.py           # Zarf CLI wrapper utilities
│   ├── scanner.py              # Image and chart scanning
│   ├── validation.py           # Input and config validation
│   ├── verifier.py             # Package integrity verification
│   ├── version_utils.py        # Version parsing and comparison
│   ├── secrets.py              # Secrets handling for registries
│   ├── metrics.py              # Build metrics collection
│   ├── logging.py              # Structured logging setup
│   └── exceptions.py           # Custom exception hierarchy
├── tests/                      # pytest + hypothesis tests
├── config/                     # Default configuration files
├── pyproject.toml              # Project metadata and tool config
└── zarf.yaml.template          # Zarf package template

Module responsibilities

Module	Responsibility
cli.py	Typer-based CLI. Defines init, build, and related commands. Entry point registered as opencenter-airgap in pyproject.toml.
orchestrator.py	Coordinates the full build pipeline: config loading → image collection → Zarf generation → packaging. Calls other modules in sequence.
config.py	Loads versions.env and YAML config files. Validates required fields using jsonschema.
state.py	Persists build state to disk so builds can resume after failure. Tracks which steps completed.
transaction.py	Wraps build steps in transactions. If a step fails, rolls back partial artifacts.
manifest.py	Parses and generates image manifests. Tracks which container images and Helm charts to include.
component_manifest.py	Tracks individual components (services from gitops-base) and their image/chart dependencies.
image_utils.py	Pulls, tags, and saves container images. Handles multi-arch manifests and registry authentication.
zarf_generator.py	Generates zarf.yaml from the collected manifests and component list.
zarf_utils.py	Wraps the zarf CLI binary for package creation and deployment commands.
scanner.py	Scans images and charts for vulnerabilities and generates reports.
validation.py	Validates inputs (versions, URLs, file paths) before the build starts.
verifier.py	Verifies package integrity after build (checksums, signatures).
version_utils.py	Parses semver strings, compares versions, resolves version constraints.
secrets.py	Manages registry credentials for pulling images from private registries.
metrics.py	Collects build timing, image counts, and package sizes. Outputs to logs and optional metrics file.
logging.py	Configures structured logging with Rich console output.
exceptions.py	Defines BuildError, ConfigError, ValidationError, and other domain exceptions.

Entry point

The CLI is registered in pyproject.toml:

[project.scripts]
opencenter-airgap = "opencenter_build.cli:main"

Running opencenter-airgap build invokes cli.main(), which delegates to orchestrator.py.

Key dependencies

Package	Version	Purpose
typer	0.21.1	CLI framework
rich	13.7.0	Terminal output formatting
pyyaml	6.0.1	YAML parsing
jsonschema	4.21.1	Configuration validation
python-dotenv	1.0.1	Loading versions.env files

Dev dependencies include pytest 7.4.4, hypothesis 6.98.3, black 24.1.1, mypy 1.8.0, and pylint 3.0.3.