# slab/quill architecture

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

- Interactive diagram: https://gitdiagram.com/slab/quill
- Repository: https://github.com/slab/quill

## Overview

1. **Repository shape**
   - This is a monorepo with two main runtime products: the **Quill editor library** in `packages/quill` and the **documentation/playground website** in `packages/website`.
   - The root also contains release/changelog automation and GitHub Actions workflows, so the repo is both a library source and a published docs site.

2. **Primary product boundary: `packages/quill`**
   - `packages/quill` is the distributable rich-text editor package published to npm and served via CDN.
   - It is built from TypeScript/JavaScript source into browser-ready bundles using Babel/Webpack, with package-specific configs (`babel.config.cjs`, `webpack*.cjs`, `playwright.config.ts`).

3. **Editor core architecture**
   - The editing engine is centered around `src/core` and `src/core/quill.ts`, which define the main `Quill` runtime and its coordination of selection, history, clipboard, keyboard, composition, theme, and module lifecycle.
   - `src/core/emitter.ts` provides the event bus that links DOM/user events to editor state updates.

4. **Document model and rendering layer**
   - `src/blots` contains the document abstraction layer: blocks, inlines, embeds, text, scroll, cursor, etc.
   - These blots form the internal tree Quill uses to represent and manipulate content, separating the editor’s logical document model from raw DOM.
   - `src/formats` defines the built-in formatting primitives (bold, list, link, image, table, etc.) that map editor operations onto blots and DOM attributes.

5. **Module-driven behavior**
   - `src/modules` houses behavior subsystems that plug into the core editor: clipboard, history, keyboard, input, toolbar, syntax highlighting, uploader, table handling, and external-HTML normalization.
   - `normalizeExternalHTML` is a distinct ingestion path for pasted content, with dedicated normalizers for Google Docs and MS Word, showing that paste/import is a first-class architecture boundary.

6. **Theme, UI, and styling boundary**
   - `src/themes`, `src/ui`, and `src/assets` separate behavior from presentation.
   - Themes (`base`, `snow`, `bubble`) assemble CSS/stylus assets and UI elements like tooltips, pickers, icon pickers, and color pickers.
   - This keeps the editor logic reusable across different visual skins and runtime integrations.

7. **Data flow inside the editor**
   - User input enters through browser events handled by modules like keyboard, input, clipboard, and composition.
   - Those events are normalized into editor operations via the core/editor layer, which updates the document model, selection state, and history.
   - The document model then drives DOM updates and UI changes, with selection/scroll helpers ensuring the visible editor stays synchronized.

8. **Website and documentation app: `packages/website`**
   - The website is a separate Next.js app that serves docs, blog posts, and the interactive playground.
   - Its content is largely MDX-based under `content/docs` and `content/blog`, with page routing and layout components in `src/pages` and `src/components`.
   - This is a content-driven frontend, not part of the editor runtime itself.

9. **Interactive playground subsystem**
   - `packages/website/src/playground` and `src/pages/playground` host runnable demos for editor configurations and custom examples.
   - The site uses components like `Sandpack`, `Editor`, and playground layouts to render live code examples and Quill configurations.
   - Static standalone demos under `src/pages/standalone` provide prebuilt editor variants such as snow, bubble, and stress cases.

10. **Testing strategy**
    - `packages/quill/test/unit` covers editor internals, formats, modules, themes, UI, and utility functions with Vitest.
    - `packages/quill/test/e2e` uses Playwright for browser-level interaction tests against a dedicated dev server fixture.
    - `packages/quill/test/fuzz` adds randomized validation for editor/table behavior, and `test/types` checks TypeScript typing contracts.

11. **Build, release, and automation**
    - GitHub Actions workflows handle test, changelog, release, labels, and pull-request automation.
    - Root `scripts/` plus package-local build scripts support changelog generation, release orchestration, and asset/build transforms such as SVG import inlining.
    - This repo is optimized for publishing both the editor package and the documentation site as separate deliverables.

12. **External-facing outputs**
    - The library is consumed as an npm package and via CDN bundles, with theme CSS as separate artifacts.
    - The website is the public documentation and demo surface, while the package is the editor runtime distributed to application developers.

