# mckinsey/vizro architecture

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

- Interactive diagram: https://gitdiagram.com/mckinsey/vizro
- Repository: https://github.com/mckinsey/vizro

## Overview

##### Project type and purpose
- This is a monorepo containing three interrelated Python packages:
- **vizro-core** – the low-code dashboard framework (Pydantic models + Plotly/Dash integration).
- **vizro-ai** – an extension that layers LLM-powered chart/dashboard generation on top of vizro-core.
- **vizro-mcp** – a minimal server component that can host or orchestrate Vizro dashboards (e.g., multi-component platform).
- It includes docs (MkDocs/Sphinx), examples, CI/CD (GitHub Actions), Docker devcontainer, and release tooling.

##### File structure
- Top-level folders:
- **.devcontainer** – Dockerfile + setup for VS Code dev containers.
- **.github** – Issue templates, GitHub Actions workflows.
- **tools** – release scripts, helper utilities (e.g., PyCafé link checker).
- **vizro-core**, **vizro-ai**, **vizro-mcp** – each follows the same layout:
– `src/<package>` with Python source
– `tests` (unit, integration, e2e)
– docs (MkDocs or ReadTheDocs config)
– examples & changelog directories
– packaging config (pyproject.toml, hatch.toml)
- Patterns:
- Monorepo with sibling packages
- Pydantic model definitions → code generation → Dash + Plotly runtime
- CI pipelines per package + monorepo‐wide workflows
- Devcontainer to unify development environment

##### README insights
- The README emphasizes: low-code configuration via Pydantic/JSON/YAML, built‐in best practices, extensibility via Python/JS/CSS, production deployment with Plotly/Dash, and an LLM “AI” layer for natural-language generation.
- It cites core tech: Python 3.9–3.13, Plotly, Dash, Pydantic, Hatch (build), MkDocs/ReadTheDocs.

