User Guide

Getting Started

Diagrix is a native macOS app for structured project planning. It combines thirteen diagram and analysis modules in a single window, saves documents in an open JSON format (.diagrix), and provides an MCP server through which AI assistants can directly access all content.

System Requirements

Launching the App

The app is started as a macOS application bundle. On first launch, an empty document opens with the SWOT module active. Select the desired module from the left sidebar.

Main Window

The main window consists of three areas: toolbar (top), sidebar (left), and module content (right).

Toolbar

Sidebar

Clicking a module instantly switches the view. Hovering over a module shows a short description as a tooltip. At the bottom of the sidebar is the language selector — switches between English, German and French without restarting the app — along with the installed version (e.g. “Diagrix 1.0.0.171”).

Documents

New, Open, Save

Documents are saved in the .diagrix format (JSON). Each file contains exactly one active module.

Auto-Save

Once a file has been saved, the app automatically saves every 2 minutes when there are unsaved changes.

Settings ⌘,

Settings open as a sheet via the ⚙ button in the toolbar or by pressing ⌘,. They contain five sections.

Appearance

Choose between System (follows macOS), Light and Dark.

Diagram Theme

Six color palettes determine which colors new nodes in Flowchart, UML and ERD automatically receive:

Grid

The grid applies to: Flowchart, UML, ERD, C4, Arc42 Diagram, MindMap.

Manage Modules

Enable or disable individual modules. At least one module must remain active; MindMap is always active.

Export & import languages

Diagrix ships with German, English and French. Via Settings → Languages you can add more languages as an Excel file (.xlsx) or correct existing ones — no coding required.

Empty target cells are filled automatically with the English translation. Unmappable keys and all English fallbacks are recorded in a log file next to the Excel file.

Help languages (help packs)

The in-app help is built in for German. The help window (top right) has a language picker and a ••• menu with export/import — like the interface languages, but as separate .xlsx help packs. Ready-made packs (e.g. English) are in the download area.

A help pack only applies to the matching app version; missing texts fall back to German automatically.

Font per Diagram Type

Click the Aa icon in the module toolbar. A popover opens:

Canvas Interaction

The following interactions apply to all canvas modules: Flowchart, C4, ERD, UML, Arc42 Diagram.

Selection & Drag

Keyboard

Navigation & Zoom

Right-Click Context Menu

• Nothing selected — Select all, Auto-layout
• 1 element selected — Duplicate, Delete
• Multiple selected — Delete N elements

Inline Editing

• Double-click on a node → Edit the label directly on the canvas
• Enter or click outside → Confirm change
• Escape → Discard change

Collision Detection

In Flowchart, UML, ERD, C4 and Arc42 Diagram, dragging prevents shapes from overlapping:

• Sliding along edge: If one axis is blocked, the other can still be used
• Already overlapping shapes (e.g. placed via MCP) can freely move out of the overlap
• Visual feedback: Blocking shapes are briefly highlighted with a red dashed border

Edges, Waypoints & Labels

All diagram modules with connections support individual edge styles. Select an edge → the style editor appears in the right properties panel.

Edge Style

Waypoints

Waypoints shape the edge path freely. They appear as white circles with a colored border and are always in the foreground — even when they lie on top of a node.

Waypoints are available in: Flowchart, UML, ERD, C4, Arc42 Diagram, BPMN.

Labels

Edges can be labelled directly on the canvas. The label sits centred on the edge by default and can be moved freely — the offset appears identically in the PNG/JPEG and HTML export.

Labelling is available in all edge modules: Flowchart, UML, ERD, C4, Arc42 Diagram, BPMN, Sequence Diagram.

Auto-Layout

In Flowchart, UML, ERD, C4 and Arc42 Diagram, the Auto button in the toolbar arranges all elements automatically.

Process

1. Click Auto in the toolbar (or right-click → Auto-Layout)
2. The layout engine analyzes the graph structure
3. No cycles in graph → hierarchical layer layout (Sugiyama)
4. Graph contains cycles → force-directed layout (Fruchterman-Reingold)
5. After layout, groups are compressed and remaining overlaps are resolved

Groups

Groups are available in Flowchart, UML, ERD, C4 and Arc42. They visually enclose and label related elements.

Creating a Group

Click Group in the toolbar, then drag an area on the canvas.

Properties

Containment

An element automatically belongs to a group when its center point lies within the group rectangle. Auto-Layout keeps contained elements together.

1. MindMap

