# civicdatalab/bma-dashboard-superset architecture

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

- Interactive diagram: https://gitdiagram.com/civicdatalab/bma-dashboard-superset
- Repository: https://github.com/civicdatalab/bma-dashboard-superset

## Overview

##### Project type and purpose
- From the name “dashboard-superset” and minimal README, this appears to be an extension or customization layer on top of Apache Superset—a full-stack, data-viz/dashboarding platform. The goal is likely to provide a prescriptive set of dashboards or UI enhancements for Superset.

##### (current and expected) file structure
- At the moment there are only LICENSE and README.md, which suggests the code hasn’t been laid out yet in your repo. In a typical Superset-extension project you would see:
- a “superset_ext” or “plugin” directory containing Python files (Flask views, hooks)
- a “superset_ext/static” folder for JavaScript/TypeScript or CSS assets
- a “superset_ext/templates” folder for Jinja templates
- a configuration file (e.g. setup.py or pyproject.toml)
- possibly a “docker” or “ci” folder for deployment/build scripts

##### README for additional insights
- As it stands the README only names the project. When expanded, look for:
- an “Architecture” or “How it works” section
- a list of dependencies (e.g. Superset version, Python, Node)
- any code snippets showing plugin registration or configuration

##### Main components
a. User’s Web Browser (React/JS front‐end)
b. Superset Core Server (Flask + Superset’s internal API + plugin hooks)
c. Custom Dashboard Plugin (your Python & JS code, registered via Superset’s plugin framework)
d. Metadata Database (PostgreSQL or MySQL storing Superset metadata: dashboards, slices, users)
e. External Data Sources (e.g. PostgreSQL, Presto, Druid—where the dashboards read their data)
f. Build & Deployment Pipeline (Docker, CI/CD scripts, helm charts, etc.)

##### Relationships and interactions
- Superset Server interacting with the Metadata DB for dashboard definitions.
- Superset Server querying External Data Sources for chart data.
- Build/deploy pipeline feeding container images or config into the Superset runtime environment.
- If an auth service is used, show the flow of tokens or redirects between browser, Superset, and the auth provider.

##### Architectural patterns and design principles
- Plugin Architecture: highlight how your extension code hooks into Superset’s plugin registry.
- MVC within Superset: model (metadata DB), view (React components), controller (Flask routes).
- Layered separation: build pipeline → infrastructure (containers/helm) → runtime (Superset + plugin).

##### Relevant technologies, frameworks, libraries
- Backend: Python 3.x, Flask, Superset’s plugin framework
- Frontend: React (JS/TS), Ant Design (if used by Superset), custom CSS/JS in “static”
- Data stores: PostgreSQL/MySQL for metadata, plus any external catalogs
- CI/CD: Docker, GitHub Actions/Jenkins, helm/Terraform

##### Next steps
- Populate your repo with the expected directory structure and configuration files.
- Flesh out the README’s “Architecture” section with brief component descriptions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Auth
    Browser["User's Web Browser"]:::external
    AuthService["Authentication Service (OAuth/LDAP)"]:::external

    %% Superset Server and Plugin
    subgraph "Superset Runtime"
        direction TB
        SupersetCore["Superset Core Server (Flask)"]:::core
        Plugin["Custom Dashboard Plugin"]:::plugin
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MetadataDB["Metadata Database (PostgreSQL/MySQL)"]:::database
        ExternalSources["External Data Sources"]:::external
    end

    %% CI/CD
    subgraph "Build & Deployment Pipeline"
        direction TB
        CI["CI/CD Scripts (GitHub Actions/Jenkins)"]:::infra
        DockerImages["Docker Images / Helm Charts"]:::infra
    end

    %% Documentation
    subgraph "Project Files"
        direction TB
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
    end

    %% Connections
    Browser -->|"HTTP Requests"| SupersetCore
    Browser -->|"Auth Redirects / Tokens"| AuthService
    AuthService -->|"OAuth Callback"| SupersetCore

    SupersetCore -->|"Plugin Registration"| Plugin
    Plugin -->|"Serves Static Assets"| Browser
    Plugin -->|"Adds UI Routes"| Browser

    SupersetCore -->|"SQL Queries"| MetadataDB
    SupersetCore -->|"Data Queries"| ExternalSources

    CI -->|Build & Push| DockerImages
    DockerImages -->|Deploy| SupersetCore

    %% Click Events
    click README "https://github.com/civicdatalab/bma-dashboard-superset/blob/main/README.md"
    click LICENSE "https://github.com/civicdatalab/bma-dashboard-superset/tree/main/LICENSE"

    %% Styles
    classDef core fill:#AED6F1,stroke:#2E86C1,color:#1B4F72
    classDef plugin fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef external fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef database fill:#F5B7B1,stroke:#C0392B,color:#7B241C
    classDef infra fill:#D7BDE2,stroke:#8E44AD,color:#512E5F
    classDef docs fill:#D5DBDB,stroke:#566573,color:#1C2833
```
