# belmironeto/homelab architecture

> Architecture diagram of the GitHub repository belmironeto/homelab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/belmironeto/homelab
- Repository: https://github.com/belmironeto/homelab

## Overview

##### Project type and purpose
- This is an “infrastructure-as-code” homelab project. It orchestrates virtual machines (via Proxmox), Kubernetes clusters (via K3s), and GitOps (via ArgoCD) using Terraform, a custom Terraform provider, and Ansible playbooks.

##### File structure
- Top-level:
- ansible_playbooks/ – provisioning & configuration roles for K3s, ArgoCD, ingress, contexts, cluster joins
- terraform_modules/ – reusable Terraform code for Proxmox VMs (k8s_nodes)
- terraform_stack/ – concrete Terraform stacks (k3s_argo, k8s_default) with state and inventory templates
- terraform_provider/ – Go code for a custom “multirouter” Terraform provider
- argocd_platform/ – GitOps config (applicationset) for ArgoCD
- Patterns & config:
- Terraform modules vs. stacks (module reuse vs. environment-level stacks)
- Ansible roles organized by concern (install_k3s, init_master, join_workers, install_argocd, etc.)
- Inventory templating for dynamic host lists

##### README for additional insights
- Simple summary: “A homelab project with some IaC – Ansible Playbooks, Terraform Modules, Terraform Stack.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Layer
    subgraph "Control Layer"
        direction TB
        Dev["Developer / Control Host"]:::external
        GitRepo["Git Repository"]:::state
        TerraformCLI["Terraform CLI"]:::terraform
        AnsibleCtrl["Ansible Controller"]:::ansible
    end

    Dev -->|"push code"| GitRepo
    GitRepo -->|"source code"| TerraformCLI
    GitRepo -->|"source code"| AnsibleCtrl

    %% Provisioning Layer
    subgraph "Provisioning Layer"
        direction TB
        Modules["Terraform Modules"]:::terraform
        Stacks["Terraform Stacks"]:::terraform
        CustomProv["Custom Provider\n(terraform-provider-multirouter)"]:::terraform
        ProxmoxAPI["Proxmox API"]:::external
    end

    TerraformCLI -->|"plan/apply"| Modules
    TerraformCLI -->|"plan/apply"| Stacks
    TerraformCLI -->|"uses provider"| CustomProv
    Modules -->|"VM create"| ProxmoxAPI
    CustomProv -->|"plugin"| TerraformCLI
    TerraformCLI -->|"call API"| ProxmoxAPI

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        VMs["Proxmox VMs"]:::external
    end

    ProxmoxAPI -->|"creates"| VMs

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        Inventory["Inventory Template"]:::ansible
        Playbooks["Ansible Playbooks"]:::ansible
        K3sCluster["K3s Cluster\n(masters & workers)"]:::k8s
    end

    Stacks -->|"generate"| Inventory
    Inventory -->|"feeds"| Playbooks
    Playbooks -->|"ssh configure"| VMs
    VMs -->|"install"| K3sCluster

    %% GitOps Layer
    subgraph "GitOps Layer"
        direction TB
        ArgoCDServer["ArgoCD Server"]:::gitops
        ArgoCDConfig["ArgoCD GitOps Config"]:::state
    end

    GitRepo -->|"hosts apps config"| ArgoCDConfig
    ArgoCDServer -->|"sync/gitops"| ArgoCDConfig
    ArgoCDServer -->|"reconcile"| K3sCluster

    %% Click Events
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/"
    click Inventory "https://github.com/belmironeto/homelab/blob/main/ansible_playbooks/inventory.tftpl"
    click Playbooks "https://github.com/belmironeto/homelab/blob/main/ansible_playbooks/create_k8s_cluster.yml"
    click Playbooks "https://github.com/belmironeto/homelab/blob/main/ansible_playbooks/destroy_k8s.yml"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/install_k3s/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/init_k8s_master/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/join_k8s_workers/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/install_k8s_dependencies/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/install_ingress_nginx/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/install_argocd/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/argo_add_cluster/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/argo_remove_cluster/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/k8s_add_context/"
    click Playbooks "https://github.com/belmironeto/homelab/tree/main/ansible_playbooks/roles/k8s_remove_context/"
    click Modules "https://github.com/belmironeto/homelab/tree/main/terraform_modules/proxmox/"
    click Modules "https://github.com/belmironeto/homelab/tree/main/terraform_modules/proxmox/k8s_nodes/"
    click Stacks "https://github.com/belmironeto/homelab/tree/main/terraform_stack/k3s_argo/"
    click Stacks "https://github.com/belmironeto/homelab/blob/main/terraform_stack/k3s_argo/inventory.tftpl"
    click Stacks "https://github.com/belmironeto/homelab/tree/main/terraform_stack/k8s_default/"
    click Stacks "https://github.com/belmironeto/homelab/blob/main/terraform_stack/k8s_default/inventory.tftpl"
    click CustomProv "https://github.com/belmironeto/homelab/tree/main/terraform_provider/terraform-provider-multirouter/"
    click ArgoCDConfig "https://github.com/belmironeto/homelab/tree/main/argocd_platform/"

    %% Styles
    classDef terraform fill:#e6ffed,stroke:#2ca02c,stroke-width:2px;
    classDef ansible fill:#e7f0fd,stroke:#1f77b4,stroke-width:2px;
    classDef k8s fill:#fff2e6,stroke:#ff7f0e,stroke-width:2px;
    classDef gitops fill:#fff5e6,stroke:#d62728,stroke-width:2px;
    classDef external fill:#f0f0f0,stroke:#7f7f7f,stroke-width:2px;
    classDef state fill:#f9f9f9,stroke:#9467bd,stroke-width:2px;
```
