# bryson-tai/general_utilities architecture

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

- Interactive diagram: https://gitdiagram.com/bryson-tai/general_utilities
- Repository: https://github.com/bryson-tai/general_utilities

## Overview

##### Project type and purpose
- This is an infrastructure-as-code repository whose primary goal is to provision and deploy a Kubernetes environment (both locally via Minikube and remotely on Azure AKS).
- It uses Taskfiles for orchestration, Helm for templating and packaging, raw Kubernetes manifests for configuration, and OpenTofu (a Terraform-compatible tool) for Azure resource provisioning.

##### File structure
- Top level:
- Taskfiles/ — orchestration scripts (kubernetes.yaml, minikube.yaml)
- helm/nginx/ — a Helm chart with Chart.yaml, values.yaml, and templates (configmap, deployment, service)
- kubernetes/nginx/ — raw Kubernetes YAML files for nginx (configmap, deployment, service)
- opentofu/azure/kubernetes/ — Terraform-style files (.tf) to provision Azure resources (AKS cluster, variables, environment examples)
- Patterns:
- “Taskfiles” drives the workflows for both local (Minikube) and remote (Azure) setups.
- Separate directories for templated (helm) vs. declarative (raw kubectl) deployments.
- A Terraform-style IaC module under opentofu for cloud provisioning.

##### README for additional insights
- It confirms that tasks chain across local and remote targets, invoking Minikube startup or Azure provisioning before issuing kubectl/helm commands.

##### Main components & their relationships
a. Developer workstation (CLI)
b. Taskfiles orchestrator
c. External Taskfile includes (e.g., general_utilities.git)
d. Local Kubernetes cluster (Minikube)
e. Remote Kubernetes cluster (Azure AKS)
f. OpenTofu module for Azure resource provisioning
g. Helm chart for nginx
h. Raw Kubernetes manifests for nginx
i. Kubernetes API (kubectl)

Relationships & data flow:
- Developer invokes Taskfile on CLI → Taskfiles parse includes and dependencies
- For local: Taskfile calls Minikube start → yields kubeconfig → Taskfile runs helm install or kubectl apply against Minikube
- For remote: Taskfile calls OpenTofu apply → provisions AKS cluster → fetches kubeconfig → Taskfile runs helm install or kubectl apply against AKS
- Helm chart and raw manifests create ConfigMaps, Deployments, Services in the cluster

##### Architectural patterns & design principles
- Modular orchestration: Taskfiles separate concerns into tasks for provisioning vs. deployment vs. testing.
- Infrastructure as code: OpenTofu for cloud provisioning, raw YAML and Helm for in-cluster resources.
- Reuse via “includes”: ability to pull in common Taskfiles from external repos.
- Environments segregation: Local (Minikube) vs. Remote (Azure AKS) workflows.

