Architecture

System Overview

jhf-deployment is organized around IaC environments and reusable modules.

Primary layers:

• modules/
  • Docker, networking, compute, storage, and fabric-datasource
• environments/
  • concrete local/test/staging entrypoints
• environments/test/scripts/
  • operator and runner execution path
• fabric-manifest.json plus scripts/export-fabric-metadata.py
  • machine-readable repo self-description

Main Components

• Docker environment modules
  • model local containerized stacks
• generic root modules/compute, modules/networking, and modules/storage
  • fail-closed placeholder interfaces only; active infrastructure implementations must come from provider-specific modules such as the Hetzner variants
• fabric-datasource
  • reads Fabric inventory and version hints over HTTP GET
• environments/test
  • bounded scenario catalog and mixed-source artifact test path
• environments/hetzner-staging
  • minimal staging skeleton for future rollout work
• metadata export and selfcheck scripts
  • validate that docs and manifest match the checked-in repo state

Data Flow

1. operator or CI invokes the IaC lifecycle or helper scripts
2. environments/test resolves scenario composition and explicit artifact inputs
3. optional Fabric datasource reads inventory and version hints
4. the IaC lifecycle produces plan/output data for the selected environment
5. helper scripts verify selected endpoints or state
6. metadata export surfaces repo-level environments, scenarios, dependencies, and Fabric-read posture

Internal And External Interfaces

• internal:
  • IaC variables and outputs
  • Bash helper scripts
  • file-based manifest/export contract
• external:
  • Fabric HTTP read endpoints
  • Docker host / Docker socket
  • OCI registries / Gitea Packages
  • Hetzner Cloud provider API through the IaC layer

Dependencies

• OpenTofu CLI and IaC providers
• Docker Engine for local/test mutation
• Python 3 and Bash for scripts
• optional Fabric availability for read-time enrichment

Operational Assumptions

• Linux-based Gitea runner is the reference validation platform
• helper scripts are bash-compatible and LF-oriented
• artifact resolution remains explicit and outside the IaC layer if a resolver is later added

Role In The Helpifyr Ecosystem

• supporting platform tool
• not a core runtime product
• supplies deployment context, scenario definitions, and pinned artifact inputs for test systems

Expected Role Toward jhf-fabric

• Fabric may read:
  • repo metadata
  • environments and scenarios
  • version-source defaults
  • CI validation status
• Fabric should not directly control:
  • terraform apply
  • terraform destroy
  • shared-host Docker mutation

---

License: AGPLv3 Source and governance: https://helpifyr.com