How OfficeCLI's Three-Layer Architecture (L1, L2, L3) Facilitates Document Operations

OfficeCLI's three-layer architecture separates document operations into Semantic (L1), Query (L2), and Raw (L3) layers, enabling users to interact with Office documents at high, medium, or low abstraction levels depending on their technical requirements.

The iOfficeAI/OfficeCLI repository implements a clean separation of concerns across all document handlers for Word, Excel, and PowerPoint. This OfficeCLI three-layer architecture is defined in the core interface IDocumentHandler and referenced throughout the codebase, including in WatchServer.cs. By isolating operations into distinct abstraction levels, the architecture allows both casual users and advanced developers to manipulate Office documents effectively without compromising stability or flexibility.

Understanding the Three-Layer Architecture

The architecture divides every document operation into three distinct tiers, each serving different user needs and technical capabilities.

Semantic Layer (L1): Human-Readable Abstractions

The Semantic Layer provides high-level, user-friendly views of documents by abstracting underlying XML into readable formats. Located in src/officecli/Core/IDocumentHandler.cs at lines 58-74, this layer handles operations like view text, view outline, view stats, and view annotated.

When users need to extract content without understanding OpenXML structure, the Semantic Layer translates complex document markup into plain text or structured outlines. This eliminates the need for users to parse XML manually while still providing access to document content and metadata.

Query Layer (L2): Programmatic Document Manipulation

The Query Layer exposes a structured API for querying, retrieving, and mutating document parts using paths and selectors. Defined in IDocumentHandler.cs at lines 81-97, this layer supports operations including get, query, set, add, remove, move, and copy.

This layer returns JSON or object models, offering a balanced approach between usability and precision. Users can target specific document elements via XPath-like selectors while working with logical abstractions rather than raw XML nodes.

Raw Layer (L3): Direct XML Access

The Raw Layer provides direct access to OpenXML markup for scenarios requiring exact manipulation. Found in IDocumentHandler.cs at lines 98-101, this layer implements methods like raw, rawset, and addpart.

When higher layers lack specific functionality or when plugins need to implement custom behaviors, the Raw Layer serves as a safety valve. Advanced users can read or edit underlying XML parts directly, ensuring the system remains extensible for edge cases.

How the Layers Facilitate Different Operations

The layered design creates clear boundaries that benefit the entire OfficeCLI ecosystem:

• User-Facing Simplicity – The Semantic layer hides technical complexity, allowing users to request human-readable representations without XML knowledge.
• Programmable Flexibility – The Query layer enables precise targeting of document elements through selectors while maintaining logical document models.
• Full Control – The Raw layer permits exact XML manipulation when standard APIs prove insufficient.

This separation ensures that changes in one layer rarely propagate to others, maintaining system stability while enabling independent testing and extension.

Implementation in the Core Interface

The IDocumentHandler interface in src/officecli/Core/IDocumentHandler.cs formalizes this three-layer contract that all document handlers must implement. Whether processing Word documents (WordHandler), PowerPoint presentations (PowerPointHandler), or Excel spreadsheets (ExcelHandler), each handler provides concrete implementations of L1, L2, and L3 operations.

The interface definition ensures consistency across document types. For example, the Set method in the Query Layer behaves predictably whether modifying a Word heading or a PowerPoint slide title, while the ViewAsText method in the Semantic Layer produces consistent output formats across different Office applications.

Real-World Usage Examples

The following C# snippets demonstrate how consumers interact with each layer through the IDocumentHandler interface:

// Assume `handler` is an IDocumentHandler for a .docx file.

// 1️⃣ Semantic layer – get a clean text view.
string plainText = handler.ViewAsText(startLine: 1, maxLines: 50);

// 2️⃣ Query layer – change the title of a slide (PowerPoint) or a heading (Word).
var setResult = handler.Set("/slide[1]/title", new Dictionary<string, string>
{
    ["text"] = "Quarterly Report"
});

// 3️⃣ Raw layer – directly edit the underlying XML of a chart part.
handler.RawSet(
    partPath: "/ppt/charts/chart1.xml",
    xpath: "/c:chart/c:title/c:tx/c:rich/c:p/c:r/c:t",
    action: "replace",
    xml: "<t>Q1 Sales</t>"
);

These examples show the progression from high-level content extraction to precise XML manipulation, illustrating how the same handler instance supports multiple abstraction levels.

Integration with the Watch Subsystem

The three-layer architecture extends beyond static document manipulation into the live-editing subsystem. In src/officecli/Core/Watch/WatchServer.cs at lines 91-94, comments enumerate the same three layers, demonstrating how the server routes changes from low-level SSE updates through overlay decorations to UI hooks.

This architectural consistency ensures that real-time document updates follow the same abstraction principles as batch operations. The watch subsystem leverages Layer 1 for user display updates, Layer 2 for structured change tracking, and Layer 3 for direct XML modifications when necessary.

Summary

• OfficeCLI's three-layer architecture separates document operations into Semantic (L1), Query (L2), and Raw (L3) tiers, defined in IDocumentHandler.cs.
• Semantic Layer methods like ViewAsText provide human-readable document views without requiring XML knowledge.
• Query Layer operations including Set, Get, and Query enable programmatic manipulation using selectors and paths.
• Raw Layer functions such as RawSet offer direct OpenXML access for advanced scenarios requiring exact markup control.
• The architecture appears consistently across Word, Excel, and PowerPoint handlers, as well as in the WatchServer.cs live-editing subsystem.
• This separation enables independent testing, plugin extensibility, and stable maintenance across the iOfficeAI/OfficeCLI codebase.

Frequently Asked Questions

What is the primary purpose of OfficeCLI's three-layer architecture?

The architecture isolates document operations by abstraction level, allowing casual users to extract content through the Semantic Layer while enabling developers to perform precise manipulations via the Query and Raw layers. This separation prevents technical complexity from overwhelming simple use cases while preserving advanced functionality for power users.

How does the Query Layer differ from the Raw Layer in OfficeCLI?

The Query Layer (L2) provides a structured API with methods like Set and Query that work with logical paths and return object models or JSON, whereas the Raw Layer (L3) exposes direct XML manipulation through methods like RawSet that require knowledge of OpenXML markup and exact XPath expressions.

Can plugin developers extend only specific layers of the architecture?

Yes, plugins can interact with the OfficeCLI three-layer architecture at whichever level suits their requirements. The interface design in IDocumentHandler.cs allows extensions to leverage high-level Semantic methods for content extraction, Query methods for structured modifications, or Raw methods for custom XML operations without affecting other layers.

Where is the three-layer architecture implemented in the OfficeCLI source code?

The architecture is formally defined in src/officecli/Core/IDocumentHandler.cs with specific method signatures for each layer at lines 58-74 (Semantic), 81-97 (Query), and 98-101 (Raw). Concrete implementations appear in src/officecli/Handlers/Word/, src/officecli/Handlers/Pptx/, and src/officecli/Handlers/Excel/, while the watch subsystem in src/officecli/Core/Watch/WatchServer.cs applies the same layering to live-editing scenarios.

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