##### Technologies and frameworks
- Taskfile (Go-based Task runner)
- Helm (Kubernetes package manager)
- Kubernetes (Minikube locally, AKS remotely)
- OpenTofu (Terraform-compatible IaC for Azure)
- Azure provider (AKS resources, variables.tf)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    DCLI["Developer Workstation (CLI)"]:::external
    ExternalIncludes["External Taskfile Includes"]:::external

    %% Orchestration Layer
    subgraph "Orchestration (Blue)"
        direction TB
        TaskKube["Taskfiles/kubernetes.yaml"]:::orchestration
        TaskMini["Taskfiles/minikube.yaml"]:::orchestration
    end

    %% Provisioning Layer
    subgraph "Provisioning (Green)"
        direction TB
        OT1["main.tf"]:::provisioning
        OT2["opentofu.tf"]:::provisioning
        OT3["variables.tf"]:::provisioning
        OT4[".env.example"]:::provisioning
        OpenTofuModule["OpenTofu Module"]:::provisioning
        OT1 --> OpenTofuModule
        OT2 --> OpenTofuModule
        OT3 --> OpenTofuModule
        OT4 --> OpenTofuModule
    end
    AzureAKS["Azure AKS"]:::cloud
    Minikube["Minikube Cluster"]:::cloud

    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        subgraph "Helm Chart (nginx)" 
            direction TB
            ChartY["Chart.yaml"]:::templating
            Values["values.yaml"]:::templating
            CMtpl["templates/configmap.yaml"]:::templating
            DeplT["templates/deployment.yaml"]:::templating
            ServiceT["templates/service.yaml"]:::templating
        end
        subgraph "Raw Manifests (nginx)"
            direction TB
            RawConfig["configmap.yaml"]:::raw
            RawDepl["deployment.yaml"]:::raw
            RawSvc["service.yaml"]:::raw
        end
        KubernetesAPI["Kubernetes API Server"]:::api
    end

    %% Flow Arrows
    DCLI -->|"invoke"| TaskKube
    DCLI -->|"invoke"| TaskMini
    TaskKube --> ExternalIncludes
    TaskMini --> ExternalIncludes

    %% Local Flow
    TaskMini -->|"start cluster"| Minikube
    TaskMini -->|"deploy"| ChartY
    TaskMini -->|"deploy"| RawConfig
    TaskMini -->|"deploy"| RawDepl
    TaskMini -->|"deploy"| RawSvc

    %% Remote Flow
    TaskKube -->|"provision"| OpenTofuModule
    OpenTofuModule --> AzureAKS
    TaskKube -->|"deploy"| ChartY
    TaskKube -->|"deploy"| RawConfig
    TaskKube -->|"deploy"| RawDepl
    TaskKube -->|"deploy"| RawSvc

    %% Deployment to API
    ChartY --> KubernetesAPI
    Values --> KubernetesAPI
    CMtpl --> KubernetesAPI
    DeplT --> KubernetesAPI
    ServiceT --> KubernetesAPI
    RawConfig --> KubernetesAPI
    RawDepl --> KubernetesAPI
    RawSvc --> KubernetesAPI

    %% Click Events
    click DCLI "https://github.com/bryson-tai/general_utilities/blob/main/README.md"
    click TaskKube "https://github.com/bryson-tai/general_utilities/blob/main/Taskfiles/kubernetes.yaml"
    click TaskMini "https://github.com/bryson-tai/general_utilities/blob/main/Taskfiles/minikube.yaml"
    click OT1 "https://github.com/bryson-tai/general_utilities/blob/main/opentofu/azure/kubernetes/main.tf"
    click OT2 "https://github.com/bryson-tai/general_utilities/blob/main/opentofu/azure/kubernetes/opentofu.tf"
    click OT3 "https://github.com/bryson-tai/general_utilities/blob/main/opentofu/azure/kubernetes/variables.tf"
    click OT4 "https://github.com/bryson-tai/general_utilities/blob/main/opentofu/azure/kubernetes/.env.example"
    click ChartY "https://github.com/bryson-tai/general_utilities/blob/main/helm/nginx/Chart.yaml"
    click Values "https://github.com/bryson-tai/general_utilities/blob/main/helm/nginx/values.yaml"
    click CMtpl "https://github.com/bryson-tai/general_utilities/blob/main/helm/nginx/templates/configmap.yaml"
    click DeplT "https://github.com/bryson-tai/general_utilities/blob/main/helm/nginx/templates/deployment.yaml"
    click ServiceT "https://github.com/bryson-tai/general_utilities/blob/main/helm/nginx/templates/service.yaml"
    click RawConfig "https://github.com/bryson-tai/general_utilities/blob/main/kubernetes/nginx/configmap.yaml"
    click RawDepl "https://github.com/bryson-tai/general_utilities/blob/main/kubernetes/nginx/deployment.yaml"
    click RawSvc "https://github.com/bryson-tai/general_utilities/blob/main/kubernetes/nginx/service.yaml"

    %% Styles
    classDef orchestration fill:#ADD8E6,stroke:#000;
    classDef provisioning fill:#90EE90,stroke:#000;
    classDef templating fill:#FFA500,stroke:#000;
    classDef raw fill:#DDA0DD,stroke:#000;
    classDef cloud fill:#E0E0E0,stroke:#000,stroke-dasharray: 5 5;
    classDef api fill:#FFD700,stroke:#000;
    classDef external fill:#F2F2F2,stroke:#000,stroke-dasharray: 2 2;
```