Main entry points: [`packages/quill/src/core/quill.ts`](https://github.com/slab/quill/blob/main/packages/quill/src/core/quill.ts) (Core runtime), [`packages/quill/src/modules`](https://github.com/slab/quill/tree/main/packages/quill/src/modules) (Modules), [`packages/website/src/pages`](https://github.com/slab/quill/tree/main/packages/website/src/pages) (Site pages), [`packages/quill/test`](https://github.com/slab/quill/tree/main/packages/quill/test) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo root"]
  node_automation["Automation<br/>release + CI"]
end

subgraph group_quill["Quill package"]
  node_quill_public["Quill API<br/>package entry<br/>[quill.ts]"]
  node_quill_core["Core runtime<br/>editor engine<br/>[quill.ts]"]
  node_quill_emitter(("Event bus<br/>event coordination<br/>[emitter.ts]"))
  node_quill_model{{"Document model<br/>blots tree"}}
  node_quill_formats["Formats<br/>format primitives"]
  node_quill_modules["Modules<br/>behavior plugins"]
  node_quill_normalize["Normalize HTML<br/>paste ingestion"]
  node_quill_theme["Themes<br/>presentation layer"]
  node_quill_ui["UI widgets<br/>editor controls"]
  node_quill_assets["Styles/assets<br/>styling assets"]
  node_quill_tests["Tests<br/>test suite"]
  node_quill_build["Build config<br/>tooling<br/>[webpack.config.cjs]"]
end

subgraph group_website["Website"]
  node_site_content["Docs content<br/>MDX content"]
  node_site_pages["Site pages<br/>Next.js routes"]
  node_site_components["Site UI<br/>frontend components"]
  node_site_playground["Playground<br/>live demos"]
  node_site_data["Site data<br/>navigation data"]
end

node_automation -->|"drives"| node_quill_build
node_automation -->|"runs"| node_quill_tests
node_quill_public -->|"exposes"| node_quill_core
node_quill_core -->|"uses"| node_quill_emitter
node_quill_core -->|"updates"| node_quill_model
node_quill_core -->|"orchestrates"| node_quill_modules
node_quill_core -->|"skins"| node_quill_theme
node_quill_model -->|"renders via"| node_quill_formats
node_quill_modules -->|"ingests"| node_quill_normalize
node_quill_modules -->|"presents"| node_quill_ui
node_quill_theme -->|"bundles"| node_quill_assets
node_quill_ui -->|"consumes"| node_quill_assets
node_quill_tests -->|"verifies"| node_quill_core
node_quill_tests -->|"verifies"| node_quill_modules
node_quill_build -->|"builds"| node_quill_public
node_site_pages -->|"renders"| node_site_content
node_site_pages -->|"composes"| node_site_components
node_site_pages -->|"navigates"| node_site_data
node_site_components -->|"hosts"| node_site_playground
node_site_data -->|"indexes"| node_site_content
node_site_playground -->|"embeds"| node_quill_public
node_site_playground -->|"demonstrates"| node_quill_theme

click node_automation "https://github.com/slab/quill/tree/main/scripts"
click node_quill_public "https://github.com/slab/quill/blob/main/packages/quill/src/quill.ts"
click node_quill_core "https://github.com/slab/quill/blob/main/packages/quill/src/core/quill.ts"
click node_quill_emitter "https://github.com/slab/quill/blob/main/packages/quill/src/core/emitter.ts"
click node_quill_model "https://github.com/slab/quill/tree/main/packages/quill/src/blots"
click node_quill_formats "https://github.com/slab/quill/tree/main/packages/quill/src/formats"
click node_quill_modules "https://github.com/slab/quill/tree/main/packages/quill/src/modules"
click node_quill_normalize "https://github.com/slab/quill/tree/main/packages/quill/src/modules/normalizeExternalHTML"
click node_quill_theme "https://github.com/slab/quill/tree/main/packages/quill/src/themes"
click node_quill_ui "https://github.com/slab/quill/tree/main/packages/quill/src/ui"
click node_quill_assets "https://github.com/slab/quill/tree/main/packages/quill/src/assets"
click node_quill_tests "https://github.com/slab/quill/tree/main/packages/quill/test"
click node_quill_build "https://github.com/slab/quill/blob/main/packages/quill/webpack.config.cjs"
click node_site_content "https://github.com/slab/quill/tree/main/packages/website/content"
click node_site_pages "https://github.com/slab/quill/tree/main/packages/website/src/pages"
click node_site_components "https://github.com/slab/quill/tree/main/packages/website/src/components"
click node_site_playground "https://github.com/slab/quill/tree/main/packages/website/src/playground"
click node_site_data "https://github.com/slab/quill/tree/main/packages/website/src/data"

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_automation toneBlue
class node_quill_public,node_quill_core,node_quill_emitter,node_quill_model,node_quill_formats,node_quill_modules,node_quill_normalize,node_quill_theme,node_quill_ui,node_quill_assets,node_quill_tests,node_quill_build toneAmber
class node_site_content,node_site_pages,node_site_components,node_site_playground,node_site_data toneMint
```

## Components

### Repo root

Monorepo-wide release, workflows, and shared metadata

- [Automation](https://github.com/slab/quill/tree/main/scripts): release + CI · GitHub Actions, changelog, and release orchestration for publishing and repo maintenance · `scripts`

### Quill package

Distributable rich-text editor runtime and browser bundles

- [Quill API](https://github.com/slab/quill/blob/main/packages/quill/src/quill.ts): package entry · Top-level package entry points that expose the editor library to consumers · `packages/quill/src/quill.ts`
- [Core runtime](https://github.com/slab/quill/blob/main/packages/quill/src/core/quill.ts): editor engine · Main Quill runtime coordinating selection, history, clipboard, keyboard, composition, themes, and module lifecycle · `packages/quill/src/core/quill.ts`
- [Event bus](https://github.com/slab/quill/blob/main/packages/quill/src/core/emitter.ts): event coordination · Core emitter linking DOM/user events to editor state updates · `packages/quill/src/core/emitter.ts`
- [Document model](https://github.com/slab/quill/tree/main/packages/quill/src/blots): blots tree · Internal content tree for blocks, inlines, embeds, text, cursor, and scroll management · `packages/quill/src/blots`
- [Formats](https://github.com/slab/quill/tree/main/packages/quill/src/formats): format primitives · Built-in formatting behaviors such as bold, lists, links, embeds, tables, and alignment · `packages/quill/src/formats`
- [Modules](https://github.com/slab/quill/tree/main/packages/quill/src/modules): behavior plugins · Clipboard, history, keyboard, input, toolbar, syntax, tables, uploader, and HTML normalization · `packages/quill/src/modules`
- [Normalize HTML](https://github.com/slab/quill/tree/main/packages/quill/src/modules/normalizeExternalHTML): paste ingestion · First-class pasted-content normalization path with Google Docs and MS Word handlers · `packages/quill/src/modules/normalizeExternalHTML`
- [Themes](https://github.com/slab/quill/tree/main/packages/quill/src/themes): presentation layer · Base, snow, and bubble themes that assemble styling and UI chrome · `packages/quill/src/themes`
- [UI widgets](https://github.com/slab/quill/tree/main/packages/quill/src/ui): editor controls · Tooltips, pickers, icon pickers, color pickers, and shared editor UI helpers · `packages/quill/src/ui`
- [Styles/assets](https://github.com/slab/quill/tree/main/packages/quill/src/assets): styling assets · Stylus themes, icons, and shared visual assets for the editor package · `packages/quill/src/assets`
- [Tests](https://github.com/slab/quill/tree/main/packages/quill/test): test suite · Unit, E2E, fuzz, and type tests covering editor internals and browser behavior · `packages/quill/test`
- [Build config](https://github.com/slab/quill/blob/main/packages/quill/webpack.config.cjs): tooling · Babel, Webpack, Playwright, and package-local build scripts for browser bundles and validation · `packages/quill/webpack.config.cjs`

### Website

Next.js docs, blog, and playground app

- [Docs content](https://github.com/slab/quill/tree/main/packages/website/content): MDX content · Docs and blog content that document APIs, usage, and product direction · `packages/website/content`
- [Site pages](https://github.com/slab/quill/tree/main/packages/website/src/pages): Next.js routes · Routing, layouts, and page shells for docs, blog, home, and standalone demos · `packages/website/src/pages`
- [Site UI](https://github.com/slab/quill/tree/main/packages/website/src/components): frontend components · Reusable layout, MDX, SEO, editor, and playground components for the website · `packages/website/src/components`
- [Playground](https://github.com/slab/quill/tree/main/packages/website/src/playground): live demos · Interactive editor examples and standalone variants used to exercise Quill configurations · `packages/website/src/playground`
- [Site data](https://github.com/slab/quill/tree/main/packages/website/src/data): navigation data · Structured docs and playground metadata used to build navigation and content indexes · `packages/website/src/data`

## Connections

- Automation → Build config: drives · Release and CI automation run package build and validation workflows
- Automation → Tests: runs · Automation executes tests before release and on pull requests
- Quill API → Core runtime: exposes · The public API instantiates and surfaces the core editor runtime
- Core runtime → Event bus: uses · Core runtime routes editor and DOM events through the emitter
- Core runtime → Document model: updates · Core operations mutate the document model and selection state
- Core runtime → Modules: orchestrates · Core runtime loads and coordinates behavior modules
- Core runtime → Themes: skins · Core editor can be paired with different visual themes
- Document model → Formats: renders via · Document nodes are shaped and annotated by format primitives
- Modules → Normalize HTML: ingests · Clipboard and paste flows delegate HTML normalization to dedicated handlers
- Modules → UI widgets: presents · Modules such as toolbar and syntax use shared UI widgets
- Themes → Styles/assets: bundles · Themes assemble stylus files and icon assets into runtime skins
- UI widgets → Styles/assets: consumes · UI widgets rely on shared icons and styling assets
- Tests → Core runtime: verifies · Unit and E2E tests cover editor runtime behavior
- Tests → Modules: verifies · Tests cover clipboard, history, keyboard, tables, and normalization modules
- Build config → Quill API: builds · Tooling compiles the package entry points into distributable bundles
- Site pages → Docs content: renders · Route handlers render MDX docs and blog content
- Site pages → Site UI: composes · Page shells are assembled from shared website components
- Site pages → Site data: navigates · Pages use structured data for docs and playground navigation
- Site UI → Playground: hosts · Playground components embed runnable Quill demos
- Site data → Docs content: indexes · Data definitions organize docs and API content into site navigation
- Playground → Quill API: embeds · Interactive demos instantiate the Quill library in multiple configurations
- Playground → Themes: demonstrates · Standalone demos showcase Quill theme variants and editor states
