# coolguy1771/home-ops architecture

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

- Interactive diagram: https://gitdiagram.com/coolguy1771/home-ops
- Repository: https://github.com/coolguy1771/home-ops

## Overview

##### Main Components
- Infrastructure Layer: Capture the physical hardware (network routers like Vyos, Kubernetes masters/workers, storage servers) as described in the README’s hardware section. Show the networking details (VLANs, load balancing via HAProxy and BGP with Cilium).
- Cluster Management & Provisioning: Include Talos as the operating system for Kubernetes, along with bootstrap procedures in the “talos”, “ansible”, and “pulumi” directories.
- Cloud & External Services: Represent cloud integrations like Cloudflare for public DNS, Fastmail, 1Password (with 1Password Connect integrating secrets), and storage providers (B2, NextDNS) that are partly managed via Pulumi.
- Repository Structure & Automation: Illustrate the “mono repository” concept itself as the source of truth for the entire infrastructure via declarative YAML, kustomizations, and HelmReleases.

- Use distinct sections for different layers. For example, use one layer for physical/hardware infrastructure, the next for Kubernetes clusters and control planes, then a layer for GitOps & infrastructure provisioning, and finally a layer for external integrations.
- Clearly label clusters such as “kyak” and “sol” (as derived from the directory tree under “kubernetes”) since each has its own flux configuration, bootstrap, and apps.
- Networking components such as the DNS flow. For internal DNS, show external-dns syncing records from ingresses (especially those with the “external” ingress class), and for public DNS, link to Cloudflare. Also represent the segmentation in network layers (management VLAN, Kubernetes nodes, pods, and services).

##### Architectural Patterns and Design Principles
- Infrastructure as Code (IaC): Note that Pulumi, Ansible, and Talos are used to define both on-premise and cloud environments. Show how these tools work together to continuously provision, update, and monitor the infrastructure.
- Dependency Management: Illustrate the ordering and dependencies among applications (for example, how postgres must be healthy first).
- Modular and Declarative Configurations: Indicate the “mono repository” structure where directories separate concerns (apps, bootstrap, flux configuration) and how that modularity feeds into the overall architecture.

