# padok-team/burrito architecture

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

- Interactive diagram: https://gitdiagram.com/padok-team/burrito
- Repository: https://github.com/padok-team/burrito

## Overview

##### Project type and purpose
- Burrito is a Kubernetes Operator (written in Go) plus a companion React Web UI—i.e., a full‑stack cloud‑native application.
- It implements custom Terraform orchestration via Kubernetes CRDs (TerraformLayer, TerraformPullRequest, TerraformRepository, TerraformRun), controller loops (cmd/controllers), runner agents (cmd/runner), an API server (cmd/server), and a Web UI (ui/).
- It integrates with Git providers (GitHub and GitLab) to watch push and pull/merge events, plan/apply Terraform code, detect drift, and display diffs in a UI.

##### File‑structure analysis
- Top level:
- cmd/… – entrypoints for controllers, datastore, runner, server.
- api/v1alpha1 – definitions of Burrito CRDs (TerraformLayer, TerraformPullRequest, TerraformRepository, TerraformRun).
- internal/… – business‑logic: controllers, datastore storage clients (S3, GCS, Azure), runner tools (Terraform, Terragrunt, OpenTofu), webhook handlers, Git provider abstractions, server handlers, locking, sync windows, etc.
- ui/ – React SPA consuming the Burrito API.
- deploy/ & manifests/ – Helm chart and Kustomize manifests for Kubernetes deployment.

##### Key architecture points from README & docs
- Burrito uses the Operator pattern: CRDs + controller loops drive state in Kubernetes.
- The API server exposes REST endpoints for UI and external clients.
- The runner component executes Terraform operations in pods.
- A pluggable datastore persists plans, logs, state diffs.
- Git provider module abstracts GitHub and GitLab webhook events and API calls.

a. Main components:
1. Kubernetes cluster (control plane).
2. Custom Resources (CRDs):
- TerraformLayer
- TerraformPullRequest
- TerraformRepository
- TerraformRun
3. Controller Manager (cmd/controllers): watches CRDs, reconciles state.
4. Runner Pods (cmd/runner): perform terraform plan/apply.
5. Datastore Service (cmd/datastore + storage backends): stores plans, logs, revisions.
6. API Server (cmd/server): serves UI and CLI clients.
7. Webhook Listener (internal/webhook): ingests GitHub/GitLab events.
8. Git Providers (GitHub, GitLab)—external systems.
9. React Web UI (ui/): user front end.

b. Relationships & data‑flow:
- GitHub/GitLab → Webhook Listener → CRD instances (TerraformPullRequest & TerraformRepository).
- Controller Manager watches CRDs → creates / updates Runner Pods & TerraformLayer/Run resources.
- Runner Pods execute Terraform via integrated tools → send logs/results to Datastore.
- Controller Manager updates TerraformRun CRDs with status & diff results.
- API Server reads CRDs & Datastore → exposes REST API.
- Web UI calls API Server → displays state, diffs, run history.

c. Architectural patterns/design principles:
- Kubernetes Operator pattern (CRD + controller loops).
- Event‑driven reconciliation (Git webhooks & Kubernetes events).
- Micro‑services-like separation: controller, runner, datastore, API, UI.
- Pluggable abstractions for storage backends and Git providers.

d. Key technologies / frameworks:
- Go & controller-runtime (Operator SDK)
- Kubernetes CRDs & Helm/Kustomize for deployment
- React, Vite, Tailwind CSS for UI
- Storage backends: AWS S3, GCS, Azure Blob (internal/datastore/storage)
- Git provider integrations: internal/utils/gitprovider/{github,gitlab}

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Git Providers
    subgraph "Git Providers" 
        direction TB
        GitHub(("GitHub")):::external
        GitLab(("GitLab")):::external
    end

    %% Webhook Listener
    WebhookListener["Webhook Listener"]:::service

    %% Custom Resources
    subgraph "Custom Resources (CRDs)" 
        direction TB
        TFLayer["TerraformLayer"]:::k8s
        TFPR["TerraformPullRequest"]:::k8s
        TFRepo["TerraformRepository"]:::k8s
        TFRun["TerraformRun"]:::k8s
    end

    %% Controller and Runner
    ControllerManager["Controller Manager"]:::k8s
    RunnerPods["Runner Pods"]:::k8s

    %% Datastore and API
    DatastoreService["Datastore Service"]:::service
    APIServer["API Server"]:::service

    %% Frontend
    ReactUI["React Web UI"]:::frontend

    %% Deployment
    Deployment["Helm/Kustomize Deployment"]:::infra

    %% Connections
    GitHub -->|HTTP/Webhook| WebhookListener
    GitLab -->|HTTP/Webhook| WebhookListener

    WebhookListener -->|K8s API calls| TFPR
    WebhookListener -->|K8s API calls| TFRepo

    TFLayer <-->|controller-runtime| ControllerManager
    TFPR <-->|controller-runtime| ControllerManager
    TFRepo <-->|controller-runtime| ControllerManager
    TFRun <-->|controller-runtime| ControllerManager

    ControllerManager -->|creates pods| RunnerPods
    RunnerPods -->|Terraform CLI| DatastoreService

    ControllerManager -->|updates status| TFRun

    APIServer -->|reads CRDs| TFLayer
    APIServer -->|reads CRDs| TFPR
    APIServer -->|reads CRDs| TFRepo
    APIServer -->|reads CRDs| TFRun
    APIServer -->|storage API| DatastoreService

    ReactUI -->|REST/HTTPS| APIServer

    Deployment -->|deploys| ControllerManager
    Deployment -->|deploys| RunnerPods
    Deployment -->|deploys| APIServer

    %% Click Events
    click TFLayer "https://github.com/padok-team/burrito/blob/main/api/v1alpha1/terraformlayer_types.go"
    click TFPR "https://github.com/padok-team/burrito/blob/main/api/v1alpha1/terraformpullrequest_types.go"
    click TFRepo "https://github.com/padok-team/burrito/blob/main/api/v1alpha1/terraformrepository_types.go"
    click TFRun "https://github.com/padok-team/burrito/blob/main/api/v1alpha1/terraformrun_types.go"
    click ControllerManager "https://github.com/padok-team/burrito/tree/main/cmd/controllers"
    click WebhookListener "https://github.com/padok-team/burrito/blob/main/internal/webhook/webhook.go"
    click RunnerPods "https://github.com/padok-team/burrito/tree/main/cmd/runner"
    click DatastoreService "https://github.com/padok-team/burrito/tree/main/cmd/datastore"
    click APIServer "https://github.com/padok-team/burrito/tree/main/cmd/server"
    click ReactUI "https://github.com/padok-team/burrito/tree/main/ui"
    click Deployment "https://github.com/padok-team/burrito/tree/main/deploy/charts/burrito"

    %% Styles
    classDef k8s fill:#dafadf,stroke:#2f7d32,stroke-width:2px
    classDef service fill:#d0e7ff,stroke:#1a73e8,stroke-width:2px
    classDef external fill:#e0e0e0,stroke:#616161,stroke-width:2px
    classDef frontend fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef infra fill:#f5f5f5,stroke:#9e9e9e,stroke-width:2px
```
