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

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 and 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, 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 and 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.
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:

# 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#:

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, demonstrating how the Application layer orchestrates Infrastructure operations.

Key Source Files

Understanding the architecture requires familiarity with these specific files:

• Program.cs: The application entry point that wires the CLI parser to the handler dispatcher.
• CommandBuilder.Add.cs and CommandBuilder.Refresh.cs: Contain all CLI parsing logic for constructing command objects.
• WordHandler.cs: Central hub for Word-specific commands; routes requests to sub-handlers.
• WordHandler.Add.Table.cs: Implements the add table operation by constructing Open XML table parts.
• BlankDocCreator.cs: Creates minimal .docx packages when target files do not exist.
• ResidentServer.cs and ResidentClient.cs: Provide the live preview server that streams document changes to UIs.
• 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 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, 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, 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.

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