# ataylor-us/infra architecture

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

- Interactive diagram: https://gitdiagram.com/ataylor-us/infra
- Repository: https://github.com/ataylor-us/infra

## Overview

##### Project type and purpose
- This is an Infrastructure-as-Code (IaC) project, using Ansible to automate configuration of a home lab:
– A hypervisor host (EL10) running multiple VMs and containers.
– A Fedora “client” VM used as the Ansible control node.
– Additional EL10 VM hosting services.
– A separate physical workstation.
- Services include reverse proxy (Caddy), backups (borgmatic), mail notifications, CalDAV/CardDAV clients, container hosts, file sync, virtualization, etc.
- Secrets are managed via Ansible Vault (backed by Bitwarden), network overlay by Tailscale.

##### File structure
- Top-level playbooks:
– master.yml (full run)
– playbooks/update_packages.yml, clean_packages.yml, client_sync.yml
- Inventory and variables:
– hosts.yml defines groups: container_hosts, interactive_boxes, etc.
– group_vars/ and host_vars/ contain per-group and per-host settings plus vault files.
- Roles directory:
– Dozens of roles, each encapsulating a single service or concern (e.g. reverse_proxy, backups, virtualization, notifications).
– Each role has defaults/, tasks/, handlers/, templates/ or files/.
- Configuration:
– ansible.cfg, requirements.yml (external roles), .get-vault-pass.sh, .get-become-pass.sh.

##### README for architecture insights
- Describes network topology:
– One hypervisor (bare-metal) running two VMs.
– Fedora VM as control node for Ansible.
– EL10 VM for extra services.
– Separate workstation.
– All hosts connected over Tailscale.
- External dependencies: Bitwarden for vault secrets, Borgbase for backups, Pushover for notifications, Tailscale auth server.

