# microsoft/flint-chart architecture

> Architecture diagram of the GitHub repository microsoft/flint-chart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/flint-chart
- Repository: https://github.com/microsoft/flint-chart

## Overview

1. **Monorepo shape**
   - This repo is organized around one product family, Flint, with three shipping surfaces: the TypeScript library (`flint-js`), the MCP server (`flint-mcp`), and the public demo/documentation site (`site`).
   - A source-only Python port (`flint-py`) mirrors the library architecture for validation and future release work.

2. **Core compilation pipeline**
   - The architectural center is the Flint compiler pipeline in `packages/flint-js/src/core`.
   - Input is a compact chart spec plus data and semantic types; core modules resolve semantics, make chart/layout decisions, compute sizing, and apply color/encoding rules before backend rendering.

3. **Backend boundary**
   - Backend-specific code is cleanly separated from core logic.
   - `vegalite`, `echarts`, and `chartjs` each expose the same high-level assembly entry points, but generate different native spec formats and have their own templates, recommendation logic, and spec instantiation paths.

4. **Template-driven rendering**
   - Each backend has a `templates/` layer containing chart-specific renderers such as bar, line, scatter, heatmap, pie, radar, waterfall, etc.
   - The templates are the main extension point for adding chart types without changing the compiler core.

5. **Shared type and semantics system**
   - The core package defines the domain model: chart spec types, semantic types, field semantics, encoding actions/overrides, and registry metadata.
   - This semantic layer is what allows Flint to infer presentation details from business meaning rather than requiring verbose chart configuration.

6. **MCP server architecture**
   - `packages/flint-mcp` wraps the library in an agent-facing server that exposes tools to list, validate, compile, and render charts.
   - It is both a protocol server and a rendering service: it can return backend-native specs, static SVG/PNG-like outputs, or open an interactive chart view for MCP clients.

7. **Render subsystem in MCP**
   - The MCP package has its own `render/` boundary that converts Flint specs into visual output.
   - It includes backend adapters, SVG/font handling, and data-source loading, which lets the server render charts from in-memory rows or from local files such as JSON, CSV, or TSV.

8. **Web demo and authoring experience**
   - The `site/` package is a Vite + React application that consumes the same library code to provide the landing page, docs viewer, chart gallery, editor, and MCP walkthrough pages.
   - It contains reusable UI components for chart previews, code/editing panels, sizing playgrounds, and side-by-side backend views.

9. **Test-data as a shared architectural asset**
   - `shared/test-data` is a large corpus of fixture inputs/expected outputs that drives automated tests, gallery examples, and cross-backend regression coverage.
   - This is a key boundary in the repo: the same canonical cases validate the TypeScript package, the MCP renderer, and the Python port.

10. **Python port parity**
   - `packages/flint-py` mirrors the TypeScript structure closely: `core` for semantics/decisions/layout and `vegalite` for backend assembly/templates.
   - Its tests and tooling suggest it is used as a parity implementation rather than an independent product path.

11. **Documentation and contribution workflow**
   - The `docs/` tree is part of the architecture, not just marketing: it documents compiler design, backend integration, chart templates, semantic types, and the MCP workflow.
   - Repo docs and agent skill files form an authoring boundary for humans and agents outside the codebase.

12. **Build, release, and verification**
   - The project uses GitHub Actions for CI, code scanning, npm publishing, and GitHub Pages deployment.
   - TypeScript packages are built/tested with modern Node tooling (`tsup`, `vitest`), while the site is built separately and published as the project website.

