# How OfficeCLI's Three-Layer Architecture Works: L1, L2, and L3 Explained > Unlock OfficeCLI's power with its three layer architecture. Understand L1 semantic views, L2 DOM manipulation, and L3 raw XML access for efficient document automation. See how it works. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: architecture - Published: 2026-07-28 --- **OfficeCLI employs a progressive three-layer architecture where L1 provides semantic read-only views, L2 offers DOM-like element manipulation, and L3 enables direct XPath access to raw Office XML, allowing users to choose the appropriate abstraction level for their document automation tasks.** The iOfficeAI/OfficeCLI repository implements this design to balance ease of use with fine-grained control over Word, Excel, and PowerPoint files. Understanding how these layers interact helps developers and AI agents select the right API for everything from quick content extraction to complex document surgery. Each layer builds upon the previous one, creating a **progressive abstraction** that keeps simple tasks simple while providing escape hatches for advanced scenarios. ## Overview of the OfficeCLI Three-Layer Architecture The architecture divides document operations into three distinct levels of abstraction, documented in [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) around line 342. As you move from L1 to L3, you trade convenience for power, gaining the ability to manipulate increasingly low-level document structures. The layers follow a **progressive disclosure** pattern: - **L1 (Read)** handles high-level, human-readable outputs - **L2 (DOM)** exposes structured element models for query and mutation - **L3 (Raw XML)** provides direct access to the underlying Office Open XML This design ensures that common operations require minimal complexity, while edge cases remain accessible through lower-level APIs. ## Layer 1 (L1): Semantic Read Operations **Layer 1** focuses exclusively on **semantic views** of documents—high-level representations that are easy for humans and AI agents to consume without parsing raw XML. ### Purpose and Commands According to the architecture documentation in `README.md#L342`, L1 provides read-only operations that render documents as plain text, outlines, annotated HTML, or statistical summaries. The primary command is `view`, which accepts format modifiers to control output. L1 is ideal for content extraction, document summarization, and quick inspections where you need to understand document structure without modifying it. ### L1 Code Example To render a PowerPoint presentation as high-fidelity HTML for visual inspection: ```bash officecli view deck.pptx html ``` For an annotated view of a Word document that highlights structural elements: ```bash officecli view report.docx annotated ``` ## Layer 2 (L2): Structured DOM Manipulation **Layer 2** exposes a **DOM-like representation** derived from the Office XML, enabling fine-grained element manipulation while abstracting away raw XML complexity. ### Purpose and Commands As documented in `README.md#L345`, L2 supports the full CRUD lifecycle for document elements: `get`, `query`, `set`, `add`, `remove`, `move`, and `swap`. This layer treats document elements as addressable objects with properties, similar to web DOM manipulation. L2 strikes the balance between expressiveness and safety, handling XML namespace management and structural validation automatically while allowing precise modifications to paragraphs, shapes, slides, and other Office elements. ### L2 Code Example To update a paragraph's formatting in a Word document: ```bash officecli set report.docx /body/p[1] --prop bold=true ``` To add a new shape to a specific slide in a PowerPoint deck: ```bash officecli add deck.pptx /slide[1] --type shape --prop text="Revenue ↑" ``` ## Layer 3 (L3): Raw XML Access **Layer 3** operates directly on the **raw Office XML** using XPath expressions, acting as a universal fallback when higher-level operations cannot express a needed change. ### Purpose and Commands Documented in `README.md#L346`, L3 commands include `raw`, `raw-set`, `add-part`, and `validate`. This layer bypasses all abstractions, requiring you to understand Office Open XML schema details and namespace prefixes. L3 is the most powerful—and riskiest—layer. Use it when you need to inject custom XML parts, manipulate esoteric document properties, or perform transformations that the DOM layer cannot represent. ### L3 Code Example To directly inject a new run into the first paragraph using XPath: ```bash officecli raw-set report.docx document --xpath "//w:p[1]" --action append --xml 'Injected text' ``` ## How the Layers Interact in Practice The coupling between layers becomes concrete in OfficeCLI's watch-mode implementation. In [`src/officecli/Core/Watch/WatchServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchServer.cs) (lines 81-86), Layer 1 handles Server-Sent Events (SSE) and DOM updates, while Layer 2 adds UI overlays including selection boxes and CSS injection. The interaction works through an explicit hook mechanism: 1. **Layer 1** (implemented in [`src/officecli/Resources/watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js)) manages the SSE connection and DOM diff/patch logic 2. After each DOM mutation, Layer 1 calls `window._watchReapplyHook()` 3. **Layer 2** (implemented in [`src/officecli/Resources/watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-overlay.js)) provides this hook to re-apply visual decorations This architecture ensures that real-time document previews remain synchronized while allowing UI enhancements to operate independently of the core synchronization logic. ## Summary - **OfficeCLI's three-layer architecture** provides progressive abstraction from semantic views (L1) to DOM manipulation (L2) to raw XML (L3) - **L1 commands** like `view` offer read-only, human-readable outputs suitable for content extraction - **L2 commands** including `set`, `add`, and `remove` provide structured element manipulation without XML complexity - **L3 commands** such as `raw-set` enable direct XPath access for edge cases requiring precise XML control - **Layer interaction** is demonstrated in [`WatchServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WatchServer.cs), where L1 handles data synchronization and L2 manages UI overlays through the `_watchReapplyHook()` mechanism ## Frequently Asked Questions ### What is the difference between L2 and L3 in OfficeCLI? **L2 provides a DOM-like abstraction** that handles XML namespaces and structural validation automatically, while **L3 requires manual XPath expressions** and raw XML manipulation. Use L2 for standard element operations like updating text or formatting; use L3 only when you need to inject custom XML parts or manipulate document structures that the DOM API cannot access. ### When should I use Layer 1 instead of Layer 2? Use **L1 when you only need to read or view document content** without modifying it, such as extracting text for analysis or generating HTML previews. L1 is read-only and optimized for semantic understanding. Switch to L2 when you need to modify document elements, as L1 does not support mutation operations. ### How does OfficeCLI handle real-time document updates? OfficeCLI implements real-time updates through a **watch-mode server** defined in [`src/officecli/Core/Watch/WatchServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchServer.cs). Layer 1 manages the SSE connection and core DOM synchronization via [`watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js), while Layer 2 adds visual overlays through [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js). The layers communicate via `window._watchReapplyHook()`, ensuring UI decorations persist across document mutations. ### Is Layer 3 safe to use for production documents? **Layer 3 is powerful but risky** because it bypasses all validation and safety checks present in L2. Direct XML manipulation can corrupt document structure, break relationships between parts, or create invalid Office Open XML that applications cannot open. Always validate documents after L3 operations using the `validate` command and maintain backups before performing raw XML modifications.