# livenson/talu architecture

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

- Interactive diagram: https://gitdiagram.com/livenson/talu
- Repository: https://github.com/livenson/talu

## Overview

Talu is a multitenant VM and managed-Kubernetes platform built on Kubernetes and KubeVirt. Users provision through Git-managed values reconciled by Flux or through Talu’s Kubernetes API: the API projects tenants, VMs, and managed clusters onto Flux HelmReleases, which render the tenancy charts onto the platform substrate. Access, observability, logging, and backup/DR are cross-cutting capabilities. The README documents these broader product branches; source excerpts show API wiring and HelmRelease projections, but not every deployment relationship.

Main entry points: [`components/infrastructure/kubevirt`](https://github.com/livenson/talu/tree/main/components/infrastructure/kubevirt) (KubeVirt Compute), [`apiserver/pkg/server/server.go`](https://github.com/livenson/talu/blob/main/apiserver/pkg/server/server.go) (API Group Wiring), [`components/tenancy/flux`](https://github.com/livenson/talu/tree/main/components/tenancy/flux) (Flux Reconciliation), [`apiserver/pkg/registry/hr/hr.go`](https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/hr/hr.go) (HelmRelease Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Management"]
  node_git["Git Values"]
  node_api["Talu API Server<br/>[main.go]"]
  node_api_types["Tenancy API Types<br/>[types.go]"]
  node_api_wiring["API Group Wiring<br/>[server.go]"]
  node_tenant_store["Tenant Projection<br/>[storage.go]"]
  node_vm_store["VM Projection<br/>[storage.go]"]
  node_cluster_store["Cluster Projection<br/>[storage.go]"]
  node_hr["HelmRelease Helpers<br/>[hr.go]"]
  node_flux["Flux Reconciliation"]
end

subgraph group_tenancy["Tenant Provisioning"]
  node_tenant_chart["Tenant Chart"]
  node_vm_chart["VM Chart"]
  node_cluster_chart["Cluster Chart"]
end

subgraph group_substrate["Compute Substrate"]
  node_platform_components["Platform Services"]
  node_compute["KubeVirt Compute"]
  node_storage[("Ceph Storage")]
end

subgraph group_access["Access Plane"]
  node_access_services["Identity and Ingress"]
  node_portal["Route Portal<br/>[portal.py]"]
end

subgraph group_operations["Operations"]
  node_observability["Metrics and Dashboards"]
  node_logging["Logs and Audit"]
  node_backup["Backup and Restore"]
  node_garage[("Garage S3")]
end

node_operator(("Platform User"))
node_oidc["OIDC Provider"]

node_operator -->|"commits values"| node_git
node_git -->|"reconciles config"| node_flux
node_operator -->|"submits resources"| node_api
node_api -->|"starts server"| node_api_wiring
node_api_wiring -->|"registers storage"| node_tenant_store
node_api_wiring -->|"registers storage"| node_vm_store
node_api_wiring -->|"registers storage"| node_cluster_store
node_api_wiring -->|"registers types"| node_api_types
node_tenant_store -->|"projects releases"| node_hr
node_vm_store -->|"builds releases"| node_hr
node_cluster_store -->|"builds releases"| node_hr
node_hr -->|"creates HelmReleases"| node_flux
node_flux -->|"renders chart"| node_tenant_chart
node_flux -->|"renders chart"| node_vm_chart
node_flux -->|"renders chart"| node_cluster_chart
node_tenant_chart -.->|"provisions VMs"| node_compute
node_vm_chart -.->|"provisions VM"| node_compute
node_cluster_chart -->|"provisions workers"| node_compute
node_compute -->|"uses storage"| node_storage
node_platform_components -->|"includes virtualization"| node_compute
node_operator -->|"authenticates"| node_access_services
node_access_services -->|"uses OIDC"| node_oidc
node_access_services -.->|"exposes routes"| node_portal
node_compute -.->|"exports metrics"| node_observability
node_compute -->|"provides VM logs"| node_logging
node_backup -->|"stores backups"| node_garage

click node_git "https://github.com/livenson/talu/tree/main/environments"
click node_api "https://github.com/livenson/talu/blob/main/apiserver/cmd/talu-apiserver/main.go"
click node_api_types "https://github.com/livenson/talu/blob/main/apiserver/pkg/apis/tenancy/v1alpha1/types.go"
click node_api_wiring "https://github.com/livenson/talu/blob/main/apiserver/pkg/server/server.go"
click node_tenant_store "https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/tenant/storage.go"
click node_vm_store "https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/vm/storage.go"
click node_cluster_store "https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/cluster/storage.go"
click node_hr "https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/hr/hr.go"
click node_flux "https://github.com/livenson/talu/tree/main/components/tenancy/flux"
click node_tenant_chart "https://github.com/livenson/talu/tree/main/components/tenancy/tenant-chart"
click node_vm_chart "https://github.com/livenson/talu/tree/main/components/tenancy/vm-chart"
click node_cluster_chart "https://github.com/livenson/talu/tree/main/components/tenancy/cluster-chart"
click node_platform_components "https://github.com/livenson/talu/tree/main/components/infrastructure"
click node_compute "https://github.com/livenson/talu/tree/main/components/infrastructure/kubevirt"
click node_storage "https://github.com/livenson/talu/tree/main/components/infrastructure/rook-ceph"
click node_access_services "https://github.com/livenson/talu/tree/main/components/platform/identity"
click node_portal "https://github.com/livenson/talu/blob/main/components/platform/portal/portal.py"
click node_observability "https://github.com/livenson/talu/tree/main/components/platform/monitoring"
click node_logging "https://github.com/livenson/talu/tree/main/components/platform/logging"
click node_backup "https://github.com/livenson/talu/tree/main/components/platform/backup"

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_git,node_api,node_api_types,node_api_wiring,node_tenant_store,node_vm_store,node_cluster_store,node_hr,node_flux,node_operator toneBlue
class node_tenant_chart,node_vm_chart,node_cluster_chart toneAmber
class node_platform_components,node_compute,node_storage toneMint
class node_access_services,node_portal toneRose
class node_observability,node_logging,node_backup,node_garage,node_oidc toneIndigo
```

## Components

### Management

- [Git Values](https://github.com/livenson/talu/tree/main/environments): `environments`
- [Talu API Server](https://github.com/livenson/talu/blob/main/apiserver/cmd/talu-apiserver/main.go): `apiserver/cmd/talu-apiserver/main.go`
- [Tenancy API Types](https://github.com/livenson/talu/blob/main/apiserver/pkg/apis/tenancy/v1alpha1/types.go): `apiserver/pkg/apis/tenancy/v1alpha1/types.go`
- [API Group Wiring](https://github.com/livenson/talu/blob/main/apiserver/pkg/server/server.go): `apiserver/pkg/server/server.go`
- [Tenant Projection](https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/tenant/storage.go): `apiserver/pkg/registry/tenant/storage.go`
- [VM Projection](https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/vm/storage.go): `apiserver/pkg/registry/vm/storage.go`
- [Cluster Projection](https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/cluster/storage.go): `apiserver/pkg/registry/cluster/storage.go`
- [HelmRelease Helpers](https://github.com/livenson/talu/blob/main/apiserver/pkg/registry/hr/hr.go): `apiserver/pkg/registry/hr/hr.go`
- [Flux Reconciliation](https://github.com/livenson/talu/tree/main/components/tenancy/flux): `components/tenancy/flux`

### Tenant Provisioning

- [Tenant Chart](https://github.com/livenson/talu/tree/main/components/tenancy/tenant-chart): `components/tenancy/tenant-chart`
- [VM Chart](https://github.com/livenson/talu/tree/main/components/tenancy/vm-chart): `components/tenancy/vm-chart`
- [Cluster Chart](https://github.com/livenson/talu/tree/main/components/tenancy/cluster-chart): `components/tenancy/cluster-chart`

### Compute Substrate

- [Platform Services](https://github.com/livenson/talu/tree/main/components/infrastructure): `components/infrastructure`
- [KubeVirt Compute](https://github.com/livenson/talu/tree/main/components/infrastructure/kubevirt): `components/infrastructure/kubevirt`
- [Ceph Storage](https://github.com/livenson/talu/tree/main/components/infrastructure/rook-ceph): `components/infrastructure/rook-ceph`

### Access Plane

- [Identity and Ingress](https://github.com/livenson/talu/tree/main/components/platform/identity): `components/platform/identity`
- [Route Portal](https://github.com/livenson/talu/blob/main/components/platform/portal/portal.py): `components/platform/portal/portal.py`

### Operations

- [Metrics and Dashboards](https://github.com/livenson/talu/tree/main/components/platform/monitoring): `components/platform/monitoring`
- [Logs and Audit](https://github.com/livenson/talu/tree/main/components/platform/logging): `components/platform/logging`
- [Backup and Restore](https://github.com/livenson/talu/tree/main/components/platform/backup): `components/platform/backup`
- **Garage S3**

### Other components

- **Platform User**
- **OIDC Provider**

## Connections

- Platform User → Git Values: commits values (evidence: `README.md`)
- Git Values → Flux Reconciliation: reconciles config (evidence: `README.md`)
- Platform User → Talu API Server: submits resources (evidence: `README.md`)
- Talu API Server → API Group Wiring: starts server (evidence: `apiserver/cmd/talu-apiserver/main.go`)
- API Group Wiring → Tenant Projection: registers storage (evidence: `apiserver/pkg/server/server.go`)
- API Group Wiring → VM Projection: registers storage (evidence: `apiserver/pkg/server/server.go`)
- API Group Wiring → Cluster Projection: registers storage (evidence: `apiserver/pkg/server/server.go`)
- API Group Wiring → Tenancy API Types: registers types (evidence: `apiserver/pkg/server/server.go`)
- Tenant Projection → HelmRelease Helpers: projects releases (evidence: `apiserver/pkg/registry/tenant/storage.go`)
- VM Projection → HelmRelease Helpers: builds releases (evidence: `apiserver/pkg/registry/vm/storage.go`)
- Cluster Projection → HelmRelease Helpers: builds releases (evidence: `apiserver/pkg/registry/cluster/storage.go`)
- HelmRelease Helpers → Flux Reconciliation: creates HelmReleases (evidence: `apiserver/pkg/registry/hr/hr.go`)
- Flux Reconciliation → Tenant Chart: renders chart (evidence: `README.md`)
- Flux Reconciliation → VM Chart: renders chart (evidence: `README.md`)
- Flux Reconciliation → Cluster Chart: renders chart (evidence: `README.md`)
- Tenant Chart → KubeVirt Compute: provisions VMs (evidence: `README.md`)
- VM Chart → KubeVirt Compute: provisions VM (evidence: `README.md`)
- Cluster Chart → KubeVirt Compute: provisions workers (evidence: `README.md`)
- KubeVirt Compute → Ceph Storage: uses storage (evidence: `README.md`)
- Platform Services → KubeVirt Compute: includes virtualization (evidence: `README.md`)
- Platform User → Identity and Ingress: authenticates (evidence: `README.md`)
- Identity and Ingress → OIDC Provider: uses OIDC (evidence: `README.md`)
- Identity and Ingress → Route Portal: exposes routes (evidence: `components/platform/portal/portal.py`)
- KubeVirt Compute → Metrics and Dashboards: exports metrics (evidence: `README.md`)
- KubeVirt Compute → Logs and Audit: provides VM logs (evidence: `README.md`)
- Backup and Restore → Garage S3: stores backups (evidence: `README.md`)