##### Be detailed but modular
- Five major areas: Developer tools, Core library, AI extension, Server, CI/CD & publishing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Tools
    subgraph "Developer Environment" 
        direction TB
        DevContainer["VS Code Devcontainer"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DevJSON["devcontainer.json"]:::infra
        InstallHatch["install-hatch.sh"]:::infra
    end

    subgraph "CLI & Release Tools"
        direction TB
        ReleaseScript["release.sh"]:::infra
        CheckRelease["check_package_release.py"]:::infra
        ExtractNotes["extract_release_notes.py"]:::infra
        PyCafe["pycafe/"]:::infra
    end

    %% Core Library
    subgraph "vizro-core (Core Library)" 
        direction TB
        Models["Pydantic Models"]:::core
        Builder["Dashboard Builder & Runtime API"]:::core
        PlotlyInt["Plotly Integration"]:::core
        StaticAssets["Static Assets (JS/CSS)"]:::core
    end

    %% AI Extension
    subgraph "vizro-ai (AI Extension)"
        direction TB
        AIInterface["Core Interface & Orchestration"]:::ai
        LLMModels["LLM Provider Layer"]:::ai
        DashboardGen["Dashboard Generation Models"]:::ai
        PlotUtils["Plot Generation Utilities"]:::ai
    end

    %% MCP Server
    subgraph "vizro-mcp (MCP Server)"
        direction TB
        ServerEntrypoint["HTTP Entrypoint (server.py)"]:::server
        RequestSchemas["Request Schemas"]:::server
        MCPUtils["Internal Utilities"]:::server
    end

    %% Infrastructure
    subgraph "CI/CD & Publishing"
        direction TB
        Workflows["CI/CD Workflows"]:::infra
        PyPI["PyPI"]:::external
        ReadTheDocs["ReadTheDocs"]:::external
        DockerImage["Docker Image"]:::infra
    end

    %% Documentation & Packaging
    subgraph "Docs & Packaging"
        direction TB
        CoreDocs["vizro-core MkDocs"]:::infra
        AIDocs["vizro-ai MkDocs"]:::infra
        MCPDocs["vizro-mcp ReadTheDocs"]:::infra
        CorePkg["vizro-core pyproject.toml & hatch.toml"]:::infra
        AIPkg["vizro-ai pyproject.toml & hatch.toml"]:::infra
        MCPPkg["vizro-mcp pyproject.toml & hatch.toml"]:::infra
    end

    %% Runtime & External
    Browser["Web Browser"]:::external
    LLMProvider["LLM Provider (OpenAI etc.)"]:::external

    %% Relationships
    DevContainer -->|uses| Dockerfile
    DevContainer -->|uses| DevJSON
    DevContainer -->|runs| InstallHatch
    DevContainer -->|invokes| ReleaseScript

    ReleaseScript -->|runs| CheckRelease
    ReleaseScript -->|runs| ExtractNotes
    ReleaseScript -->|uses| PyCafe

    DevContainer -->|develops| Models
    DevContainer -->|develops| AIInterface
    DevContainer -->|develops| ServerEntrypoint

    Models -->|used by| Builder
    Builder -->|calls| PlotlyInt
    Builder -->|serves assets| StaticAssets
    Builder -->|generates app| Browser

    AIInterface -->|invokes| LLMModels
    LLMModels -->|calls| LLMProvider
    AIInterface -->|generates| DashboardGen
    DashboardGen -->|uses| Models
    DashboardGen -->|uses| Builder
    PlotUtils -->|assists| Builder

    ServerEntrypoint -->|validates| RequestSchemas
    ServerEntrypoint -->|calls| MCPUtils
    ServerEntrypoint -->|invokes| Builder
    ServerEntrypoint -->|invokes| AIInterface
    ServerEntrypoint -->|serves app| Browser

    Workflows -->|runs tests| Models
    Workflows -->|runs tests| AIInterface
    Workflows -->|runs tests| ServerEntrypoint
    Workflows -->|builds| DockerImage
    Workflows -->|publishes| PyPI
    Workflows -->|publishes| ReadTheDocs

    CoreDocs -->|docs for| Models
    AIDocs -->|docs for| AIInterface
    MCPDocs -->|docs for| ServerEntrypoint

    CorePkg -->|configures| Models
    AIPkg -->|configures| AIInterface
    MCPPkg -->|configures| ServerEntrypoint

    %% Click Events
    click Dockerfile "https://github.com/mckinsey/vizro/tree/main/.devcontainer/Dockerfile"
    click DevJSON "https://github.com/mckinsey/vizro/blob/main/.devcontainer/devcontainer.json"
    click InstallHatch "https://github.com/mckinsey/vizro/blob/main/.devcontainer/install-hatch.sh"
    click ReleaseScript "https://github.com/mckinsey/vizro/blob/main/tools/release.sh"
    click CheckRelease "https://github.com/mckinsey/vizro/blob/main/tools/check_package_release.py"
    click ExtractNotes "https://github.com/mckinsey/vizro/blob/main/tools/extract_release_notes.py"
    click PyCafe "https://github.com/mckinsey/vizro/tree/main/tools/pycafe/"
    click Models "https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/models/"
    click Builder "https://github.com/mckinsey/vizro/blob/main/vizro-core/src/vizro/_vizro.py"
    click PlotlyInt "https://github.com/mckinsey/vizro/blob/main/vizro-core/src/vizro/plotly/express.py"
    click StaticAssets "https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/"
    click AIInterface "https://github.com/mckinsey/vizro/blob/main/vizro-ai/src/vizro_ai/_vizro_ai.py"
    click LLMModels "https://github.com/mckinsey/vizro/blob/main/vizro-ai/src/vizro_ai/_llm_models.py"
    click DashboardGen "https://github.com/mckinsey/vizro/blob/main/vizro-ai/src/vizro_ai/dashboard/_graph/dashboard_creation.py"
    click DashboardGen "https://github.com/mckinsey/vizro/blob/main/vizro-ai/src/vizro_ai/dashboard/_pydantic_output.py"
    click DashboardGen "https://github.com/mckinsey/vizro/tree/main/vizro-ai/src/vizro_ai/dashboard/_response_models/"
    click PlotUtils "https://github.com/mckinsey/vizro/tree/main/vizro-ai/src/vizro_ai/plot/_utils/"
    click ServerEntrypoint "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/src/vizro_mcp/server.py"
    click RequestSchemas "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/src/vizro_mcp/_schemas/schemas.py"
    click MCPUtils "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/src/vizro_mcp/_utils/utils.py"
    click CoreDocs "https://github.com/mckinsey/vizro/blob/main/vizro-core/mkdocs.yml"
    click AIDocs "https://github.com/mckinsey/vizro/blob/main/vizro-ai/mkdocs.yml"
    click MCPDocs "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/.readthedocs.yaml"
    click CorePkg "https://github.com/mckinsey/vizro/blob/main/vizro-core/pyproject.toml"
    click CorePkg "https://github.com/mckinsey/vizro/blob/main/vizro-core/hatch.toml"
    click AIPkg "https://github.com/mckinsey/vizro/blob/main/vizro-ai/pyproject.toml"
    click AIPkg "https://github.com/mckinsey/vizro/blob/main/vizro-ai/hatch.toml"
    click MCPPkg "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/pyproject.toml"
    click MCPPkg "https://github.com/mckinsey/vizro/blob/main/vizro-mcp/hatch.toml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ai fill:#d4edda,stroke:#333,stroke-width:1px
    classDef server fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef infra fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
```
