# fuzzylabs/matcha architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzylabs/matcha
- Repository: https://github.com/fuzzylabs/matcha

## Overview

##### Project type and purpose
- Matcha is an open-source Python CLI tool for one-step MLOps provisioning on Azure.
- Its purpose is to let data scientists and ML engineers provision an end-to-end ML infrastructure (experiment tracking, model training, deployment) using Terraform, ZenML, and Azure services.

##### File structure
- Top-level:
- src/matcha_ml: the Python package
- tests: unit tests
- docs: MkDocs-based documentation
- .github, CI/CD workflows, pre-commit, linters
- src/matcha_ml/cli: command-line interface and UI logic
- src/matcha_ml/core: core orchestration and validation
- src/matcha_ml/config: matcha_config parsing and defaults
- src/matcha_ml/services: abstractions around Terraform, Azure, analytics
- src/matcha_ml/runners: execution layers for local/remote/azure runs
- src/matcha_ml/templates: Terraform template generators
- src/matcha_ml/infrastructure: pre-packaged Terraform modules for different “stacks” – default (MLflow, AKS, ACR, storage, Seldon, ZenML), llm (Chroma, LLM stack), remote_state_storage
- src/matcha_ml/state & storage: state handling (remote/local) and Azure storage wrappers

##### README for additional insights
- Confirms MLOps stack includes experiment tracking, training, deployment
- References ZenML for stack recipes and various Azure permission requirements

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane"
        direction TB
        U["User"]:::external
        CLI["Matcha CLI"]:::python
        Config["Configuration Loader\n(matcha_config.py)"]:::python
        Core["Core Engine"]:::python

        subgraph "Service Layer"
            direction TB
            TerraformService["TerraformService"]:::python
            AzureService["AzureService"]:::python
            AnalyticsService["AnalyticsService"]:::python
        end

        subgraph "Runner Layer"
            direction TB
            BaseRunner["BaseRunner"]:::python
            AzureRunner["AzureRunner"]:::python
            RemoteStateRunner["RemoteStateRunner"]:::python
        end

        subgraph "Template Engine"
            direction TB
            BaseTemplate["BaseTemplate"]:::python
            AzureTemplate["AzureTemplate"]:::python
            RemoteStateTemplate["RemoteStateTemplate"]:::python
        end

        StateModel["Matcha State Model"]:::python
        RemoteStateMgr["RemoteStateManager"]:::python
        AzureStorage["AzureStorage"]:::python
    end

    %% Terraform Modules
    subgraph "Terraform Modules"
        direction TB
        DefaultMod["Default ML Stack"]:::tfModule
        LLMMod["LLM Stack"]:::tfModule
        RemoteStateMod["Remote State Storage"]:::tfModule
    end

    %% Data Plane (Azure Infra)
    subgraph "Data Plane (Azure Infra)"
        direction TB
        subgraph "Resource Group"
            direction TB
            ACR["Azure Container Registry"]:::azure
            AKS["Azure Kubernetes Service"]:::azure
            StorageAcc["Blob/Data Storage"]:::storage
            MLflow["MLflow Server"]:::azure
            Seldon["Seldon Core"]:::azure
            ZenML["ZenML Server & Storage"]:::azure
            Chroma["Chroma (LLM)"]:::azure
            RemoteStateStorage["Remote State Storage"]:::storage
        end
    end

    %% Connections
    U --> CLI
    CLI --> Config
    CLI --> Core

    Core --> TerraformService
    Core --> AzureService
    Core --> AnalyticsService
    Core --> StateModel

    TerraformService --> DefaultMod
    TerraformService --> LLMMod
    TerraformService --> RemoteStateMod

    DefaultMod --> ACR
    DefaultMod --> AKS
    DefaultMod --> StorageAcc
    DefaultMod --> MLflow
    DefaultMod --> Seldon
    DefaultMod --> ZenML

    LLMMod --> Chroma
    RemoteStateMod --> RemoteStateStorage

    Core --> BaseRunner
    BaseRunner --> AzureRunner
    BaseRunner --> RemoteStateRunner

    AzureRunner --> DefaultMod
    AzureRunner --> LLMMod
    AzureRunner --> RemoteStateMod

    StateModel --> AzureStorage
    StateModel --> RemoteStateMgr
    RemoteStateMgr --> RemoteStateStorage

    %% Click Events
    click CLI "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/cli/cli.py"
    click CLI "https://github.com/fuzzylabs/matcha/tree/develop/src/matcha_ml/cli"
    click Config "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/config/matcha_config.py"
    click Core "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/core/core.py"
    click TerraformService "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/services/terraform_service.py"
    click AzureService "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/services/azure_service.py"
    click AnalyticsService "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/services/analytics_service.py"
    click BaseRunner "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/runners/base_runner.py"
    click AzureRunner "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/runners/azure_runner.py"
    click RemoteStateRunner "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/runners/remote_state_runner.py"
    click BaseTemplate "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/templates/base_template.py"
    click AzureTemplate "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/templates/azure_template.py"
    click RemoteStateTemplate "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/templates/remote_state_template.py"
    click DefaultMod "https://github.com/fuzzylabs/matcha/tree/develop/src/matcha_ml/infrastructure/default"
    click LLMMod "https://github.com/fuzzylabs/matcha/tree/develop/src/matcha_ml/infrastructure/llm"
    click RemoteStateMod "https://github.com/fuzzylabs/matcha/tree/develop/src/matcha_ml/infrastructure/remote_state_storage"
    click StateModel "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/state/matcha_state.py"
    click RemoteStateMgr "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/state/remote_state_manager.py"
    click AzureStorage "https://github.com/fuzzylabs/matcha/blob/develop/src/matcha_ml/storage/azure_storage.py"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef azure fill:#E0FFE0,stroke:#333,stroke-width:1px
    classDef storage fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef tfModule fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
