# automattic/harper architecture

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

- Interactive diagram: https://gitdiagram.com/automattic/harper
- Repository: https://github.com/automattic/harper
- Video tour (about a minute): https://gitdiagram.com/automattic/harper/video

## Overview

Harper is a privacy-focused English grammar checker. Users provide text through command-line, editor, browser, desktop, or WebAssembly interfaces; the runtime parses and analyzes it, then exposes lint findings and suggestions to the interface. The core includes document parsing, token-expression matching, and a large rule set, with adapters for markup and code comments. The README documents broad editor and WASM availability; arrows for unsampled integrations are omitted rather than inferred.

Main entry points: [`harper-core/src/document.rs`](https://github.com/automattic/harper/blob/master/harper-core/src/document.rs) (Document model), [`harper-cli/src/main.rs`](https://github.com/automattic/harper/blob/master/harper-cli/src/main.rs) (CLI commands), [`harper-cli/src/lint.rs`](https://github.com/automattic/harper/blob/master/harper-cli/src/lint.rs) (CLI lint flow), [`harper-cli/src/lint_engine.rs`](https://github.com/automattic/harper/blob/master/harper-cli/src/lint_engine.rs) (Lint engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core analysis"]
  node_document["Document model<br/>[document.rs]"]
  node_expressions["Token expressions<br/>[sequence_expr.rs]"]
  node_rules["Lint rules<br/>[mod.rs]"]
  node_dictionary["Word metadata"]
end

subgraph group_formats["Text formats"]
  node_markdown["Markdown parser<br/>[markdown.rs]"]
  node_comments["Code comments<br/>[comment_parser.rs]"]
  node_typst["Typst translator"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_cli_input["Input handling<br/>[input.rs]"]
  node_cli_lint["CLI lint flow<br/>[lint.rs]"]
  node_cli_engine["Lint engine<br/>[lint_engine.rs]"]
  node_cli_report["Lint reporting<br/>[lint_reporter.rs]"]
  node_wasm["WASM interface<br/>[lib.rs]"]
  node_js["JavaScript API<br/>[main.ts]"]
end

subgraph group_editors["Editor integrations"]
  node_ls["Language server<br/>[main.rs]"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_obsidian["Obsidian plugin<br/>[index.ts]"]
  node_chrome["Chrome extension<br/>[ProtocolClient.ts]"]
  node_popup["Lint popup UI<br/>[PopupHandler.ts]"]
end

subgraph group_desktop["Desktop app"]
  node_desktop["Desktop runtime<br/>[main.rs]"]
  node_highlighter["Native highlighter<br/>[window_manager.rs]"]
end

node_user(("Writer or developer"))

node_user -->|"submits text"| node_cli
node_cli -->|"selects input"| node_cli_input
node_cli -->|"dispatches lint"| node_cli_lint
node_cli_lint -->|"uses input"| node_cli_input
node_cli_lint -->|"runs engine"| node_cli_engine
node_cli -->|"prints results"| node_cli_report
node_cli_engine -.->|"builds document"| node_document
node_cli_engine -->|"runs rules"| node_rules
node_document -->|"uses parser"| node_markdown
node_document -->|"provides tokens"| node_expressions
node_expressions -->|"matches patterns"| node_rules
node_document -->|"uses metadata"| node_dictionary
node_user -->|"edits text"| node_ls
node_ls -->|"starts backend"| node_ls
node_user -.->|"edits text"| node_vscode
node_user -.->|"edits text"| node_obsidian
node_user -.->|"edits text"| node_chrome
node_chrome -.->|"shows suggestions"| node_popup
node_user -.->|"writes text"| node_desktop
node_desktop -->|"starts highlighter"| node_highlighter
node_highlighter -->|"requests lint actions"| node_desktop
node_user -->|"checks text"| node_wasm
node_js -.->|"wraps runtime"| node_wasm
node_typst -.->|"adapts text"| node_document
node_comments -.->|"adapts text"| node_document

click node_cli "https://github.com/automattic/harper/blob/master/harper-cli/src/main.rs"
click node_cli_input "https://github.com/automattic/harper/blob/master/harper-cli/src/input.rs"
click node_cli_lint "https://github.com/automattic/harper/blob/master/harper-cli/src/lint.rs"
click node_cli_engine "https://github.com/automattic/harper/blob/master/harper-cli/src/lint_engine.rs"
click node_cli_report "https://github.com/automattic/harper/blob/master/harper-cli/src/lint_reporter.rs"
click node_document "https://github.com/automattic/harper/blob/master/harper-core/src/document.rs"
click node_expressions "https://github.com/automattic/harper/blob/master/harper-core/src/expr/sequence_expr.rs"
click node_rules "https://github.com/automattic/harper/blob/master/harper-core/src/linting/mod.rs"
click node_dictionary "https://github.com/automattic/harper/blob/master/harper-core/src/dict_word_metadata.rs"
click node_markdown "https://github.com/automattic/harper/blob/master/harper-core/src/parsers/markdown.rs"
click node_comments "https://github.com/automattic/harper/blob/master/harper-comments/src/comment_parser.rs"
click node_typst "https://github.com/automattic/harper/blob/master/harper-typst/src/typst_translator.rs"
click node_wasm "https://github.com/automattic/harper/blob/master/harper-wasm/src/lib.rs"
click node_js "https://github.com/automattic/harper/blob/master/packages/harper.js/src/main.ts"
click node_ls "https://github.com/automattic/harper/blob/master/harper-ls/src/main.rs"
click node_vscode "https://github.com/automattic/harper/blob/master/packages/vscode-plugin/src/extension.ts"
click node_obsidian "https://github.com/automattic/harper/blob/master/packages/obsidian-plugin/src/index.ts"
click node_chrome "https://github.com/automattic/harper/blob/master/packages/chrome-plugin/src/ProtocolClient.ts"
click node_popup "https://github.com/automattic/harper/blob/master/packages/lint-framework/src/lint/PopupHandler.ts"
click node_desktop "https://github.com/automattic/harper/blob/master/harper-desktop/src-tauri/src/main.rs"
click node_highlighter "https://github.com/automattic/harper/blob/master/harper-desktop/src-tauri/src/highlighter/window_manager.rs"

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_document,node_expressions,node_rules,node_dictionary toneBlue
class node_markdown,node_comments,node_typst toneAmber
class node_cli,node_cli_input,node_cli_lint,node_cli_engine,node_cli_report,node_wasm,node_js toneMint
class node_ls,node_vscode,node_obsidian,node_chrome,node_popup toneRose
class node_desktop,node_highlighter,node_user toneIndigo
```

## Components

### Core analysis

- [Document model](https://github.com/automattic/harper/blob/master/harper-core/src/document.rs): `harper-core/src/document.rs`
- [Token expressions](https://github.com/automattic/harper/blob/master/harper-core/src/expr/sequence_expr.rs): `harper-core/src/expr/sequence_expr.rs`
- [Lint rules](https://github.com/automattic/harper/blob/master/harper-core/src/linting/mod.rs): `harper-core/src/linting/mod.rs`
- [Word metadata](https://github.com/automattic/harper/blob/master/harper-core/src/dict_word_metadata.rs): `harper-core/src/dict_word_metadata.rs`

### Text formats

- [Markdown parser](https://github.com/automattic/harper/blob/master/harper-core/src/parsers/markdown.rs): `harper-core/src/parsers/markdown.rs`
- [Code comments](https://github.com/automattic/harper/blob/master/harper-comments/src/comment_parser.rs): `harper-comments/src/comment_parser.rs`
- [Typst translator](https://github.com/automattic/harper/blob/master/harper-typst/src/typst_translator.rs): `harper-typst/src/typst_translator.rs`

### User interfaces

- [CLI commands](https://github.com/automattic/harper/blob/master/harper-cli/src/main.rs): `harper-cli/src/main.rs`
- [Input handling](https://github.com/automattic/harper/blob/master/harper-cli/src/input.rs): `harper-cli/src/input.rs`
- [CLI lint flow](https://github.com/automattic/harper/blob/master/harper-cli/src/lint.rs): `harper-cli/src/lint.rs`
- [Lint engine](https://github.com/automattic/harper/blob/master/harper-cli/src/lint_engine.rs): `harper-cli/src/lint_engine.rs`
- [Lint reporting](https://github.com/automattic/harper/blob/master/harper-cli/src/lint_reporter.rs): `harper-cli/src/lint_reporter.rs`
- [WASM interface](https://github.com/automattic/harper/blob/master/harper-wasm/src/lib.rs): `harper-wasm/src/lib.rs`
- [JavaScript API](https://github.com/automattic/harper/blob/master/packages/harper.js/src/main.ts): `packages/harper.js/src/main.ts`

### Editor integrations

- [Language server](https://github.com/automattic/harper/blob/master/harper-ls/src/main.rs): `harper-ls/src/main.rs`
- [VS Code extension](https://github.com/automattic/harper/blob/master/packages/vscode-plugin/src/extension.ts): `packages/vscode-plugin/src/extension.ts`
- [Obsidian plugin](https://github.com/automattic/harper/blob/master/packages/obsidian-plugin/src/index.ts): `packages/obsidian-plugin/src/index.ts`
- [Chrome extension](https://github.com/automattic/harper/blob/master/packages/chrome-plugin/src/ProtocolClient.ts): `packages/chrome-plugin/src/ProtocolClient.ts`
- [Lint popup UI](https://github.com/automattic/harper/blob/master/packages/lint-framework/src/lint/PopupHandler.ts): `packages/lint-framework/src/lint/PopupHandler.ts`

### Desktop app

- [Desktop runtime](https://github.com/automattic/harper/blob/master/harper-desktop/src-tauri/src/main.rs): `harper-desktop/src-tauri/src/main.rs`
- [Native highlighter](https://github.com/automattic/harper/blob/master/harper-desktop/src-tauri/src/highlighter/window_manager.rs): `harper-desktop/src-tauri/src/highlighter/window_manager.rs`

### Other components

- **Writer or developer**

## Connections

- Writer or developer → CLI commands: submits text (evidence: `README.md`)
- CLI commands → Input handling: selects input (evidence: `harper-cli/src/main.rs`)
- CLI commands → CLI lint flow: dispatches lint (evidence: `harper-cli/src/main.rs`)
- CLI lint flow → Input handling: uses input (evidence: `harper-cli/src/lint.rs`)
- CLI lint flow → Lint engine: runs engine (evidence: `harper-cli/src/lint.rs`)
- CLI commands → Lint reporting: prints results (evidence: `harper-cli/src/main.rs`)
- Lint engine → Document model: builds document
- Lint engine → Lint rules: runs rules (evidence: `harper-cli/src/lint_engine.rs`)
- Document model → Markdown parser: uses parser (evidence: `harper-core/src/document.rs`)
- Document model → Token expressions: provides tokens (evidence: `harper-core/src/document.rs`)
- Token expressions → Lint rules: matches patterns (evidence: `harper-core/src/expr/mod.rs`)
- Document model → Word metadata: uses metadata (evidence: `harper-core/src/document.rs`)
- Writer or developer → Language server: edits text (evidence: `README.md`)
- Language server → Language server: starts backend (evidence: `harper-ls/src/main.rs`)
- Writer or developer → VS Code extension: edits text
- Writer or developer → Obsidian plugin: edits text
- Writer or developer → Chrome extension: edits text
- Chrome extension → Lint popup UI: shows suggestions
- Writer or developer → Desktop runtime: writes text
- Desktop runtime → Native highlighter: starts highlighter (evidence: `harper-desktop/src-tauri/src/main.rs`)
- Native highlighter → Desktop runtime: requests lint actions (evidence: `harper-desktop/src-tauri/src/highlighter/window_manager.rs`)
- Writer or developer → WASM interface: checks text (evidence: `README.md`)
- JavaScript API → WASM interface: wraps runtime
- Typst translator → Document model: adapts text
- Code comments → Document model: adapts text
