| name | homelab-architect |
| description | Architectural standards and workflows for the Homelab mono-repo. |
Homelab Architecture Standards
Goal
To maintain a clean, consistent, and automated mono-repo for infrastructure and platform engineering.
1. Directory Structure
infra/pulumi: The source of truth for all Infrastructure as Code.
proxmox.go: VM/Cluster logic.hetzner_vps.go: Cloud logic.main.go: Entry point, service selection (k config).
.agent/skills: Knowledge base for the AI Agent.platform/: Ansible, CDK8s, or other config management (if used).
2. The "Just" Workflow
We use just (Justfile) as the single entry point for all operations.
- Why: Abstraction. The user shouldn't remember long Pulumi flags or Ansible paths.
- Standard Commands:
just deploy-proxmox: The robust, auto-recovering deploy (Up -> Refresh -> Up).just pulumi <stack> <action>: Generic wrapper.
- Rule: If a workflow is complex (more than 1 command), WRAP IT in the Justfile.
3. Configuration Management
- Loader: Global
k (using knadh/koanf) in config.go.
- Source: Reads
.env and defaults.
- Pattern:
InitConfig() loads everything at start.os.Setenv is used to pass secrets (like PROXMOX_PASSWORD) to Providers.- Do NOT hardcode secrets in Go files.
4. Verification Strategy
"Trust but Verify".
- Infrastructure: Verified by Pulumi (exit code 0).
- Applications: Verified by shell scripts (
verify_cluster.sh).
- Why? Pulumi
Helm provider can sometimes stall if the cluster is not fully healthy yet. A script with kubectl wait loops is often more robust for initial bootstrap checks.
5. Agent Interaction
- Artifacts: Always keep
task.md and implementation_plan.md up to date in the brain/ directory.
- Skills: If a new pattern emerges (e.g., "Deploying MinIO"), create a new SKILL.md for it.
6. Versioning Strategy
- Explicit Pinning: Always use specific tags/versions for software, charts, and images (e.g.,
v1.2.3, chart: 4.5.6).
- No
latest: Never rely on latest tag or implicit version fetching.
- Reason: Predictability and reproducibility.
