# penguinoneshaw/flux architecture

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

- Interactive diagram: https://gitdiagram.com/penguinoneshaw/flux
- Repository: https://github.com/penguinoneshaw/flux

## Overview

##### Project type and purpose
- This is a GitOps repository for Kubernetes, using Flux v2 and Kustomize to declaratively manage apps and infrastructure.
- Its purpose is to hold all cluster-wide and application-level configuration in Git, synchronize it to one or more clusters, and automate releases via controllers.

##### File structure
Top-level directories:
- apps/    – Kustomize “base” and “overlay” definitions of user workloads (e.g., audiobookshelf, home-assistant, pihole).
- clusters/ – Per-cluster overlay (here clusters/x86) defining which apps and controllers to deploy.
- infrastructure/ – Core platform controllers (Ingress, cert-manager, Prometheus, MetalLB, Tailscale, etc.) and load-balancer configurations.
- secrets/ – Kubernetes Secret manifests referenced by your kustomizations.
- .github/ & scripts/ – CI workflows (lint, e2e), validation scripts.

##### README
Only a title (“Flux configuration”) is provided. Use the directory naming and kustomization.yaml files as the primary source of architecture details.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% GitOps Repository Layer
  subgraph "GitHub Repo (GitOps Repository)"
    RepoCyl["Git Repo Root"]:::git
    apps_base["apps/base/"]:::app
    shared_repos["apps/base/shared-repositories"]:::app
    apps_x86["apps/x86"]:::app
    clusters_apps["clusters/x86/apps.yaml"]:::cluster
    clusters_infra["clusters/x86/infrastructure.yaml"]:::cluster
    clusters_flux["clusters/x86/flux-system/"]:::cluster
    infra_ctrl["infrastructure/controllers/"]:::infra
    infra_lb["infrastructure/load-balancer/"]:::infra
    secrets_node["secrets/kustomization.yaml"]:::secret
    ci_workflow[".github/workflows/test.yaml"]:::ci
    script_val["scripts/validate.sh"]:::ci
  end

  %% Flux Controllers
  subgraph "Flux Controllers" 
    src_ctrl["source-controller"]:::controller
    kustomize_ctrl["kustomize-controller"]:::controller
    helm_ctrl["helm-controller"]:::controller
    notif_ctrl["notification-controller"]:::controller
  end

  %% Kubernetes Cluster
  subgraph "Kubernetes Cluster"
    KAPI["API Server"]:::cluster
    Nodes["Worker Nodes"]:::cluster
  end

  %% External Services
  ContainerReg["Container Registry"]:::external
  ExternalDNS["External DNS / Tailscale"]:::external

  %% Relationships
  RepoCyl -->|sync| src_ctrl
  src_ctrl --> kustomize_ctrl
  src_ctrl --> helm_ctrl
  src_ctrl --> notif_ctrl

  kustomize_ctrl -->|"build overlays"| apps_base
  apps_base --> shared_repos
  apps_base --> apps_x86
  apps_x86 --> clusters_apps
  apps_x86 --> clusters_infra
  apps_x86 --> clusters_flux
  kustomize_ctrl --> secrets_node
  kustomize_ctrl --> clusters_flux

  helm_ctrl --> infra_ctrl
  helm_ctrl --> infra_lb

  src_ctrl -->|apply GitRepository| KAPI
  kustomize_ctrl -->|apply Manifests| KAPI
  helm_ctrl -->|helm install| KAPI
  notif_ctrl -->|alerts| ExternalDNS

  KAPI -->|schedule| Nodes

  apps_x86 -->|pull images| ContainerReg

  ci_workflow -->|validate| RepoCyl
  script_val -->|run| RepoCyl

  %% Click Events
  click RepoCyl "https://github.com/penguinoneshaw/flux/tree/main//"
  click clusters_flux "https://github.com/penguinoneshaw/flux/tree/main/clusters/x86/flux-system/"
  click clusters_apps "https://github.com/penguinoneshaw/flux/blob/main/clusters/x86/apps.yaml"
  click clusters_infra "https://github.com/penguinoneshaw/flux/blob/main/clusters/x86/infrastructure.yaml"
  click apps_base "https://github.com/penguinoneshaw/flux/tree/main/apps/base/"
  click shared_repos "https://github.com/penguinoneshaw/flux/blob/main/apps/base/shared-repositories/kustomization.yaml"
  click apps_x86 "https://github.com/penguinoneshaw/flux/blob/main/apps/x86/kustomization.yaml"
  click infra_ctrl "https://github.com/penguinoneshaw/flux/blob/main/infrastructure/controllers/kustomization.yaml"
  click infra_lb "https://github.com/penguinoneshaw/flux/blob/main/infrastructure/load-balancer/kustomization.yaml"
  click secrets_node "https://github.com/penguinoneshaw/flux/blob/main/secrets/kustomization.yaml"
  click ci_workflow "https://github.com/penguinoneshaw/flux/blob/main/.github/workflows/test.yaml"
  click script_val "https://github.com/penguinoneshaw/flux/blob/main/scripts/validate.sh"

  %% Styles
  classDef git fill:#e0ffe0,stroke:#00a000,color:#006000
  classDef controller fill:#e0f0ff,stroke:#0060a0,color:#003080
  classDef app fill:#fff0d0,stroke:#ffa000,color:#a06000
  classDef infra fill:#f0f0f0,stroke:#909090,color:#505050
  classDef secret fill:#f8f8f8,stroke:#808080,color:#404040
  classDef ci fill:#e0ffe0,stroke:#00a000,color:#006000
  classDef external fill:#ffe0ff,stroke:#a00060,color:#600030
  classDef cluster fill:#f0f8ff,stroke:#0080c0,color:#004060
```