Main entry points: [`site/src`](https://github.com/microsoft/flint-chart/tree/main/site/src) (Site app), [`packages/flint-js/src/core`](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/core) (Core pipeline), [`packages/flint-mcp/src/render`](https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/src/render) (Render boundary), [`.github/workflows`](https://github.com/microsoft/flint-chart/blob/main/.github/workflows) (CI workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monorepo["Flint monorepo"]
end

subgraph group_js_lib["TypeScript library"]
  node_flint_js_core["Core pipeline<br/>compiler core"]
  node_flint_js_vegalite["Vega-Lite<br/>backend"]
  node_flint_js_echarts["ECharts<br/>backend"]
  node_flint_js_chartjs["Chart.js<br/>backend"]
  node_flint_js_gallery["Gallery data<br/>examples"]
  node_flint_js_test_data["TS fixtures<br/>regression corpus"]
end

subgraph group_mcp["MCP server"]
  node_flint_mcp_server["MCP server<br/>protocol server<br/>[server.ts]"]
  node_flint_mcp_tools["Tools<br/>tooling"]
  node_flint_mcp_render["Render boundary<br/>renderer"]
  node_flint_mcp_ui["MCP UI<br/>embedded web ui"]
end

subgraph group_site["Web site"]
  node_site_app["Site app<br/>Vite React app"]
  node_site_components["UI components<br/>presentation layer"]
  node_site_routes["Routes<br/>pages"]
  node_site_shared["Site data<br/>shared web data"]
end

subgraph group_py["Python port"]
  node_flint_py_core["Py core<br/>compiler core"]
  node_flint_py_vegalite["Py Vega-Lite<br/>backend"]
  node_flint_py_tests["Py eval<br/>parity tests"]
end

subgraph group_assets["Shared assets"]
  node_shared_test_data[("Shared corpus<br/>fixtures")]
  node_docs_tree["Docs"]
  node_agent_skills["Agent skills<br/>authoring boundary"]
  node_ci_workflows["CI workflows<br/>automation<br/>[workflows]"]
end

node_flint_js_core -->|"feeds specs"| node_flint_js_vegalite
node_flint_js_core -->|"feeds specs"| node_flint_js_echarts
node_flint_js_core -->|"feeds specs"| node_flint_js_chartjs
node_flint_js_vegalite -->|"renders examples"| node_flint_js_gallery
node_flint_js_echarts -->|"renders examples"| node_flint_js_gallery
node_flint_js_chartjs -->|"renders examples"| node_flint_js_gallery
node_shared_test_data -->|"drives tests"| node_flint_js_test_data
node_shared_test_data -->|"drives render tests"| node_flint_mcp_render
node_shared_test_data -->|"drives parity"| node_flint_py_tests
node_flint_mcp_server -->|"exposes tools"| node_flint_mcp_tools
node_flint_mcp_server -->|"delegates render"| node_flint_mcp_render
node_flint_mcp_render -->|"uses compiler"| node_flint_js_core
node_flint_mcp_render -->|"backend adapter"| node_flint_js_vegalite
node_flint_mcp_render -->|"backend adapter"| node_flint_js_echarts
node_flint_mcp_render -->|"backend adapter"| node_flint_js_chartjs
node_flint_mcp_server -->|"serves view"| node_flint_mcp_ui
node_site_app -->|"composes"| node_site_components
node_site_app -->|"routes"| node_site_routes
node_site_app -->|"uses data"| node_site_shared
node_site_app -->|"uses library"| node_flint_js_core
node_site_app -->|"shows backend"| node_flint_js_vegalite
node_site_app -->|"shows backend"| node_flint_js_echarts
node_site_app -->|"shows backend"| node_flint_js_chartjs
node_flint_py_core -->|"feeds specs"| node_flint_py_vegalite
node_flint_py_tests -->|"verifies"| node_flint_py_core
node_docs_tree -->|"documents"| node_flint_js_core
node_docs_tree -->|"documents"| node_flint_mcp_server
node_docs_tree -->|"supports authoring"| node_site_app
node_agent_skills -->|"guides usage"| node_docs_tree
node_ci_workflows -->|"validates"| node_shared_test_data
node_ci_workflows -->|"deploys"| node_site_app
node_ci_workflows -->|"tests"| node_flint_js_core
node_ci_workflows -->|"tests"| node_flint_py_tests

click node_flint_js_core "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/core"
click node_flint_js_vegalite "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/vegalite"
click node_flint_js_echarts "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/echarts"
click node_flint_js_chartjs "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/chartjs"
click node_flint_js_gallery "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/gallery"
click node_flint_js_test_data "https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/test-data"
click node_flint_mcp_server "https://github.com/microsoft/flint-chart/blob/main/packages/flint-mcp/src/server.ts"
click node_flint_mcp_tools "https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/src/tools"
click node_flint_mcp_render "https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/src/render"
click node_flint_mcp_ui "https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/ui"
click node_site_app "https://github.com/microsoft/flint-chart/tree/main/site/src"
click node_site_components "https://github.com/microsoft/flint-chart/tree/main/site/src/components"
click node_site_routes "https://github.com/microsoft/flint-chart/tree/main/site/src/routes"
click node_site_shared "https://github.com/microsoft/flint-chart/tree/main/site/src/shared"
click node_flint_py_core "https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/flint/core"
click node_flint_py_vegalite "https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/flint/vegalite"
click node_flint_py_tests "https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/tests"
click node_shared_test_data "https://github.com/microsoft/flint-chart/tree/main/shared/test-data"
click node_docs_tree "https://github.com/microsoft/flint-chart/tree/main/docs"
click node_agent_skills "https://github.com/microsoft/flint-chart/tree/main/agent-skills"
click node_ci_workflows "https://github.com/microsoft/flint-chart/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flint_js_core,node_flint_js_vegalite,node_flint_js_echarts,node_flint_js_chartjs,node_flint_js_gallery,node_flint_js_test_data toneAmber
class node_flint_mcp_server,node_flint_mcp_tools,node_flint_mcp_render,node_flint_mcp_ui toneMint
class node_site_app,node_site_components,node_site_routes,node_site_shared toneRose
class node_flint_py_core,node_flint_py_vegalite,node_flint_py_tests toneIndigo
class node_shared_test_data,node_docs_tree,node_agent_skills,node_ci_workflows toneTeal
```

## Components

### TypeScript library

Primary Flint compiler and backend assembly implementation.

- [Core pipeline](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/core): compiler core · Semantics, decisions, layout, sizing, and encoding rules for Flint specs. · `packages/flint-js/src/core`
- [Vega-Lite](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/vegalite): backend · Vega-Lite assembly and chart templates. · `packages/flint-js/src/vegalite`
- [ECharts](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/echarts): backend · ECharts assembly, facet handling, and templates. · `packages/flint-js/src/echarts`
- [Chart.js](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/chartjs): backend · Chart.js assembly and templates. · `packages/flint-js/src/chartjs`
- [Gallery data](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/gallery): examples · Canonical gallery scenarios and benchmark-style examples. · `packages/flint-js/src/gallery`
- [TS fixtures](https://github.com/microsoft/flint-chart/tree/main/packages/flint-js/src/test-data): regression corpus · TypeScript test corpus covering semantics, sizing, backends, and gallery cases. · `packages/flint-js/src/test-data`

### MCP server

Agent-facing server plus chart rendering boundary.

- [MCP server](https://github.com/microsoft/flint-chart/blob/main/packages/flint-mcp/src/server.ts): protocol server · Agent-facing server exposing list, validate, compile, and render tools. · `packages/flint-mcp/src/server.ts`
- [Tools](https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/src/tools): tooling · Tool definitions and schemas for chart operations. · `packages/flint-mcp/src/tools`
- [Render boundary](https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/src/render): renderer · Converts Flint specs into visual output through backend adapters and SVG handling. · `packages/flint-mcp/src/render`
- [MCP UI](https://github.com/microsoft/flint-chart/tree/main/packages/flint-mcp/ui): embedded web ui · Interactive chart view served alongside the MCP server. · `packages/flint-mcp/ui`

### Web site

Docs, gallery, editor, and demo application.

- [Site app](https://github.com/microsoft/flint-chart/tree/main/site/src): Vite React app · Landing page, docs viewer, gallery, editor, and walkthrough pages. · `site/src`
- [UI components](https://github.com/microsoft/flint-chart/tree/main/site/src/components): presentation layer · Reusable preview, editor, sizing, and comparison components. · `site/src/components`
- [Routes](https://github.com/microsoft/flint-chart/tree/main/site/src/routes): pages · Top-level site experiences and content entry points. · `site/src/routes`
- [Site data](https://github.com/microsoft/flint-chart/tree/main/site/src/shared): shared web data · Docs catalog, backend lists, wall settings, and editor payload helpers. · `site/src/shared`

### Python port

Source-only parity implementation mirroring the TypeScript library.

- [Py core](https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/flint/core): compiler core · Python parity implementation of semantics, layout, and decisions. · `packages/flint-py/flint/core`
- [Py Vega-Lite](https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/flint/vegalite): backend · Python Vega-Lite assembly and templates mirroring the TS structure. · `packages/flint-py/flint/vegalite`
- [Py eval](https://github.com/microsoft/flint-chart/tree/main/packages/flint-py/tests): parity tests · Validation and evaluation tooling for Python implementation parity. · `packages/flint-py/tests`

### Shared assets

Canonical fixtures and documentation used across runtimes.

- [Shared corpus](https://github.com/microsoft/flint-chart/tree/main/shared/test-data): fixtures · Canonical input/expected-output cases shared across TypeScript, MCP, and Python validation. · `shared/test-data`
- [Docs](https://github.com/microsoft/flint-chart/tree/main/docs): architecture docs · Design, tutorial, and reference documentation for compiler and workflows. · `docs`
- [Agent skills](https://github.com/microsoft/flint-chart/tree/main/agent-skills): authoring boundary · Skill and agent guidance for chart authoring and repository workflows. · `agent-skills`
- [CI workflows](https://github.com/microsoft/flint-chart/blob/main/.github/workflows): automation · GitHub Actions for testing, publishing, scanning, and site deployment. · `.github/workflows`

## Connections

- Core pipeline → Vega-Lite: feeds specs · Core decisions are assembled into Vega-Lite backend specs.
- Core pipeline → ECharts: feeds specs · Core decisions are assembled into ECharts backend specs.
- Core pipeline → Chart.js: feeds specs · Core decisions are assembled into Chart.js backend specs.
- Vega-Lite → Gallery data: renders examples · Gallery examples are instantiated through the Vega-Lite backend.
- ECharts → Gallery data: renders examples · Gallery examples are instantiated through the ECharts backend.
- Chart.js → Gallery data: renders examples · Gallery examples are instantiated through the Chart.js backend.
- Shared corpus → TS fixtures: drives tests · Shared canonical cases are mirrored into TypeScript test data.
- Shared corpus → Render boundary: drives render tests · Shared fixtures validate MCP rendering behavior.
- Shared corpus → Py eval: drives parity · Shared fixtures validate Python parity and evaluation.
- MCP server → Tools: exposes tools · Server registers compile, validate, list, and render tools.
- MCP server → Render boundary: delegates render · Server forwards render requests into the render subsystem.
- Render boundary → Core pipeline: uses compiler · MCP rendering starts from the same Flint core compiler pipeline.
- Render boundary → Vega-Lite: backend adapter · Rendering can target Vega-Lite output.
- Render boundary → ECharts: backend adapter · Rendering can target ECharts output.
- Render boundary → Chart.js: backend adapter · Rendering can target Chart.js output.
- MCP server → MCP UI: serves view · The server can open an interactive chart view for clients.
- Site app → UI components: composes · Site pages are built from reusable UI components.
- Site app → Routes: routes · Top-level experiences are organized as route modules.
- Site app → Site data: uses data · Site pages rely on shared catalog and configuration data.
- Site app → Core pipeline: uses library · The site consumes the Flint library code for live previews and docs.
- Site app → Vega-Lite: shows backend · The site compares backend-native outputs, including Vega-Lite.
- Site app → ECharts: shows backend · The site compares backend-native outputs, including ECharts.
- Site app → Chart.js: shows backend · The site compares backend-native outputs, including Chart.js.
- Py core → Py Vega-Lite: feeds specs · Python core output is assembled into Python Vega-Lite specs.
- Py eval → Py core: verifies · Python tests validate core behavior and parity decisions.
- Docs → Core pipeline: documents · Docs explain the compiler pipeline and semantic model.
- Docs → MCP server: documents · Docs cover MCP setup and workflow.
- Docs → Site app: supports authoring · Docs feed the website content and walkthroughs.
- Agent skills → Docs: guides usage · Skill files and guidance sit beside the documentation boundary.
- CI workflows → Shared corpus: validates · CI runs regression coverage over the shared corpus.
- CI workflows → Site app: deploys · CI builds and publishes the site.
- CI workflows → Core pipeline: tests · CI verifies the TypeScript library and backends.
- CI workflows → Py eval: tests · CI includes Python parity verification.