DOCX Editor Architecture Map

This page is a reviewer map for packages/docx_editor. It explains the package boundary, the runtime flow, and which authority stays with the host application.

What This Package Owns

docx_editor is the regulated editor shell around Syncfusion DocumentEditor. It does not parse WordprocessingML itself and it does not decide whether a user is allowed to edit a business document. Its job is to connect the editor UI to host-owned policy, audit, storage, lifecycle, locking, signing, conversion, and controlled print contracts.

host document record
  -> DocxPickedDocument
  -> DocxController
  -> SyncfusionDocxEditor
  -> Syncfusion iframe / desktop editor
  -> DocxFileGateway
  -> storage, review, signing, conversion, print contracts

Boundary With Vyuh DOCX

Concern	Owner	Reason
DOCX and SFDT parsing	vyuh_docx	Pure document format work
PDF layout and painting	vyuh_docx	Rendering engine work
Syncfusion editor hosting	docx_editor	Flutter/editor integration
Actor attribution	docx_editor and host	Session and audit concern
Capabilities and lifecycle gates	docx_editor and host	Business authorization concern
Storage writes and versioning	Host through DocxStorageAdapter	Backend owns persistence
Electronic signature ceremony	docx_editor and host	Requires actor, reauth, audit, vocabulary
Controlled copy issuance	docx_editor and host	Requires policy, copy allocation, register, audit

The important review point is that docx_editor depends on vyuh_docx for conversion and rendering, but keeps regulated workflow decisions out of vyuh_docx.

Runtime Flow

1. The host resolves a document into DocxPickedDocument.
2. The host builds DocxCapabilities from server-side access decisions.
3. The host creates DocxController with storage, trusted time, actor, audit, lifecycle, and optional signing policy.
4. SyncfusionDocxEditor applies the picked document's capabilities and edit lock to the controller.
5. The editor platform implementation opens DOCX or SFDT content in Syncfusion.
6. The platform implementation attaches a DocxFileGateway so the controller can request SFDT, DOCX, or PDF bytes from the live editor.
7. Saves, downloads, comments, revisions, signing, and print issuance go back through DocxController so capability, lifecycle, lock, and audit rules are enforced in one place.

Main Components

Component	Responsibility
SyncfusionDocxEditor	Public Flutter widget. Selects web/desktop implementation and attaches the session to the controller.
DocxController	Central enforcement point for capabilities, lifecycle, locks, dirty state, save/export, comments, revisions, signing, and audit.
DocxCapabilities	Declarative action gates for the current actor/document. Presets cover view, comment, review, edit, and locked edit modes.
DocxPickedDocument	Host-resolved document input containing source, capabilities, lifecycle, lock, integrity expectations, and metadata.
DocxFileGateway	Internal live-editor bridge used by the controller to get current SFDT, DOCX, and PDF content.
DocxConversionService	Abstract conversion contract. VyuhDocxConversionService is the pure-Dart implementation backed by vyuh_docx.
ControlledPrintService	Issues controlled or uncontrolled PDF copies with policy, allocation, trusted time, register, and audit hooks.

Host-Owned Authority

Production hosts must provide these values from trusted backend state:

Host input	Why it is not local-only
DocxActor	Required for attribution and electronic signatures.
DocxCapabilities	Must be derived from server-side policy, workflow task, lifecycle, and permissions.
DocxLifecycleState	Released documents must not become editable because of a client mistake.
DocxEditLock	Single-editor enforcement needs backend lock ownership.
DocxStorageAdapter	Saves and versions belong to the host document repository.
DocxTrustedClock	Audit and signatures need authoritative UTC time.
DocxCredentialVerifier	E-sign reauthentication must use the host identity system.
onAuditEvent	Audit durability belongs to the host.
Controlled print policy/register/allocation	Copy issuance must be atomic and traceable.

Security-Relevant Bridge Boundary

On web, the editor runs inside an iframe and uses postMessage for readiness, content-change events, and bridge request responses. The web implementation accepts only messages that come from the editor iframe's contentWindow. When DocxSyncfusionConfig.trustedOrigin is set, the generated editor HTML also pins outgoing messages to that origin.

Reviewer focus:

• forged page messages must not complete pending export/save requests;
• the host should set trustedOrigin outside local development;
• bridge responses are still treated as untrusted until the controller applies capability, lifecycle, lock, and integrity checks.

Review Checklist

• vyuh_docx remains the only place doing document parsing and PDF rendering.
• docx_editor remains the only place doing actor, lifecycle, signing, and controlled-print workflow.
• Host contracts are explicit constructor parameters or interfaces.
• Capability mapping fails closed when the host grants no access.
• Save/export requests use the controller and cannot bypass policy.
• Web bridge messages are pinned to the editor iframe source.