How OfficeCLI's Three-Layer Architecture Works: L1 Read, L2 DOM, and L3 Raw XML

OfficeCLI abstracts Office document manipulation through a three-layer architecture that separates semantic document viewing (L1), structured DOM querying (L2), and direct OpenXML manipulation (L3), enabling both safe high-level operations and precise low-level control.

The iOfficeAI/OfficeCLI repository provides a command-line interface for manipulating Microsoft Office documents through a clean architectural separation. This OfficeCLI three-layer architecture ensures developers can work at the appropriate abstraction level, from simple text extraction to precise XML surgery, without risking document integrity.

Understanding the Three Layers

The architecture divides document access into distinct layers defined in src/officecli/Core/IDocumentHandler.cs. Each layer serves a specific purpose, allowing users to choose between convenience and control when working with Word, Excel, or PowerPoint files.

L1 Read (Semantic Layer)

The semantic layer provides human-readable, high-level views of documents. According to the source code in src/officecli/Core/IDocumentHandler.cs lines 58-74, this layer exposes methods including ViewAsText, ViewAsAnnotated, ViewAsOutline, and ViewAsStats. These methods return plain text, annotated text, document outlines, or statistical summaries while completely hiding the underlying XML structure.

Typical commands at this layer include:

• officecli view text
• officecli view annotated
• officecli view outline
• officecli view stats

L2 DOM (Query Layer)

The query layer enables structured access to the document's logical DOM through path-based selectors. As implemented in src/officecli/Core/IDocumentHandler.cs lines 81-98, this layer provides Get, Query, Set, Add, Remove, Move, and CopyFrom methods. It builds a tree of DocumentNode objects that can be addressed via logical paths such as /paragraph[3] or /table[1]/row[2].

This layer bridges the gap between human-readable views and raw XML by allowing property-based manipulation of specific document elements without requiring knowledge of OpenXML schema details.

L3 Raw XML (Raw Layer)

The raw layer offers direct access to underlying OpenXML parts for edge cases that the DOM cannot express. Defined in src/officecli/Core/IDocumentHandler.cs lines 98-106, this layer implements Raw, RawSet, and AddPart methods. It works with the exact XML of specific parts like /document, /styles, or /word/footnotes.xml, as documented in schemas/help/docx/raw.json lines 12-31.

Commands at this layer include:

• officecli raw — Read raw XML of a specific part
• officecli raw-set — Modify raw XML using XPath expressions

The IDocumentHandler Interface

The IDocumentHandler interface unifies all three layers, ensuring consistent implementation across document types. Each Office format implements this interface in respective handlers:

• WordHandler.cs for Word documents
• ExcelHandler.cs for Excel spreadsheets
• PowerPointHandler.cs for PowerPoint presentations

This design guarantees that scripts written for one layer work consistently across all supported Office formats, whether you are extracting text from a Word document or querying cells in an Excel spreadsheet.

Practical Usage Examples

The following examples demonstrate how to interact with each layer of the OfficeCLI three-layer architecture.

L1 Read Examples

View plain text from a document:

officecli view text report.docx

L2 DOM Examples

Retrieve a specific paragraph:

officecli get report.docx /paragraph[3]

Modify paragraph properties:

officecli set report.docx /paragraph[3] style=Heading1

L3 Raw XML Examples

Read the raw XML of the main document part:

officecli raw report.docx /document

Remove the first paragraph using XPath:

officecli raw-set report.docx /document \
  --xpath "//w:p[1]" \
  --action remove

Summary

• OfficeCLI's three-layer architecture separates document manipulation into L1 Read (semantic), L2 DOM (query), and L3 Raw XML (raw) layers.
• The IDocumentHandler interface in src/officecli/Core/IDocumentHandler.cs defines methods for all three layers, ensuring consistent cross-format support across Word, Excel, and PowerPoint.
• L1 Read provides safe, high-level views via ViewAsText, ViewAsAnnotated, and similar methods for extracting content without modification.
• L2 DOM enables precise manipulation through Get, Set, Add, and other methods using logical paths like /paragraph[2].
• L3 Raw XML offers direct OpenXML access via Raw and RawSet for operations the DOM layer cannot express, such as editing custom XML parts.

Frequently Asked Questions

What is the difference between L2 DOM and L3 Raw XML in OfficeCLI?

The L2 DOM layer operates on a logical tree of DocumentNode objects using human-readable paths like /paragraph[3], while L3 Raw XML works directly with the underlying OpenXML markup using XPath. Use L2 for property changes and structured queries; use L3 only when inserting custom XML fragments or editing parts not exposed by the DOM, as implemented in the Raw and RawSet methods.

When should I use the L1 Read layer versus the L2 DOM layer?

Use the L1 Read layer when you need to extract information without modifying the document, such as generating plain text reports or document statistics via ViewAsText or ViewAsStats. Use the L2 DOM layer when you need to modify specific elements, query structured data, or manipulate document properties programmatically via commands like get and set.

Is the three-layer architecture consistent across Word, Excel, and PowerPoint?

Yes. According to the source code, each document type implements the same IDocumentHandler interface, providing ViewAsText, Get, Set, Raw, and other methods. This consistency allows scripts written for one Office format to work across Word (WordHandler.cs), Excel (ExcelHandler.cs), and PowerPoint (PowerPointHandler.cs) with minimal modification.

How does OfficeCLI prevent document corruption when using raw XML?

OfficeCLI prevents corruption by isolating the raw layer (L3) as an explicit opt-in via Raw and RawSet methods, keeping most operations in the safer semantic (L1) and DOM (L2) layers. The architecture encourages users to remain in higher layers unless specific XML manipulation is required, reducing the risk of invalidating the OOXML package structure or breaking document relationships.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}