##### Components and interactions
1. Ansible Control Plane
– Your local machine (runs .get-become-pass.sh, .get-vault-pass.sh).
– Fedora “client” VM (inventory, group_vars, roles, master.yml).
2. Inventory / Variables store
– hosts.yml, group_vars/, host_vars/
3. Target Hosts
– Hypervisor (EL10 bare-metal)
- KVM/QEMU virtualization host
- Runs “container_hosts” group roles (containers, virtualization templates)
– VM Service Host (EL10)
- Runs Caddy reverse_proxy, backups, file_sync, feed_reader, etc.
– Workstation (interactive_boxes)
- Runs desktop-type roles: ide, editor, file_manager, email_client, pim_client
4. External Services
– Tailscale coordination server
– Bitwarden vault (secret retrieval)
– Borgbase (remote backup repo)
– Pushover (notifications)
– Control VM → hypervisor/VMs/workstation: SSH connections, Ansible playbook execution.
– Hosts ↔ Tailscale server: overlay network traffic.
– Roles/templates → local services on each host (Caddy config, system service enable/disable).
– Hosts → Borgbase: backup data push.
– Hosts → Bitwarden: vault secrets pull.
– Hosts → Pushover API: mailrise notifications.
c. Architectural patterns and design principles
– Modular role-based IaC: one role per service/concern.
– Separation of control plane (Ansible controller) vs. data plane (inventory hosts).
– Group_vars/host_vars layered configuration for environment segmentation.
– Template-driven configuration (Jinja2 templates for Caddyfiles, configs).
– Externalized secrets via Vault plugin.
d. Key technologies and frameworks
– Ansible (playbooks, roles, inventory)
– SSH for transport
– Jinja2 templating
– KVM/QEMU virtualization
– Caddy reverse proxy
– Borgmatic / Borgbase for backups
– Tailscale for mesh networking
– Bitwarden CLI for vault secrets
– Pushover API for notifications
– vdirsyncer for CalDAV/CardDAV sync

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane" 
        direction TB
        LM["Local Machine"]:::control
        CFG["ansible.cfg"]:::control
        PASS1[".get-become-pass.sh"]:::control
        PASS2[".get-vault-pass.sh"]:::control
        MSTR["master.yml"]:::control
        subgraph "Playbooks"
            direction TB
            PU["update_packages.yml"]:::control
            PC["clean_packages.yml"]:::control
            PS["client_sync.yml"]:::control
        end
        VM["Fedora VM (Ansible Control Node)"]:::control
    end

    %% Inventory / Variables Store
    subgraph "Inventory / Variables Store"
        direction TB
        HOSTS["hosts.yml"]:::inventory
        GV["group_vars/"]:::inventory
        HV["host_vars/"]:::inventory
    end

    %% Managed Hosts
    subgraph "Managed Hosts"
        direction TB
        HYP["Hypervisor (EL10 bare-metal)"]:::managed
        VMHOST["VM Service Host (EL10 VM)"]:::managed
        WS["Workstation"]:::managed
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TS["Tailscale Coordination"]:::external
        BW["Bitwarden Vault"]:::external
        BB["Borgbase Backup Repo"]:::external
        PP["Pushover API"]:::external
    end

    %% Connections
    LM -->|"Ansible CLI & Vault helpers"| VM
    VM -->|"SSH & Playbook Execution"| HYP
    VM -->|"SSH & Playbook Execution"| VMHOST
    VM -->|"SSH & Playbook Execution"| WS

    HYP <-->|"Mesh Network"| TS
    VMHOST <-->|"Mesh Network"| TS
    WS <-->|"Mesh Network"| TS

    HYP -->|"Vault Secrets Pull"| BW
    VMHOST -->|"Vault Secrets Pull"| BW
    WS -->|"Vault Secrets Pull"| BW

    VMHOST -->|"Backup Push"| BB
    VMHOST -->|"Notifications"| PP

    %% Click Events - Control Plane
    click CFG "https://github.com/ataylor-us/infra/blob/main/.ansible.cfg"
    click PASS1 "https://github.com/ataylor-us/infra/blob/main/.get-become-pass.sh"
    click PASS2 "https://github.com/ataylor-us/infra/blob/main/.get-vault-pass.sh"
    click MSTR "https://github.com/ataylor-us/infra/blob/main/master.yml"
    click PU "https://github.com/ataylor-us/infra/blob/main/playbooks/update_packages.yml"
    click PC "https://github.com/ataylor-us/infra/blob/main/playbooks/clean_packages.yml"
    click PS "https://github.com/ataylor-us/infra/blob/main/playbooks/client_sync.yml"

    %% Click Events - Inventory
    click HOSTS "https://github.com/ataylor-us/infra/blob/main/hosts.yml"
    click GV "https://github.com/ataylor-us/infra/tree/main/group_vars/"
    click HV "https://github.com/ataylor-us/infra/tree/main/host_vars/"

    %% Click Events - Hypervisor Host components
    click HYP "https://github.com/ataylor-us/infra/blob/main/group_vars/container_hosts/vars.yml"
    click HYP "https://github.com/ataylor-us/infra/tree/main/roles/virtualization/"
    click HYP "https://github.com/ataylor-us/infra/tree/main/roles/containers/"

    %% Click Events - VM Service Host components
    click VMHOST "https://github.com/ataylor-us/infra/blob/main/host_vars/recipe_vps/vault.yml"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/reverse_proxy/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/backups/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/file_sync/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/feed_reader/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/bookmarks/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/photos/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/recipes/"
    click VMHOST "https://github.com/ataylor-us/infra/tree/main/roles/notifications/"

    %% Click Events - Workstation components
    click WS "https://github.com/ataylor-us/infra/blob/main/host_vars/workstation/vars.yml"
    click WS "https://github.com/ataylor-us/infra/blob/main/host_vars/workstation/vault.yml"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/ide/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/editor/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/file_manager/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/email_client/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/pim_client/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/terminal/"
    click WS "https://github.com/ataylor-us/infra/tree/main/roles/version_control/"

    %% Click Events - External Secrets & Backup Repo
    click BW "https://github.com/ataylor-us/infra/blob/main/group_vars/all/vault.yml"
    click BB "https://github.com/ataylor-us/infra/tree/main/roles/backups/"

    %% Styles
    classDef control fill:#D6E9FF,stroke:#4D79FF,stroke-width:1px;
    classDef inventory fill:#E8F4FF,stroke:#79AFFF,stroke-width:1px;
    classDef managed fill:#E6FFEA,stroke:#33CC66,stroke-width:1px;
    classDef external fill:#FFF4E6,stroke:#FF9933,stroke-width:1px;
```
