# kklimuk/docx-cli architecture

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

- Interactive diagram: https://gitdiagram.com/kklimuk/docx-cli
- Repository: https://github.com/kklimuk/docx-cli

## Overview

docx-cli is an agent-oriented command-line editor for Word `.docx` files. The principal workflow is to read a document using stable locators, find and edit content, optionally add comments or tracked changes, then return the modified file for review in Word. The CLI also supports document creation, rendering, and specialized content such as tables, images, equations, styles, and sections. The tree and README establish these capabilities; sampled source confirms CLI dispatch, query handling, and edit-layer dependencies, but not all command-to-core wiring.

Main entry points: [`src/cli/index.ts`](https://github.com/kklimuk/docx-cli/blob/main/src/cli/index.ts) (Command dispatcher), [`src/cli/find`](https://github.com/kklimuk/docx-cli/tree/main/src/cli/find) (Find and replace), [`src/cli/edit`](https://github.com/kklimuk/docx-cli/tree/main/src/cli/edit) (Edit and insert), [`src/core/ast/document`](https://github.com/kklimuk/docx-cli/tree/main/src/core/ast/document) (Document model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Command dispatcher<br/>[index.ts]"]
end

subgraph group_review["Read and review"]
  node_read["Read and inspect"]
  node_find["Find and replace"]
  node_diff["Document diff"]
  node_render["Page rendering"]
end

subgraph group_mutation["Document changes"]
  node_edit["Edit and insert"]
  node_track["Tracked changes"]
  node_comments["Comments"]
end

subgraph group_content["Content tools"]
  node_create["Create documents"]
  node_tables["Tables"]
  node_styles["Styles and layout"]
  node_media["Images and links"]
  node_equations["Equations"]
  node_code["Code blocks"]
end

subgraph group_engine["Document engine"]
  node_docmodel["Document model"]
  node_raw["OOXML package"]
  node_editcore["Edit operations<br/>[index.tsx]"]
  node_findcore["Query operations"]
end

node_agent(("Agent or user"))
node_word(("Microsoft Word"))

node_agent -->|"invokes commands"| node_cli
node_cli -->|"dispatches"| node_read
node_cli -->|"dispatches"| node_find
node_cli -->|"dispatches"| node_diff
node_cli -->|"dispatches"| node_render
node_cli -->|"dispatches"| node_edit
node_cli -->|"dispatches"| node_track
node_cli -->|"dispatches"| node_comments
node_cli -->|"dispatches"| node_create
node_cli -->|"dispatches"| node_tables
node_cli -->|"dispatches"| node_styles
node_cli -->|"dispatches"| node_media
node_cli -->|"dispatches"| node_equations
node_cli -->|"dispatches"| node_code
node_find -->|"queries document"| node_findcore
node_edit -->|"applies edits"| node_editcore
node_editcore -->|"mutates model"| node_docmodel
node_docmodel -->|"represents package"| node_raw
node_agent -->|"opens result"| node_word

click node_cli "https://github.com/kklimuk/docx-cli/blob/main/src/cli/index.ts"
click node_read "https://github.com/kklimuk/docx-cli/tree/main/src/cli/read"
click node_find "https://github.com/kklimuk/docx-cli/tree/main/src/cli/find"
click node_diff "https://github.com/kklimuk/docx-cli/tree/main/src/cli/diff"
click node_render "https://github.com/kklimuk/docx-cli/tree/main/src/cli/render"
click node_edit "https://github.com/kklimuk/docx-cli/tree/main/src/cli/edit"
click node_track "https://github.com/kklimuk/docx-cli/tree/main/src/cli/track-changes"
click node_comments "https://github.com/kklimuk/docx-cli/tree/main/src/cli/comments"
click node_create "https://github.com/kklimuk/docx-cli/tree/main/src/cli/create"
click node_tables "https://github.com/kklimuk/docx-cli/tree/main/src/cli/tables"
click node_styles "https://github.com/kklimuk/docx-cli/tree/main/src/cli/styles"
click node_media "https://github.com/kklimuk/docx-cli/tree/main/src/cli/images"
click node_equations "https://github.com/kklimuk/docx-cli/tree/main/src/cli/equations"
click node_code "https://github.com/kklimuk/docx-cli/tree/main/src/cli/code"
click node_docmodel "https://github.com/kklimuk/docx-cli/tree/main/src/core/ast/document"
click node_raw "https://github.com/kklimuk/docx-cli/tree/main/src/core/raw"
click node_editcore "https://github.com/kklimuk/docx-cli/blob/main/src/core/edit/index.tsx"
click node_findcore "https://github.com/kklimuk/docx-cli/tree/main/src/core/find"

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_cli,node_agent toneBlue
class node_read,node_find,node_diff,node_render toneAmber
class node_edit,node_track,node_comments toneMint
class node_create,node_tables,node_styles,node_media,node_equations,node_code toneRose
class node_docmodel,node_raw,node_editcore,node_findcore,node_word toneIndigo
```

## Components

### CLI entry

- [Command dispatcher](https://github.com/kklimuk/docx-cli/blob/main/src/cli/index.ts): `src/cli/index.ts`

### Read and review

- [Read and inspect](https://github.com/kklimuk/docx-cli/tree/main/src/cli/read): `src/cli/read`
- [Find and replace](https://github.com/kklimuk/docx-cli/tree/main/src/cli/find): `src/cli/find`
- [Document diff](https://github.com/kklimuk/docx-cli/tree/main/src/cli/diff): `src/cli/diff`
- [Page rendering](https://github.com/kklimuk/docx-cli/tree/main/src/cli/render): `src/cli/render`

### Document changes

- [Edit and insert](https://github.com/kklimuk/docx-cli/tree/main/src/cli/edit): `src/cli/edit`
- [Tracked changes](https://github.com/kklimuk/docx-cli/tree/main/src/cli/track-changes): `src/cli/track-changes`
- [Comments](https://github.com/kklimuk/docx-cli/tree/main/src/cli/comments): `src/cli/comments`

### Content tools

- [Create documents](https://github.com/kklimuk/docx-cli/tree/main/src/cli/create): `src/cli/create`
- [Tables](https://github.com/kklimuk/docx-cli/tree/main/src/cli/tables): `src/cli/tables`
- [Styles and layout](https://github.com/kklimuk/docx-cli/tree/main/src/cli/styles): `src/cli/styles`
- [Images and links](https://github.com/kklimuk/docx-cli/tree/main/src/cli/images): `src/cli/images`
- [Equations](https://github.com/kklimuk/docx-cli/tree/main/src/cli/equations): `src/cli/equations`
- [Code blocks](https://github.com/kklimuk/docx-cli/tree/main/src/cli/code): `src/cli/code`

### Document engine

- [Document model](https://github.com/kklimuk/docx-cli/tree/main/src/core/ast/document): `src/core/ast/document`
- [OOXML package](https://github.com/kklimuk/docx-cli/tree/main/src/core/raw): `src/core/raw`
- [Edit operations](https://github.com/kklimuk/docx-cli/blob/main/src/core/edit/index.tsx): `src/core/edit/index.tsx`
- [Query operations](https://github.com/kklimuk/docx-cli/tree/main/src/core/find): `src/core/find`

### Other components

- **Agent or user**
- **Microsoft Word**

## Connections

- Agent or user → Command dispatcher: invokes commands
- Command dispatcher → Read and inspect: dispatches
- Command dispatcher → Find and replace: dispatches
- Command dispatcher → Document diff: dispatches
- Command dispatcher → Page rendering: dispatches
- Command dispatcher → Edit and insert: dispatches
- Command dispatcher → Tracked changes: dispatches
- Command dispatcher → Comments: dispatches
- Command dispatcher → Create documents: dispatches
- Command dispatcher → Tables: dispatches
- Command dispatcher → Styles and layout: dispatches
- Command dispatcher → Images and links: dispatches
- Command dispatcher → Equations: dispatches
- Command dispatcher → Code blocks: dispatches
- Find and replace → Query operations: queries document
- Edit and insert → Edit operations: applies edits
- Edit operations → Document model: mutates model
- Document model → OOXML package: represents package
- Agent or user → Microsoft Word: opens result