# How OfficeCLI's Three-Layer Architecture Works for Document Manipulation

> Learn how OfficeCLI's three-layer architecture streamlines document manipulation. Understand its separation of concerns for reliable terminal-based operations. Explore the iOfficeAI/OfficeCLI repository today.

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

---

**OfficeCLI employs a three-layer architecture that separates command-line parsing, business logic, and Open XML operations to enable reliable document manipulation from the terminal.**

The iOfficeAI/OfficeCLI repository organizes its document manipulation capabilities into a clean three-layer architecture. This design separates concerns between the user interface, application logic, and low-level document operations, making the codebase maintainable and extensible for Word, Excel, and PowerPoint automation.

## The Three Layers of OfficeCLI

### Presentation Layer (CLI)

The **Presentation layer** handles user input through the `CommandBuilder` classes. These classes tokenize command-line arguments and translate them into internal request objects. Located in files like [`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs) and [`CommandBuilder.Refresh.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Refresh.cs), this layer includes specialized builders such as `CommandBuilder.Add`, `CommandBuilder.Refresh`, and `CommandBuilder.Mark` that construct the command tree needed for execution.

### Application Layer (Handler)

The **Application layer** contains the business logic that interprets requests and validates arguments. The `WordHandler` class serves as the central hub, routing commands to specific sub-handlers like `WordHandler.Set` and `WordHandler.Add`. According to the source code in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), this layer delegates complex operations to helper classes—for example, `WordHandler.Add.Table` handles table construction logic while remaining agnostic to the underlying Open XML implementation.

### Infrastructure Layer (Document)

The **Infrastructure layer** directly manipulates Office Open XML files. Key components include `BlankDocCreator` for generating minimal `.docx` packages, and `ResidentServer` with `ResidentClient` for streaming real-time updates to preview UIs. As implemented in [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs) and [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), this layer handles file I/O, XML injection, and package management without exposing these details to upper layers.

## How the Layers Interact

When a user executes a command, the three layers process the request through a strict hierarchy:

1. **User Input**: The command `officecli add table --rows 3 --cols 4 mydoc.docx` enters the Presentation layer.
2. **CLI Parsing**: `CommandBuilder.Add` tokenizes the arguments and builds a `Command` object, forwarding it to the dispatcher in [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs).
3. **Business Logic**: The Application layer's `WordHandler` inspects the command type (`Add.Table`), validates parameters, and delegates to `WordHandler.Add.Table` to construct the appropriate Open XML elements.
4. **Document Modification**: The Infrastructure layer creates or opens the file via `BlankDocCreator`, injects the table XML into the document package, and writes changes to disk. If enabled, `ResidentServer` streams updates to connected clients.

This unidirectional flow ensures that Presentation knows only about Application abstractions, while Application knows only about Infrastructure capabilities.

## Code Examples

### Adding a Table from the Command Line

The simplest way to interact with the architecture is through the CLI:

```bash

# Add a 3×4 table to the end of "proposal.docx"

officecli add table --rows 3 --cols 4 proposal.docx

```

Behind the scenes, `CommandBuilder.Add` parses this into a structured request that `WordHandler.Add.Table` executes against the document infrastructure.

### Using the API Programmatically

You can bypass the CLI and interact with the layers directly in C#:

```csharp
using OfficeCli;

// 1. Load or create the document (Infrastructure layer)
var doc = BlankDocCreator.CreateOrOpen("proposal.docx");

// 2. Build a table request (Application layer)
var tableReq = new WordHandler.Add.Table
{
    Rows = 3,
    Columns = 4,
    Location = WordHandler.Add.TableLocation.EndOfDocument
};

// 3. Execute the request via the handler
WordHandler.Execute(tableReq, doc);

// 4. Save the changes
doc.Save();

```

This example mirrors the internal flow found in [`WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Table.cs), demonstrating how the Application layer orchestrates Infrastructure operations.

## Key Source Files

Understanding the architecture requires familiarity with these specific files:

- **[`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs)**: The application entry point that wires the CLI parser to the handler dispatcher.
- **[`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs)** and **[`CommandBuilder.Refresh.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Refresh.cs)**: Contain all CLI parsing logic for constructing command objects.
- **[`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs)**: Central hub for Word-specific commands; routes requests to sub-handlers.
- **[`WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Table.cs)**: Implements the `add table` operation by constructing Open XML table parts.
- **[`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs)**: Creates minimal `.docx` packages when target files do not exist.
- **[`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)** and **[`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs)**: Provide the live preview server that streams document changes to UIs.
- **[`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs)**: Handles batched mutations for efficiency when applying multiple edits.

## Summary

- **OfficeCLI's three-layer architecture** separates CLI parsing (Presentation), business logic (Application), and Open XML manipulation (Infrastructure).
- **CommandBuilder classes** in the Presentation layer translate terminal arguments into structured `Command` objects.
- **WordHandler** serves as the Application layer's router, validating requests and delegating to specialized helpers like `WordHandler.Add.Table`.
- **Infrastructure components** such as `BlankDocCreator` and `ResidentServer` handle low-level document creation and streaming without exposing complexity to upper layers.
- Each layer communicates only with the layer directly below it, enabling independent testing and extension of the codebase.

## Frequently Asked Questions

### What is the role of the CommandBuilder in OfficeCLI?

The `CommandBuilder` classes form the Presentation layer, responsible for parsing command-line arguments and constructing internal `Command` objects. Files like [`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs) contain the logic for tokenizing user input and building the command tree that gets passed to the Application layer.

### How does WordHandler process document manipulation requests?

`WordHandler` acts as the Application layer's central router. It receives requests from the Presentation layer, validates arguments, and delegates to specific sub-handlers such as `WordHandler.Add.Table`. According to the source code in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), this design keeps business logic separate from both CLI parsing and low-level XML manipulation.

### What is the purpose of the ResidentServer in the Infrastructure layer?

`ResidentServer`, defined in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), provides a live preview capability by streaming document changes to connected clients. It works alongside `ResidentClient` to enable real-time updates in preview UIs while the Infrastructure layer performs the actual file modifications on disk.

### Can I use OfficeCLI's application layer without the CLI?

Yes. The Application and Infrastructure layers are accessible directly via C# APIs, as shown in the programmatic example above. You can instantiate `BlankDocCreator` and `WordHandler` classes independently, allowing you to embed OfficeCLI's document manipulation logic into custom applications without invoking the command-line parser.