##### Final Checklist for the Principal Software Engineer
- Main component (hardware, Kubernetes control plane, GitOps & provisioning, applications, cloud integrations) is represented with its own node or group.
- Clearly articulate the relationships (e.g., Git repository → Flux (with kustomizations) → Kubernetes clusters → deployed applications).
- Modularity (show separate directories for “kyak”, “sol”, “pulumi”, “ansible”, etc.) and how these modules integrate into the complete system.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Repository & Automation"
        RS["Mono Repository (Config & Automation)"]:::repo
    end

    subgraph "GitOps Pipeline"
        Fk["Flux (kyak)"]:::gitops
        Fs["Flux (sol)"]:::gitops
        Fa["Flux (archive)"]:::gitops
        gha["GitHub Actions"]:::gitops
        ren["Renovate"]:::gitops
    end

    subgraph "Cluster Management & Provisioning"
        T1["Talos ClusterConfig"]:::cluster
        T2["Talos Config"]:::cluster
        A1["Ansible Cluster Bootstrap (sol)"]:::cluster
        A2["Ansible Storage Servers"]:::cluster
        P1["Pulumi AWS"]:::cluster
        P2["Pulumi Sol"]:::cluster
        P3["Pulumi Cloudflare"]:::cluster
        P4["Pulumi Vault"]:::cluster
    end

    subgraph "Application Deployments"
        AppsKyak["K8s Apps (kyak)"]:::apps
        AppsSol["K8s Apps (sol)"]:::apps
        ArchiveApps["Helm/Kustomize Archive"]:::apps
        Postgres["Postgres DB"]:::apps
        LLDAP["LLDAP Service"]:::apps
        Authelia["Authelia Service"]:::apps
    end

    subgraph "Cloud & External Services"
        CF["Cloudflare DNS"]:::cloud
        AWSs["AWS Services"]:::cloud
        Vaults["Vault Service"]:::cloud
    end

    subgraph "Physical Infrastructure"
        Routers["VyOS Routers"]:::infra
        Masters["Kubernetes Masters"]:::infra
        Workers["Kubernetes Workers"]:::infra
        StorageS["Storage Servers"]:::infra
        LB["HAProxy/BGP Load Balancer"]:::infra
    end

    %% Connections from Repository to GitOps Pipeline
    RS -->|"triggers"| gha
    RS -->|"triggers"| ren
    RS -->|"triggers"| Fk
    RS -->|"triggers"| Fs
    RS -->|"triggers"| Fa

    %% Connections from GitOps Pipeline to Cluster Management & Provisioning
    Fk -->|"syncs"| T1
    Fs -->|"syncs"| T2
    gha -->|"executes"| A1
    ren -->|"updates"| P1
    Fa -->|"syncs"| A1

    %% Connections from Cluster Management & Provisioning to Application Deployments
    T1 -->|"enables"| AppsKyak
    T2 -->|"enables"| AppsSol
    A1 -->|"bootstraps"| AppsKyak
    P1 -->|"provisions"| ArchiveApps
    P2 -->|"provisions"| AppsSol
    P3 -->|"provisions"| ArchiveApps
    P4 -->|"provisions"| ArchiveApps

    %% Application dependency chain
    Postgres -->|"ready-for"| LLDAP
    Postgres -->|"ready-for"| Authelia

    %% Connections from Application Deployments to Cloud & External Services
    ArchiveApps -->|"integrates"| CF
    ArchiveApps -->|"integrates"| AWSs
    ArchiveApps -->|"integrates"| Vaults

    %% Connections from Cluster Management & Provisioning to Physical Infrastructure
    T1 -->|"applied-to"| Masters
    T2 -->|"applied-to"| Workers
    A1 -->|"configures"| Masters
    A2 -->|"configures"| StorageS
    P1 -->|"provisions"| LB

    %% Connections from Physical Infrastructure to Application Deployments
    Masters -->|"hosts"| AppsKyak
    Workers -->|"hosts"| AppsSol
    LB -->|"routes to"| AppsKyak

    %% DNS integration from Cloud to Physical Infrastructure
    CF -->|"routes"| LB

    %% Click Events
    click T1 "https://github.com/coolguy1771/home-ops/tree/main/talos/clusterconfig"
    click T2 "https://github.com/coolguy1771/home-ops/blob/main/talos/talconfig.yaml"
    click A1 "https://github.com/coolguy1771/home-ops/tree/main/ansible/sol"
    click A2 "https://github.com/coolguy1771/home-ops/tree/main/ansible/storage/servers"
    click P1 "https://github.com/coolguy1771/home-ops/tree/main/pulumi/aws"
    click P2 "https://github.com/coolguy1771/home-ops/tree/main/pulumi/sol"
    click P3 "https://github.com/coolguy1771/home-ops/tree/main/pulumi/cloudflare"
    click P4 "https://github.com/coolguy1771/home-ops/tree/main/pulumi/vault"
    click Fk "https://github.com/coolguy1771/home-ops/tree/main/kubernetes/kyak/flux"
    click Fs "https://github.com/coolguy1771/home-ops/tree/main/kubernetes/sol/flux"
    click Fa "https://github.com/coolguy1771/home-ops/tree/main/.archive/cobra/flux"
    click gha "https://github.com/coolguy1771/home-ops/tree/main/.github/workflows"
    click ren "https://github.com/coolguy1771/home-ops/blob/main/.renovate"
    click AppsKyak "https://github.com/coolguy1771/home-ops/tree/main/kubernetes/kyak/apps"
    click AppsSol "https://github.com/coolguy1771/home-ops/tree/main/kubernetes/sol/apps"
    click ArchiveApps "https://github.com/coolguy1771/home-ops/tree/main/.archive/cobra/apps"
    click RS "https://github.com/coolguy1771/home-ops/blob/main/README.md"

    %% Styles
    classDef repo fill:#D6DBDF,stroke:#566573,stroke-width:2px;
    classDef gitops fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
    classDef cluster fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef apps fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef cloud fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef infra fill:#F2D7D5,stroke:#C0392B,stroke-width:2px;
```
