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

> Understand OfficeCLI's three-layer architecture L1 Read, L2 DOM, and L3 Raw XML for safe high-level and precise low-level Office document manipulation.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: architecture
- Published: 2026-07-25

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main//word/footnotes.xml), as documented in [`schemas/help/docx/raw.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) for Word documents
- [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs) for Excel spreadsheets
- [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
officecli view text report.docx

```

### L2 DOM Examples

Retrieve a specific paragraph:

```bash
officecli get report.docx /paragraph[3]

```

Modify paragraph properties:

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

```

### L3 Raw XML Examples

Read the raw XML of the main document part:

```bash
officecli raw report.docx /document

```

Remove the first paragraph using XPath:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs)), Excel ([`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs)), and PowerPoint ([`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.