Vyuh DOCX Architecture Map

This page is a reviewer map for packages/vyuh_docx. It explains the headless document engine, the rendering pipeline, and the boundary with docx_editor.

What This Package Owns

vyuh_docx is a pure Dart document engine. It reads, builds, transforms, and exports document structure. It has no Flutter editor UI and no workflow authority.

DOCX / SFDT / HTML / Markdown / builder input
  -> DocxBuiltDocument AST
  -> resolved source-backed properties
  -> layout model
  -> exporters
  -> DOCX / SFDT / HTML / PDF

Main Layers

Layer	Main APIs	Responsibility
Input	DocxReader, SfdtReader, HtmlParser, MarkdownParser, docx()	Convert source formats or generated content into the model.
Model	DocxBuiltDocument, DocxParagraph, DocxText, DocxTable, DocxSectionDef, drawing/comment/revision nodes	Preserve document structure and Word/SFDT properties.
Layout	PdfLayoutEngine, PdfLayoutDocument, PdfLayoutBox	Measure content and create page fragments.
Export	DocxExporter, SfdtExporter, HtmlExporter, PdfExporter	Write model output formats.
Utilities	DocxDocumentDiff, DocxTemplateEngine, validators, ID helpers, XML helpers	Support comparison, templating, and diagnostics.

Boundary With DOCX Editor

Concern	Owner
Parse DOCX into an AST	vyuh_docx
Convert AST to SFDT	vyuh_docx
Convert SFDT to DOCX or PDF	vyuh_docx
Host Syncfusion DocumentEditor	docx_editor
Enforce actor permissions	Host and docx_editor
Save document versions	Host through docx_editor contracts
Electronic signing	Host and docx_editor
Controlled copy allocation and register writes	Host and docx_editor

This separation keeps vyuh_docx reusable on servers, command-line tools, tests, and Flutter apps.

Source-Backed Rendering Rule

Renderer behavior must come from one of these sources:

• DOCX XML;
• SFDT JSON;
• generated DocxBuiltDocument fields;
• a documented Word or OOXML default.

If a needed property is missing, add it to the model first. Do not add file-name-specific or customer-specific renderer branches.

Why The Layout Model Exists

Directly painting AST nodes is not enough for Word-like output. Reviewers should expect layout facts to be explicit:

Layout fact	Why it matters
Paragraph line boxes	Needed for wrapping, alignment, tabs, and page breaks.
Table row fragments	Needed for rows that split across pages.
Repeated header rows	Needed for multi-page tables.
Section boxes	Needed for page size, margins, columns, headers, and footers.
Image and shape geometry	Needed for inline and floating positioning.
Page fragments	Needed for deterministic PDF painting and diagnostics.

PdfLayoutDocument and the PdfLayoutBox family make those facts testable.

Review Checklist

• Parsing preserves source-backed properties instead of dropping them early.
• PDF export uses PdfLayoutEngine before painting pages.
• Deterministic output options stay in PdfExporter.
• Workflow concepts such as actor, signing, lifecycle, permissions, and print registers do not enter this package.
• Any new renderer rule has a DOCX, SFDT, or documented default source.