# evg4b/modern-json-formatter architecture

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

- Interactive diagram: https://gitdiagram.com/evg4b/modern-json-formatter
- Repository: https://github.com/evg4b/modern-json-formatter

## Overview

Modern JSON Formatter is a browser extension that detects JSON in a page, presents an interactive formatted view, and supports jq queries, downloads, and configurable behavior. The main path runs from a browser page through the content-script extension and viewer, which uses background messaging for formatting, queries, history, and downloads; a Rust/WASM engine provides JSON operations. Options and FAQ are separate user-facing branches. Relationships for unsampled subsystems are limited to those explicitly documented in the README or shown in the source index.

Main entry points: [`worker-wasm/core/src/query.rs`](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/query.rs) (jq Query Engine), [`src/background/handler.ts`](https://github.com/evg4b/modern-json-formatter/blob/main/src/background/handler.ts) (Background Dispatcher), [`src/content-script/extension.ts`](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/extension.ts) (Page Integration), [`src/content-script/ui/query-input/query-input.ts`](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/query-input.ts) (jq Query Input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_viewer["Page Viewer"]
  node_extension["Page Integration<br/>[extension.ts]"]
  node_json_doc["JSON Document<br/>[json-document.ts]"]
  node_dom_builder["JSON DOM Builder<br/>[build-dom.ts]"]
  node_viewer_ui["Formatter Viewer<br/>[container.ts]"]
  node_query_ui["jq Query Input<br/>[query-input.ts]"]
  node_query_history_ui["Query Undo History<br/>[history-manager.ts]"]
  node_query_autocomplete["Query Autocomplete"]
end

subgraph group_engine["JSON Engine"]
  node_wasm_api["WASM API<br/>[lib.rs]"]
  node_wasm_conversion["WASM Conversion<br/>[convert.rs]"]
  node_parser["JSON Parser<br/>[parser.rs]"]
  node_query_engine["jq Query Engine<br/>[query.rs]"]
  node_jaq_factory["jq Value Factory"]
  node_node_model["JSON Node Model<br/>[node.rs]"]
  node_hashing["Number Hashing<br/>[hash.rs]"]
  node_convert_nodes["Value Conversion<br/>[convert.rs]"]
end

subgraph group_background["Background Services"]
  node_handler["Background Dispatcher<br/>[handler.ts]"]
  node_protocol["Message Protocol<br/>[protocol.ts]"]
  node_history_store[("Query History Store<br/>[history.ts]")]
  node_downloads["Download Service<br/>[download.ts]"]
end

subgraph group_settings["Settings and Help"]
  node_options_page["Options Page<br/>[options.ts]"]
  node_option_sections["Option Controls"]
  node_faq["FAQ<br/>[faq.ts]"]
  node_sidebar_controller["FAQ Navigation"]
end

node_page(("JSON Page"))
node_browser(("Browser Runtime"))

node_page -.->|"hosts script"| node_extension
node_extension -->|"uses document"| node_json_doc
node_extension -->|"uses builder"| node_dom_builder
node_extension -->|"mounts viewer"| node_viewer_ui
node_json_doc -.->|"builds nodes"| node_dom_builder
node_viewer_ui -.->|"renders query"| node_query_ui
node_query_ui -->|"tracks edits"| node_query_history_ui
node_query_ui -->|"updates suggestions"| node_query_autocomplete
node_query_ui -.->|"submits query"| node_handler
node_query_autocomplete -.->|"loads history"| node_handler
node_handler -->|"calls JSON ops"| node_wasm_api
node_handler -->|"reads and writes"| node_history_store
node_handler -->|"dispatches download"| node_downloads
node_wasm_api -->|"converts values"| node_wasm_conversion
node_wasm_api -.->|"runs jq"| node_query_engine
node_query_engine -->|"parses JSON"| node_parser
node_query_engine -->|"uses factory"| node_jaq_factory
node_jaq_factory -->|"parses values"| node_parser
node_query_engine -->|"builds nodes"| node_node_model
node_query_engine -->|"uses hashes"| node_hashing
node_query_engine -->|"converts values"| node_convert_nodes
node_browser -.->|"messaging host"| node_protocol
node_options_page -->|"renders controls"| node_option_sections
node_options_page -.->|"manages history"| node_handler
node_faq -->|"uses navigation"| node_sidebar_controller

click node_extension "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/extension.ts"
click node_json_doc "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/document/json-document.ts"
click node_dom_builder "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/dom/build-dom.ts"
click node_viewer_ui "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/container/container.ts"
click node_query_ui "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/query-input.ts"
click node_query_history_ui "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/history-manager.ts"
click node_query_autocomplete "https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/autocomplete.controller.ts"
click node_wasm_api "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/src/lib.rs"
click node_wasm_conversion "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/src/convert.rs"
click node_parser "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/parser.rs"
click node_query_engine "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/query.rs"
click node_jaq_factory "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/jaq_json_factory.rs"
click node_node_model "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/node.rs"
click node_hashing "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/hash.rs"
click node_convert_nodes "https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/convert.rs"
click node_handler "https://github.com/evg4b/modern-json-formatter/blob/main/src/background/handler.ts"
click node_protocol "https://github.com/evg4b/modern-json-formatter/blob/main/src/core/background/protocol.ts"
click node_history_store "https://github.com/evg4b/modern-json-formatter/blob/main/src/background/history.ts"
click node_downloads "https://github.com/evg4b/modern-json-formatter/blob/main/src/background/download.ts"
click node_options_page "https://github.com/evg4b/modern-json-formatter/blob/main/src/options/options.ts"
click node_option_sections "https://github.com/evg4b/modern-json-formatter/blob/main/src/options/sections/download-mode-section.ts"
click node_faq "https://github.com/evg4b/modern-json-formatter/blob/main/src/faq/faq.ts"
click node_sidebar_controller "https://github.com/evg4b/modern-json-formatter/blob/main/src/faq/sidebar/sidebar.controller.ts"

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_extension,node_json_doc,node_dom_builder,node_viewer_ui,node_query_ui,node_query_history_ui,node_query_autocomplete,node_browser toneBlue
class node_wasm_api,node_wasm_conversion,node_parser,node_query_engine,node_jaq_factory,node_node_model,node_hashing,node_convert_nodes toneAmber
class node_handler,node_protocol,node_history_store,node_downloads toneMint
class node_options_page,node_option_sections,node_faq,node_sidebar_controller toneRose
class node_page toneIndigo
```

## Components

### Page Viewer

- [Page Integration](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/extension.ts): `src/content-script/extension.ts`
- [JSON Document](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/document/json-document.ts): `src/content-script/document/json-document.ts`
- [JSON DOM Builder](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/dom/build-dom.ts): `src/content-script/dom/build-dom.ts`
- [Formatter Viewer](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/container/container.ts): `src/content-script/ui/container/container.ts`
- [jq Query Input](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/query-input.ts): `src/content-script/ui/query-input/query-input.ts`
- [Query Undo History](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/history-manager.ts): `src/content-script/ui/query-input/history-manager.ts`
- [Query Autocomplete](https://github.com/evg4b/modern-json-formatter/blob/main/src/content-script/ui/query-input/autocomplete.controller.ts): `src/content-script/ui/query-input/autocomplete.controller.ts`

### JSON Engine

- [WASM API](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/src/lib.rs): `worker-wasm/src/lib.rs`
- [WASM Conversion](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/src/convert.rs): `worker-wasm/src/convert.rs`
- [JSON Parser](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/parser.rs): `worker-wasm/core/src/parser.rs`
- [jq Query Engine](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/query.rs): `worker-wasm/core/src/query.rs`
- [jq Value Factory](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/jaq_json_factory.rs): `worker-wasm/core/src/jaq_json_factory.rs`
- [JSON Node Model](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/node.rs): `worker-wasm/core/src/node.rs`
- [Number Hashing](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/hash.rs): `worker-wasm/core/src/hash.rs`
- [Value Conversion](https://github.com/evg4b/modern-json-formatter/blob/main/worker-wasm/core/src/convert.rs): `worker-wasm/core/src/convert.rs`

### Background Services

- [Background Dispatcher](https://github.com/evg4b/modern-json-formatter/blob/main/src/background/handler.ts): `src/background/handler.ts`
- [Message Protocol](https://github.com/evg4b/modern-json-formatter/blob/main/src/core/background/protocol.ts): `src/core/background/protocol.ts`
- [Query History Store](https://github.com/evg4b/modern-json-formatter/blob/main/src/background/history.ts): `src/background/history.ts`
- [Download Service](https://github.com/evg4b/modern-json-formatter/blob/main/src/background/download.ts): `src/background/download.ts`

### Settings and Help

- [Options Page](https://github.com/evg4b/modern-json-formatter/blob/main/src/options/options.ts): `src/options/options.ts`
- [Option Controls](https://github.com/evg4b/modern-json-formatter/blob/main/src/options/sections/download-mode-section.ts): `src/options/sections/download-mode-section.ts`
- [FAQ](https://github.com/evg4b/modern-json-formatter/blob/main/src/faq/faq.ts): `src/faq/faq.ts`
- [FAQ Navigation](https://github.com/evg4b/modern-json-formatter/blob/main/src/faq/sidebar/sidebar.controller.ts): `src/faq/sidebar/sidebar.controller.ts`

### Other components

- **JSON Page**
- **Browser Runtime**

## Connections

- JSON Page → Page Integration: hosts script (evidence: `README.md`)
- Page Integration → JSON Document: uses document (evidence: `src/content-script/extension.ts`)
- Page Integration → JSON DOM Builder: uses builder (evidence: `src/content-script/extension.ts`)
- Page Integration → Formatter Viewer: mounts viewer (evidence: `src/content-script/extension.ts`)
- JSON Document → JSON DOM Builder: builds nodes
- Formatter Viewer → jq Query Input: renders query
- jq Query Input → Query Undo History: tracks edits (evidence: `src/content-script/ui/query-input/query-input.ts`)
- jq Query Input → Query Autocomplete: updates suggestions (evidence: `src/content-script/ui/query-input/query-input.ts`)
- jq Query Input → Background Dispatcher: submits query
- Query Autocomplete → Background Dispatcher: loads history
- Background Dispatcher → WASM API: calls JSON ops (evidence: `src/background/handler.ts`)
- Background Dispatcher → Query History Store: reads and writes (evidence: `src/background/handler.ts`)
- Background Dispatcher → Download Service: dispatches download (evidence: `src/background/handler.ts`)
- WASM API → WASM Conversion: converts values (evidence: `worker-wasm/src/lib.rs`)
- WASM API → jq Query Engine: runs jq
- jq Query Engine → JSON Parser: parses JSON (evidence: `worker-wasm/core/src/query.rs`)
- jq Query Engine → jq Value Factory: uses factory (evidence: `worker-wasm/core/src/query.rs`)
- jq Value Factory → JSON Parser: parses values (evidence: `worker-wasm/core/src/jaq_json_factory.rs`)
- jq Query Engine → JSON Node Model: builds nodes (evidence: `worker-wasm/core/src/query.rs`)
- jq Query Engine → Number Hashing: uses hashes (evidence: `worker-wasm/core/src/query.rs`)
- jq Query Engine → Value Conversion: converts values (evidence: `worker-wasm/core/src/query.rs`)
- Browser Runtime → Message Protocol: messaging host
- Options Page → Option Controls: renders controls (evidence: `src/options/options.ts`)
- Options Page → Background Dispatcher: manages history
- FAQ → FAQ Navigation: uses navigation (evidence: `src/faq/faq.ts`)
