# starburstdata/metabase-driver architecture

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

- Interactive diagram: https://gitdiagram.com/starburstdata/metabase-driver
- Repository: https://github.com/starburstdata/metabase-driver

## Overview

##### Main Components
- Driver Plugin Module: Highlight the drivers/starburst directory as the core of the plugin. This includes source code (Clojure files under src), driver implementations, and tests.
- Build & Automation System:
- The Makefile that manages cloning the Metabase repository, copying driver files, building the .jar, and starting the local server.
- GitHub Actions workflows (found under .github) which encapsulate CI checks, release branch creation, release artifact building, and dependency management.
- External Dependencies:
- The Metabase Repository: Depicted as an external system that this project interacts with (via cloning & integration into the Metabase modules directory).
- Dockerized Trino Server: Used during testing where a Docker container (from resources/docker/trino) is used to simulate/expose a Trino server, essential for validating connectivity and data population into test catalogs.
- Testing Environment: Components that include local server start-up (Makefile targets for server and test) and specific test directories (test directories under drivers/starburst/test).

##### Relationships and Interactions
- Build Process Flow: Illustrate the steps where “make build” first clones the Metabase repo, then copies the Starburst driver files into the appropriate Metabase modules directory. This subsystem then triggers the build scripts provided in the Metabase repo to compile and package the .jar.
- Plugin Integration: Represent the final .jar file that must be placed in the Metabase plugins directory. This signals the separation of concerns: the Starburst driver, once built and tested, acts as a plug-in that extends Metabase’s functionality.

##### Key Architectural Patterns and Design Principles
- Plugin Architecture: The driver is designed as a plug-in which adheres to Metabase’s driver API, so clearly segmenting the driver code from the main platform (Metabase) is essential.
- Modular Build & Test Strategy: Show how the Makefile serves as an orchestrator for different stages (build, server startup, tests) and how CI/CD workflows (via GitHub Actions) integrate continuous validation and release management.
- Dependency Management: Illustrate the version file (app_versions.json) and the use of dependency files (e.g., deps.edn) which are instrumental in ensuring reproducible builds.

##### Elements
- Components clearly labeled “Driver Plugin (Starburst)”, “Metabase Repository”, “Makefile Build Process”, “CI/CD Workflows (GitHub Actions)”, “Docker – Trino Server”, and “Test Suite”.
- Codebase components (driver source, tests)
- Automation components (Makefile, GitHub workflows)
- External systems (Metabase core application, Dockerized servers)
- Actions such as “Build”, “Test”, “Deploy/Release”, and “Plugin Integration” at the relevant parts of the workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Automation Subgraph
    subgraph "Build & Automation"
        A1("Makefile Build Process"):::automation
        A2("GitHub Actions Workflows"):::automation
    end

    %% Driver Plugin Subgraph
    subgraph "Driver Plugin (Starburst)"
        B("Driver Plugin (Starburst)"):::driver
        B1("Source Code"):::driver
        B2("Test Suite"):::driver
    end

    %% Dependency Management Subgraph
    subgraph "Dependency Management"
        C1("deps.edn"):::dep
        C2("app_versions.json"):::dep
    end

    %% Testing Environment Subgraph
    subgraph "Testing Environment"
        D1("Local Metabase Server (Port3000)"):::test
        D2("Dockerized Trino Server"):::test
    end

    %% Release and Integration
    E("Release Artifact (.jar Plugin)"):::driver
    F("Metabase Application"):::external

    %% Connections from Build & Automation to Driver Plugin
    A1 -->|"clone/copy/build"| B
    A2 -->|"CI/CD-workflows"| B

    %% Connections from Build & Automation to Dependency Management
    A1 -->|"manage-deps"| C1
    A1 -->|"manage-deps"| C2

    %% Connections for Testing
    A1 -->|"trigger-test"| D1
    A1 -->|"trigger-test"| D2
    B2 -->|"execute-tests"| D1
    B2 -->|"execute-tests"| D2

    %% Build Process to Release Artifact
    B -->|"compile-package"| E
    A2 -->|"release-workflow"| E

    %% Plugin Integration into Metabase
    E -->|"integrate-plugin"| F

    %% Click Events
    click A1 "https://github.com/starburstdata/metabase-driver/tree/main/Makefile"
    click A2 "https://github.com/starburstdata/metabase-driver/blob/main/.github"
    click B "https://github.com/starburstdata/metabase-driver/tree/main/drivers/starburst"
    click B1 "https://github.com/starburstdata/metabase-driver/tree/main/drivers/starburst/src"
    click B2 "https://github.com/starburstdata/metabase-driver/tree/main/drivers/starburst/test"
    click C1 "https://github.com/starburstdata/metabase-driver/blob/main/drivers/starburst/deps.edn"
    click C2 "https://github.com/starburstdata/metabase-driver/blob/main/app_versions.json"
    click D2 "https://github.com/starburstdata/metabase-driver/tree/main/resources/docker/trino"

    %% Styles
    classDef automation fill:#88c0d0,stroke:#2e3440,stroke-width:2px;
    classDef driver fill:#a3be8c,stroke:#2e3440,stroke-width:2px;
    classDef external fill:#ebcb8b,stroke:#2e3440,stroke-width:2px;
    classDef test fill:#bf616a,stroke:#2e3440,stroke-width:2px;
    classDef dep fill:#d08770,stroke:#2e3440,stroke-width:2px;
```
