microsoft/flint-chart

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.