# insuperposition/firmament architecture

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

- Interactive diagram: https://gitdiagram.com/insuperposition/firmament
- Repository: https://github.com/insuperposition/firmament

## Overview

Firmament declaratively provisions one Kubernetes host: the local environment composes an OrbStack VM, Ubuntu readiness checks, and k0s, then bootstraps Flux and Cilium. Flux reconciles the GitOps packages, including its own installation. The README documents this ordering and the shared state and kubeconfig; source excerpts were unavailable, so implementation-level wiring beyond those documented relationships is omitted.

Main entry points: [`environment/local/main.tf`](https://github.com/insuperposition/firmament/blob/main/environment/local/main.tf) (Local Environment), [`components/cni-cilium/kustomization.yaml`](https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/kustomization.yaml) (Cilium Package), [`environment/local/bootstrap.tf`](https://github.com/insuperposition/firmament/blob/main/environment/local/bootstrap.tf) (Cluster Bootstrap), [`components/gitops-flux/fluxinstance.yaml`](https://github.com/insuperposition/firmament/blob/main/components/gitops-flux/fluxinstance.yaml) (Flux)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Environment"]
  node_environment_config["Local Environment<br/>[main.tf]"]
  node_bootstrap["Cluster Bootstrap<br/>[bootstrap.tf]"]
  node_state[("OpenTofu State")]
  node_kubeconfig["Kubeconfig"]
end

subgraph group_modules["Infrastructure Modules"]
  node_vm_module["OrbStack VM<br/>[main.tf]"]
  node_ubuntu_module["Ubuntu Readiness<br/>[main.tf]"]
  node_k0s_module["k0s Node<br/>[main.tf]"]
end

subgraph group_gitops["GitOps Packages"]
  node_flux_package["Flux Package<br/>[kustomization.yaml]"]
  node_cilium_package["Cilium Package<br/>[kustomization.yaml]"]
end

subgraph group_cluster["Cluster Services"]
  node_flux_runtime["Flux<br/>[fluxinstance.yaml]"]
  node_cilium_runtime["Cilium<br/>[helmrelease.yaml]"]
  node_hubble["Hubble<br/>[helmrelease.yaml]"]
  node_kubernetes["Kubernetes Cluster"]
end

node_operator(("Operator"))
node_orbstack["OrbStack"]

node_operator -->|"applies"| node_environment_config
node_environment_config -->|"composes"| node_vm_module
node_environment_config -->|"composes"| node_ubuntu_module
node_environment_config -->|"composes"| node_k0s_module
node_environment_config -->|"stores state"| node_state
node_environment_config -->|"owns file"| node_kubeconfig
node_vm_module -->|"provisions VM"| node_orbstack
node_environment_config -->|"checks readiness"| node_ubuntu_module
node_environment_config -->|"installs k0s"| node_k0s_module
node_k0s_module -->|"creates cluster"| node_kubernetes
node_environment_config -->|"runs bootstrap"| node_bootstrap
node_bootstrap -->|"installs"| node_flux_package
node_bootstrap -->|"installs"| node_cilium_package
node_flux_runtime -->|"reconciles"| node_flux_package
node_flux_runtime -->|"reconciles"| node_cilium_package
node_flux_package -->|"installs"| node_flux_runtime
node_cilium_package -->|"installs"| node_cilium_runtime
node_cilium_package -->|"installs"| node_hubble

click node_environment_config "https://github.com/insuperposition/firmament/blob/main/environment/local/main.tf"
click node_bootstrap "https://github.com/insuperposition/firmament/blob/main/environment/local/bootstrap.tf"
click node_vm_module "https://github.com/insuperposition/firmament/blob/main/modules/vm-orb/main.tf"
click node_ubuntu_module "https://github.com/insuperposition/firmament/blob/main/modules/os-ubuntu/main.tf"
click node_k0s_module "https://github.com/insuperposition/firmament/blob/main/modules/orch-k0s/main.tf"
click node_flux_package "https://github.com/insuperposition/firmament/blob/main/components/gitops-flux/kustomization.yaml"
click node_cilium_package "https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/kustomization.yaml"
click node_flux_runtime "https://github.com/insuperposition/firmament/blob/main/components/gitops-flux/fluxinstance.yaml"
click node_cilium_runtime "https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/helmrelease.yaml"
click node_hubble "https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/helmrelease.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_environment_config,node_bootstrap,node_state,node_kubeconfig toneBlue
class node_vm_module,node_ubuntu_module,node_k0s_module toneAmber
class node_flux_package,node_cilium_package toneMint
class node_flux_runtime,node_cilium_runtime,node_hubble,node_kubernetes toneRose
class node_operator,node_orbstack toneIndigo
```

## Components

### Environment

- [Local Environment](https://github.com/insuperposition/firmament/blob/main/environment/local/main.tf): `environment/local/main.tf`
- [Cluster Bootstrap](https://github.com/insuperposition/firmament/blob/main/environment/local/bootstrap.tf): `environment/local/bootstrap.tf`
- **OpenTofu State**
- **Kubeconfig**

### Infrastructure Modules

- [OrbStack VM](https://github.com/insuperposition/firmament/blob/main/modules/vm-orb/main.tf): `modules/vm-orb/main.tf`
- [Ubuntu Readiness](https://github.com/insuperposition/firmament/blob/main/modules/os-ubuntu/main.tf): `modules/os-ubuntu/main.tf`
- [k0s Node](https://github.com/insuperposition/firmament/blob/main/modules/orch-k0s/main.tf): `modules/orch-k0s/main.tf`

### GitOps Packages

- [Flux Package](https://github.com/insuperposition/firmament/blob/main/components/gitops-flux/kustomization.yaml): `components/gitops-flux/kustomization.yaml`
- [Cilium Package](https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/kustomization.yaml): `components/cni-cilium/kustomization.yaml`

### Cluster Services

- [Flux](https://github.com/insuperposition/firmament/blob/main/components/gitops-flux/fluxinstance.yaml): `components/gitops-flux/fluxinstance.yaml`
- [Cilium](https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/helmrelease.yaml): `components/cni-cilium/helmrelease.yaml`
- [Hubble](https://github.com/insuperposition/firmament/blob/main/components/cni-cilium/helmrelease.yaml): `components/cni-cilium/helmrelease.yaml`
- **Kubernetes Cluster**

### Other components

- **Operator**
- **OrbStack**

## Connections

- Operator → Local Environment: applies
- Local Environment → OrbStack VM: composes
- Local Environment → Ubuntu Readiness: composes
- Local Environment → k0s Node: composes
- Local Environment → OpenTofu State: stores state
- Local Environment → Kubeconfig: owns file
- OrbStack VM → OrbStack: provisions VM
- Local Environment → Ubuntu Readiness: checks readiness
- Local Environment → k0s Node: installs k0s
- k0s Node → Kubernetes Cluster: creates cluster
- Local Environment → Cluster Bootstrap: runs bootstrap
- Cluster Bootstrap → Flux Package: installs
- Cluster Bootstrap → Cilium Package: installs
- Flux → Flux Package: reconciles
- Flux → Cilium Package: reconciles
- Flux Package → Flux: installs
- Cilium Package → Cilium: installs
- Cilium Package → Hubble: installs