# negashev/aldaas architecture

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

- Interactive diagram: https://gitdiagram.com/negashev/aldaas
- Repository: https://github.com/negashev/aldaas

## Overview

##### Project type and purpose
- This is an event-driven Kubernetes application (“App with Large Data as a Service”) that automates provisioning of ephemeral, production-like database clones for developers and CI/CD pipelines. It uses Rook/Ceph snapshots, Argo Events, and Argo Workflows under a Helm chart, and is deployed via Rancher Fleet.

##### File-structure analysis
- `.github/workflows`: CI to build & publish the `tunnel` Docker image.
- `chart/`: Helm chart defining Kubernetes resources (ConfigMaps, CronJobs, Argo Sensors/Sources, RBAC, EventBus, Workflows, Secrets).
- `fleet/`: Rancher Fleet GitOps manifests for deploying Argo Events, Argo Workflows, Ceph (Rook), and monitoring.
- `tunnel/`: Light client image (Dockerfile + `aldaas.sh`) acting as a proxy between user CLI and the Argo control plane.

##### Key architectural insights from the README
- Core components: Rook-Ceph with VolumeSnapshots, Argo Events (with webhook), Argo Workflows, Helm-deployed control-plane, and a lightweight client proxy.
- The user leverages `aldaas.sh` + `argo` CLI to trigger snapshot workflows and bind ephemeral database credentials.

##### Main components
a. Developer / CI/CD client
b. aldaas tunnel (Docker container)
c. Argo Events:
- EventSource (webhook listener)
- EventBus
- Sensor (triggers on events)
d. Argo Workflow Controller & Server
e. Rook-Ceph storage cluster (VolumeSnapshotClass & snapshots)
f. Kubernetes cluster (namespaces, PVCs, ephemeral database Pods)
g. Rancher Fleet (GitOps: deployments of Argo, Ceph, monitoring)
h. Helm chart (defines all control-plane resources)

##### Interactions and data flows
1. Client runs `aldaas.sh` → sends HTTP event to Argo EventSource (via webhook ingress).
2. EventSource publishes to EventBus.
3. Sensor watches EventBus → spawns an Argo Workflow.
4. Workflow steps:
ii. Create a new PVC from that snapshot
iii. Deploy a temporary database Pod bound to the PVC
iv. Generate connection credentials & expose a Service
5. Tunnel proxy forwards client’s DB traffic to the ephemeral Service.
6. (Optionally) CronJob from Helm chart cleans up unused snapshots & PVCs.

##### Architectural patterns & design principles
- Event-driven, declarative control-plane on Kubernetes.
- Separation of concerns:
- Control plane (Helm chart + Fleet)
- Data plane (Rook/Ceph, PVCs, DB Pods)
- Client plane (tunnel, CLI)
- GitOps deployment (Rancher Fleet) for infra consistency.
- Reuse of Kubernetes primitives (CustomResources, VolumeSnapshots, CronJobs).