Hierarchical mind map with unlimited depth, cross-links, themes and inline editing.

Right panel: label, notes, text alignment, theme. Auto-layout via Auto button.

2. SWOT Analysis

Classic 2×2 matrix for Strengths, Weaknesses, Opportunities and Threats.

• + button in the quadrant header → Add new entry
• × button on hover → Delete entry
• Changes are automatically saved when leaving the field

3. Business Model Canvas

Nine sections of the Business Model Canvas with direct inline input.

• + button in the section header → Add new entry
• Changes are automatically saved when leaving the field

4. Kanban Board

Professional Kanban board with sprint planning, swimlanes, time tracking and bidirectional Gantt synchronization.

• Move cards between columns via drag & drop
• New card → title field immediately editable
• Priorities: Low / Medium / High / Critical
• Tags as free-text chips
• Optional WIP limit per column
• Double-click on column title to rename
• Sprint labels, swimlanes and dependencies (blocks / blocked by)
• Time tracking: Estimated / Logged
• Bidirectional synchronization with the Gantt chart

5. Gantt Chart

Interactive Gantt chart with drag-to-move, zoom levels and bidirectional Kanban synchronization.

Right panel: name, start day, duration, color.

6. Fishbone Diagram (Ishikawa)

Cause-and-effect diagram with configurable categories.

• + Top / + Bottom → Add new category
• System picker → 6M, 4M, 4P or custom
• Click on category → Edit causes in the right panel
• Category labels and causes save on focus loss
• Drag category label → Reposition the category along the spine; cause layout adjusts automatically

7. Sequence Diagram

Participants and messages in chronological order.

Message types: Synchronous (→), Asynchronous (⇢), Return (--→). From/To fields prevent the same participant as source and target.

8. arc42

Complete arc42 template with 12 chapters, status tracking and an integrated diagram editor.

• Chapter status: Empty / Draft / Done
• Each chapter has three tabs: Text, Preview and Diagram
• Preview tab — Live rendering of the Markdown text (headings, lists, code blocks, bold/italic)
• Chapter diagrams: full canvas interaction with all shortcuts
• Drag-to-Connect: in connection mode, drag from a node to create an edge — a rubber-band line shows the connection path
• Auto button in the diagram toolbar: arrange nodes automatically
• Group button: create group rectangle or ellipse

9. Flowchart

Flow diagrams per ISO 5807 with full canvas interaction.

• Connection mode: click "Connect" button, then click source → target
• Edges with optional label
• Auto button: arrange nodes automatically
• Group button: create group rectangle or ellipse
• Shape palette (right): drag & drop shapes onto the canvas

10. C4 Model

Hierarchical architecture model with context, container and component diagrams.

• Multiple diagrams per document (Context → Container → Component)
• Shape palette (right): drag & drop shapes onto the canvas — automatically limited to the active level (Context: 4, Container: 8, Component: 6 shapes)
• Level linking: "References level" in properties panel → right-click → "Go to referenced level"

11. ER Diagram

Entity-relationship model in relational and Chen notation.

• Columns: name, type, PK / NOT NULL / UNIQUE
• Cardinalities: 1, n, 0..1, 0..n, 1..n
• Auto button: arrange entities automatically
• Shape palette (right): drag & drop shapes onto the canvas

12. UML Diagram

Class, object, component and state machine diagrams.

• Relationships: Association, Dependency, Generalization, Realization, Composition, Aggregation
• Attributes and methods editable (one per line)
• Auto button: arrange nodes automatically
• Shape palette (right): drag & drop shapes onto the canvas

13. BPMN Process

Business process diagrams per BPMN 2.0 (ISO 19510) — the standard for ERP modeling.

• Connect button + type selector (Sequence / Message / Association) in the toolbar
• Auto button: arrange elements automatically (pools and lanes remain fixed)

In-App Help

The complete help is available directly in the app: Menu Help → Diagrix Help (or via the Help menu in the macOS menu bar).

The help window opens as a standalone window and can remain open while working in the app.

Export

MCP Server

Diagrix automatically starts a local MCP server (default port 3001). AI assistants like Claude can use it to directly access all 13 modules — read, create, edit, delete. By default the server is only reachable on your own Mac (bound to 127.0.0.1).

Server settings

Under Settings → MCP Server:

Security: the server has no built-in limits and can modify documents. Keep the token secret when allowing external access.

Setup (Claude Desktop)

{
  "mcpServers": {
    "diagrix": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/sse"
      ]
    }
  }
}

Available Tool Categories