# How the OfficeCLI Diagram Compiler Converts Mermaid Flowcharts into Native Shapes

> Discover how the OfficeCLI diagram compiler converts Mermaid flowcharts into native editable Office shapes. Learn about its five-stage pipeline for seamless integration.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-08-10

---

**The OfficeCLI diagram compiler transforms Mermaid flowcharts into native editable Office shapes through a five-stage pipeline: detection, semantic parsing, geometric layout, native emission, and optional image fallback.**

The [iOfficeAI/OfficeCLI](https://github.com/iOfficeAI/OfficeCLI) repository provides a command-line interface for automating Microsoft Office documents, with its diagram compiler serving as the core engine that bridges text-based Mermaid diagrams and fully editable Word or PowerPoint graphics. Unlike simple image embedding, this compiler generates native Office DrawingML shapes that users can manipulate after generation.

## The Five-Stage Compilation Pipeline

The conversion process follows a sophisticated compiler architecture that moves from text representation to geometric layout to native Office objects.

### Stage 1: Mermaid Source Detection

The pipeline begins in [`src/officecli/Core/Diagram/DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/DiagramCompiler.cs), where the **`DiagramCompiler.Compile`** method inspects the first non-comment line of the input Mermaid text. This header detection determines the layout strategy:

- If the header matches `flowchart` or `graph`, the compiler delegates to **`FlowchartLayout.Layout`**
- If the header matches `sequenceDiagram`, it routes to **`SequenceLayout.Layout`**
- When no explicit header exists, the compiler defaults to flowchart mode (matching Mermaid's native behavior)

### Stage 2: Parsing to Semantic IR

Once the diagram type is identified, the selected layout invokes **`MermaidParser.Parse`** from [`src/officecli/Core/Diagram/MermaidParser.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/MermaidParser.cs). This parser tokenizes the Mermaid DSL and constructs a **`DiagramGraph`**—a semantic intermediate representation containing nodes (with `Id`, `Label`, and `Shape` properties) and edges (with `From`, `To`, and `Label` properties).

### Stage 3: Layout to Geometric IR

The semantic graph undergoes sophisticated layout algorithms depending on diagram type:

**Flowchart Layout** ([`src/officecli/Core/Diagram/FlowchartLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/FlowchartLayout.cs)): Implements a full **Sugiyama-style layered graph layout**, including cycle breaking, longest-path ranking, dummy-node insertion for edge routing, barycentric crossing reduction, Brandes-Köpf coordinate assignment, and final fit-to-canvas scaling.

**Sequence Diagram Layout** ([`src/officecli/Core/Diagram/SequenceLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/SequenceLayout.cs)): Uses a specialized algorithm for positioning lifelines and routing messages between participants.

Both algorithms output a **`LaidOutGraph`**—a geometric intermediate representation containing exact `X/Y/W/H` coordinates for every node and poly-line routes for every edge.

### Stage 4: Native Shape Emission

The geometric IR feeds into Office-specific handlers that instantiate native DrawingML objects:

- **Word Documents**: [`src/officecli/Handlers/Word/WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Add.Diagram.cs) iterates over `LaidOutGraph.Nodes`, creates shapes (rectangles, decision diamonds, cylinders) via the Word interop API, and draws routed edges as connectors.
- **PowerPoint Presentations**: [`src/officecli/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.Add.Diagram.cs) performs the same mapping for PPTX slides, ensuring shapes appear as native PowerPoint diagram elements.

### Stage 5: PNG Fallback

If the client requests `render=image` or the native renderer is unavailable, **`MermaidImageRenderer`** (located in [`src/officecli/Core/Diagram/MermaidImageRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Diagram/MermaidImageRenderer.cs)) renders the Mermaid source to PNG using the bundled Mermaid JS engine, embedding the raster image instead of native shapes.

## Command-Line Usage Examples

Generate native editable shapes in PowerPoint using the `--render native` flag:

```bash
officecli add my.pptx /slide[1] textbox \
  --prop text="flowchart TD; A[Start] --> B[Process] --> C[End]" \
  --prop size=32 --prop bold=true \
  --render native

```

Render the same chart as a static image fallback:

```bash
officecli add my.pptx /slide[1] textbox \
  --prop text="flowchart TD; A[Start] --> B[Process] --> C[End]" \
  --render image

```

Insert a flowchart as native shapes in Word:

```bash
officecli add my.docx /body \
  --type diagram \
  --prop text="flowchart LR; X[Input] --> Y[Output]" \
  --render native

```

## Programmatic API Access

Invoke the compiler directly from C# for custom automation workflows:

```csharp
using OfficeCli.Core.Diagram;

string mermaid = "flowchart TD; A[Start] --> B[Middle] --> C[End]";
LaidOutGraph graph = DiagramCompiler.Compile(mermaid);

// graph now contains positioned nodes & routed edges ready for Office APIs

```

## Summary

- **OfficeCLI** transforms Mermaid text into native Office shapes through a **semantic-to-geometric compilation pipeline**.
- **`DiagramCompiler.Compile`** in [`DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DiagramCompiler.cs) orchestrates the process by detecting diagram types and delegating to specialized layouts.
- **[`FlowchartLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FlowchartLayout.cs)** implements Sugiyama-style layered graph layout, while **[`SequenceLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SequenceLayout.cs)** handles lifeline diagrams.
- Output handlers in [`WordHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Diagram.cs) and [`PowerPointHandler.Add.Diagram.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.Add.Diagram.cs) convert the geometric IR (`LaidOutGraph`) into editable DrawingML shapes and connectors.
- **[`MermaidImageRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/MermaidImageRenderer.cs)** provides PNG fallback when native rendering is disabled or unavailable.

## Frequently Asked Questions

### What is the difference between native shapes and image rendering in OfficeCLI?

Native shapes produce editable DrawingML objects that users can manipulate in Word or PowerPoint—resizing, recoloring, and modifying text after generation. Image rendering (`--render image`) generates a static PNG bitmap using the bundled Mermaid JS engine, which cannot be edited as individual shapes but ensures compatibility when the Office interop APIs are unavailable.

### Which Mermaid diagram types does the OfficeCLI compiler support?

According to the source code in [`DiagramCompiler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DiagramCompiler.cs), the compiler explicitly supports **flowcharts** (including `graph` and `flowchart` keywords) and **sequence diagrams** (triggered by `sequenceDiagram` headers). When no header is detected, the compiler defaults to flowchart mode to maintain compatibility with standard Mermaid syntax.

### How does OfficeCLI determine the positioning of flowchart nodes?

The compiler uses a **Sugiyama-style layered graph layout algorithm** implemented in [`FlowchartLayout.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FlowchartLayout.cs). This algorithm performs cycle breaking to handle directed graphs, assigns ranks using longest-path layering, inserts dummy nodes for edge routing, reduces crossings via barycentric heuristics, and assigns coordinates using the Brandes-Köpf method before scaling to fit the target canvas dimensions.

### Can I use the OfficeCLI diagram compiler in my own .NET applications?

Yes. The compiler exposes a public API through the `OfficeCli.Core.Diagram` namespace. You can call `DiagramCompiler.Compile(string mermaidText)` to receive a `LaidOutGraph` object containing calculated coordinates and dimensions, then feed this data into your own rendering logic or use the built-in Word and PowerPoint handlers provided in the `officecli.Handlers` namespace.