##### Essential elements
- Event flow: Client → EventSource → EventBus → Sensor → Workflow
- Workflow steps hitting the CSI driver & creating DB pods
- Tunnel proxy layer connecting client to ephemeral DB Service
- GitOps loop: Fleet applies `fleet/` manifests
- Helm chart role: templating all Kubernetes control-plane resources

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Plane
    subgraph "Client Plane" 
        direction TB
        DevCI["Developer / CI/CD Client"]:::client
        Tunnel["aldaas Tunnel Proxy"]:::client
    end

    %% Control Plane
    subgraph "Control Plane (Kubernetes)" 
        direction TB
        subgraph "Helm Chart" 
            direction TB
            Chart["Chart Resources"]:::helm
        end
        subgraph "Argo Events" 
            direction TB
            ES["EventSource (webhook listener)"]:::argo
            EB["EventBus"]:::argo
            Sensor["Sensor"]:::argo
        end
        subgraph "Argo Workflows" 
            direction TB
            WFController["Workflow Controller & Server"]:::argo
        end
        subgraph "Cleanup" 
            direction TB
            Cron["Cleanup CronJob"]:::cron
        end
    end

    %% Data Plane
    subgraph "Data Plane" 
        direction TB
        Ceph["Rook-Ceph Storage Cluster"]:::storage
        Snapshot["VolumeSnapshot CSI"]:::storage
        PVC["PVC & Ephemeral DB Pod"]:::k8s
        DBService["Ephemeral DB Service"]:::k8s
    end

    %% GitOps Plane
    subgraph "GitOps Plane" 
        direction TB
        Fleet["Rancher Fleet (GitOps)"]:::gitops
    end

    %% Interactions
    DevCI -->|"HTTP Event"| ES
    ES -->|"publish event"| EB
    EB -->|"trigger"| Sensor
    Sensor -->|"start workflow"| WFController
    WFController -->|"snapshot"| Snapshot
    Snapshot --> PVC
    PVC --> DBService
    DevCI -->|"DB Traffic through tunnel"| Tunnel
    Tunnel --> DBService
    Cron -->|"cleanup snapshots/PVCs"| Snapshot
    Fleet -->|"applies manifests"| Chart
    Fleet -->|"applies manifests"| ES
    Fleet -->|"applies manifests"| Sensor
    Fleet -->|"applies manifests"| EB
    Fleet -->|"applies manifests"| WFController
    Fleet -->|"applies manifests"| Ceph

    %% Click Events
    click DevCI "https://github.com/negashev/aldaas/blob/main/.github/workflows/docker-publish.yml"
    click Tunnel "https://github.com/negashev/aldaas/tree/main/tunnel/Dockerfile"
    click Tunnel "https://github.com/negashev/aldaas/blob/main/tunnel/aldaas.sh"
    click Chart "https://github.com/negashev/aldaas/blob/main/chart/Chart.yaml"
    click Chart "https://github.com/negashev/aldaas/blob/main/chart/values.yaml"
    click Chart "https://github.com/negashev/aldaas/tree/main/chart/templates/"
    click ES "https://github.com/negashev/aldaas/blob/main/chart/templates/create-event-source.yaml"
    click ES "https://github.com/negashev/aldaas/blob/main/chart/templates/remove-event-source.yaml"
    click ES "https://github.com/negashev/aldaas/blob/main/fleet/argo/events/fleet.yaml"
    click EB "https://github.com/negashev/aldaas/blob/main/chart/templates/event-bus.yaml"
    click Sensor "https://github.com/negashev/aldaas/blob/main/chart/templates/create-event-sensor.yaml"
    click Sensor "https://github.com/negashev/aldaas/blob/main/chart/templates/remove-event-sensor.yaml"
    click Sensor "https://github.com/negashev/aldaas/blob/main/fleet/argo/events/fleet.yaml"
    click WFController "https://github.com/negashev/aldaas/blob/main/chart/templates/generator-application.yaml"
    click WFController "https://github.com/negashev/aldaas/blob/main/fleet/argo/workflow/fleet.yaml"
    click WFController "https://github.com/negashev/aldaas/blob/main/fleet/argo/workflow/service-account/auth.yaml"
    click WFController "https://github.com/negashev/aldaas/blob/main/fleet/argo/workflow/service-account/fleet.yaml"
    click Ceph "https://github.com/negashev/aldaas/blob/main/fleet/rook/fleet.yaml"
    click Ceph "https://github.com/negashev/aldaas/blob/main/fleet/ceph/fleet.yaml"
    click Cron "https://github.com/negashev/aldaas/blob/main/chart/templates/cleanup-cron.yaml"
    click Cron "https://github.com/negashev/aldaas/blob/main/chart/templates/cleanup-config-map.yaml"
    click Fleet "https://github.com/negashev/aldaas/tree/main/fleet/"

    %% Styles
    classDef client fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef helm fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef argo fill:#87cefa,stroke:#333,stroke-width:1px
    classDef cron fill:#ffa500,stroke:#333,stroke-width:1px
    classDef storage fill:#98fb98,stroke:#333,stroke-width:1px
    classDef k8s fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef gitops fill:#ffb6c1,stroke:#333,stroke-width:1px
```
