# nicomathieu/docscribe architecture

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

- Interactive diagram: https://gitdiagram.com/nicomathieu/docscribe
- Repository: https://github.com/nicomathieu/docscribe

## Overview

DocScribe turns DOCX templates into editable, formatting-aware ASTs, exposes document operations over MCP, and persists input/output files and ASTs. Its main workflow is template upload, AST inspection, LLM-directed edits, and validation. The README also documents optional RAG utilities for retrieval; their connection to the document-authoring workflow is not shown, so they are modeled separately. Relationships follow README statements and the shown server and utility excerpts; other source behavior was not inspected.

Main entry points: [`src/docscribe/mcp/server.py`](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py) (Edit document), [`src/docscribe/storage/local.py`](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/local.py) (Local document store), [`src/docscribe/storage/s3.py`](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/s3.py) (S3 document store), [`src/docscribe/ast/converter.py`](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/converter.py) (DOCX AST converter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Document authoring"]
  node_converter["DOCX AST converter<br/>[converter.py]"]
  node_astmodel["Document AST models<br/>[models.py]"]
  node_formatter["Run formatter<br/>[run_formatter.py]"]
end

subgraph group_protocol["MCP interface"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_upload["Upload document<br/>[server.py]"]
  node_load["Load document AST<br/>[server.py]"]
  node_edit["Edit document<br/>[server.py]"]
  node_validate["Validate state<br/>[server.py]"]
end

subgraph group_persistence["Document persistence"]
  node_local[("Local document store<br/>[local.py]")]
  node_s3[("S3 document store<br/>[s3.py]")]
  node_session[("Session registry<br/>[session.py]")]
end

subgraph group_retrieval["RAG utilities"]
  node_rag["RAG utilities<br/>[rag_utils.py]"]
  node_embeddings["Embedding service<br/>[rag_utils.py]"]
  node_opensearch["OpenSearch retrieval<br/>[rag_utils.py]"]
end

node_user(("Document author"))
node_agent(("Agno LLM agent"))
node_llmservice{{"LiteLLM endpoint"}}
node_searchservice[("OpenSearch service")]

node_user -->|"provides content"| node_agent
node_agent -->|"calls tools"| node_mcp
node_mcp -->|"dispatches"| node_upload
node_mcp -->|"dispatches"| node_load
node_mcp -->|"dispatches"| node_edit
node_mcp -->|"dispatches"| node_validate
node_upload -->|"builds AST"| node_converter
node_upload -->|"stores files"| node_local
node_upload -.->|"stores files"| node_s3
node_upload -->|"registers document"| node_session
node_load -->|"gets record"| node_session
node_load -->|"reads AST"| node_local
node_load -.->|"reads AST"| node_s3
node_edit -->|"gets record"| node_session
node_edit -->|"reads and writes"| node_local
node_edit -.->|"reads and writes"| node_s3
node_edit -->|"creates runs"| node_formatter
node_edit -->|"applies edits"| node_converter
node_validate -->|"gets and updates"| node_session
node_validate -->|"reads and stores AST"| node_local
node_validate -.->|"reads and stores AST"| node_s3
node_validate -->|"rebuilds AST"| node_converter
node_converter -->|"creates elements"| node_astmodel
node_formatter -->|"returns text runs"| node_astmodel
node_local -->|"serializes AST"| node_astmodel
node_s3 -->|"serializes AST"| node_astmodel
node_rag -->|"provides embeddings"| node_embeddings
node_embeddings -->|"requests vectors"| node_llmservice
node_opensearch -->|"embeds query"| node_embeddings
node_opensearch -->|"searches index"| node_searchservice

click node_mcp "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py"
click node_upload "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py"
click node_load "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py"
click node_edit "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py"
click node_validate "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py"
click node_converter "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/converter.py"
click node_astmodel "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/models.py"
click node_formatter "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/run_formatter.py"
click node_local "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/local.py"
click node_s3 "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/s3.py"
click node_session "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/session.py"
click node_rag "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py"
click node_embeddings "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py"
click node_opensearch "https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py"

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_converter,node_astmodel,node_formatter toneBlue
class node_mcp,node_upload,node_load,node_edit,node_validate,node_searchservice toneAmber
class node_local,node_s3,node_session toneMint
class node_rag,node_embeddings,node_opensearch toneRose
class node_user,node_agent,node_llmservice toneIndigo
```

## Components

### Document authoring

- [DOCX AST converter](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/converter.py): `src/docscribe/ast/converter.py`
- [Document AST models](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/models.py): `src/docscribe/ast/models.py`
- [Run formatter](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/ast/run_formatter.py): `src/docscribe/ast/run_formatter.py`

### MCP interface

- [MCP tools](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py): `src/docscribe/mcp/server.py`
- [Upload document](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py): `src/docscribe/mcp/server.py`
- [Load document AST](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py): `src/docscribe/mcp/server.py`
- [Edit document](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py): `src/docscribe/mcp/server.py`
- [Validate state](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/mcp/server.py): `src/docscribe/mcp/server.py`

### Document persistence

- [Local document store](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/local.py): `src/docscribe/storage/local.py`
- [S3 document store](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/s3.py): `src/docscribe/storage/s3.py`
- [Session registry](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/storage/session.py): `src/docscribe/storage/session.py`

### RAG utilities

- [RAG utilities](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py): `src/docscribe/rag_utils.py`
- [Embedding service](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py): `src/docscribe/rag_utils.py`
- [OpenSearch retrieval](https://github.com/nicomathieu/docscribe/blob/main/src/docscribe/rag_utils.py): `src/docscribe/rag_utils.py`

### Other components

- **Document author**
- **Agno LLM agent**
- **LiteLLM endpoint**
- **OpenSearch service**

## Connections

- Document author → Agno LLM agent: provides content (evidence: `README.md`)
- Agno LLM agent → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Upload document: dispatches (evidence: `README.md`)
- MCP tools → Load document AST: dispatches (evidence: `README.md`)
- MCP tools → Edit document: dispatches (evidence: `README.md`)
- MCP tools → Validate state: dispatches (evidence: `README.md`)
- Upload document → DOCX AST converter: builds AST (evidence: `README.md`)
- Upload document → Local document store: stores files (evidence: `src/docscribe/mcp/server.py`)
- Upload document → S3 document store: stores files (evidence: `src/docscribe/mcp/server.py`)
- Upload document → Session registry: registers document (evidence: `src/docscribe/mcp/server.py`)
- Load document AST → Session registry: gets record (evidence: `src/docscribe/mcp/server.py`)
- Load document AST → Local document store: reads AST (evidence: `src/docscribe/mcp/server.py`)
- Load document AST → S3 document store: reads AST (evidence: `src/docscribe/mcp/server.py`)
- Edit document → Session registry: gets record (evidence: `src/docscribe/mcp/server.py`)
- Edit document → Local document store: reads and writes (evidence: `src/docscribe/mcp/server.py`)
- Edit document → S3 document store: reads and writes (evidence: `src/docscribe/mcp/server.py`)
- Edit document → Run formatter: creates runs (evidence: `README.md`)
- Edit document → DOCX AST converter: applies edits (evidence: `README.md`)
- Validate state → Session registry: gets and updates (evidence: `src/docscribe/mcp/server.py`)
- Validate state → Local document store: reads and stores AST (evidence: `src/docscribe/mcp/server.py`)
- Validate state → S3 document store: reads and stores AST (evidence: `src/docscribe/mcp/server.py`)
- Validate state → DOCX AST converter: rebuilds AST (evidence: `src/docscribe/mcp/server.py`)
- DOCX AST converter → Document AST models: creates elements (evidence: `src/docscribe/ast/converter.py`)
- Run formatter → Document AST models: returns text runs (evidence: `src/docscribe/ast/run_formatter.py`)
- Local document store → Document AST models: serializes AST (evidence: `src/docscribe/storage/local.py`)
- S3 document store → Document AST models: serializes AST (evidence: `src/docscribe/storage/s3.py`)
- RAG utilities → Embedding service: provides embeddings (evidence: `src/docscribe/rag_utils.py`)
- Embedding service → LiteLLM endpoint: requests vectors (evidence: `src/docscribe/rag_utils.py`)
- OpenSearch retrieval → Embedding service: embeds query (evidence: `src/docscribe/rag_utils.py`)
- OpenSearch retrieval → OpenSearch service: searches index (evidence: `src/docscribe/rag_utils.py`)
