Diagrams

Overview

A diagram in Holarch is a view of a root entity and the entities and relationships around it. It is not a separate drawing: adding a shape creates or links an entity, drawing a line creates a relationship, and deleting can remove the link, the entity, or only the shape. Every change is one undo step and is saved with the project.

Holarch has 28 diagram types in three categories:

This page covers the Diagrams page and the editor that all of them share. Each type has its own page: Action Diagrams, Functional Analysis (FFBD), SysML Diagrams, Other Diagrams and Whiteboards.

Concepts

• Root entity. Every diagram belongs to one entity: an Action Diagram to an Action, a BDD to an Asset, a Requirement Diagram to a Requirement or document. The diagram's name, number and description are the root's. One entity can have one diagram of each type that applies to its class, and the Diagram type selector switches between them.
• Saved diagrams and derived views. A diagram is saved once someone has opened or edited it. Holarch also offers derived views: a Hierarchy, Spider, Action or Asset Diagram for every top-level entity with children, listed before anyone opens them. Opening a derived view saves it.
• Model and layout. Entities and relationships live in the model. Positions, sizes, colors, line styles, hidden items, zoom and annotations are layout, saved per diagram. Deleting a diagram removes only the layout.
• Annotations. Notes, text, shapes, pictures, legends and title blocks drawn on a diagram. They are layout, never entities, so they never change the model.
• The inspector. Selecting a shape or line shows its details on the right: the entity's name, number, description, attributes and relationships, or the relationship's line type and attributes.

How to use it

When and why

Use diagrams to build and communicate the model at each step of the systems engineering process: requirement and spider diagrams while capturing and tracing requirements, Action Diagrams and FFBDs for behavior, Asset Diagrams, BDDs and IBDs for structure, ICDs and N² Diagrams for interfaces, Risk and Timeline Diagrams for management. Because diagrams edit the model, you can build the model directly on a diagram and see the result in the Database, documents and matrices at once.

Create a diagram

1. Click Diagrams at the bottom of the navigation rail (or a group's overview page, or a diagram page such as Behavior → Action Diagrams).
2. Click + Create Diagram in the top bar. To build the diagram on an entity you already have, click ▾ → Create from Existing Entity instead.
3. In Choose Which Type of Diagram to Create, filter with All, General, LML or SysML and click a type card. Each card shows the type's description.
4. For a new root, Specify New Root asks for the Root Entity Class (only classes the type applies to), Number, Name and Description, and says Enter a name or a number. Click Create. For an existing root, pick it in the entity picker.

Result: the diagram opens in the editor and appears on the Diagrams page.

Open a diagram

• Click its tile on the Diagrams page.
• In an entity's inspector or Entity View, click Open ▾ and choose the diagram type.
• Use ⌘K (Search) and type the diagram's root name.
• Click its editor tab under the top bar; open diagrams stay as tabs per project.
• In an open diagram, choose another type in the Diagram type selector (same root), or click ▲ Parent (same type, parent entity).

A typical editing session

1. Drag a class or construct from the palette onto the canvas, or onto an existing shape to relate them. Result: a new entity, related to the root or to the target.
2. Select the new shape and type its name in the inspector.
3. Point at a shape and drag its green connect handle to another shape. If several relationships are allowed, choose one. Result: a relationship and a line.
4. Select several shapes with Shift-click or a box selection, then use the format tools (where the type has them) to align them, give them the same size, or color them.
5. Add a Note from Annotations to explain a choice, and a Title Block before exporting.
6. Choose Export ▾ → Opaque Image (PNG) or Microsoft Word (DOCX) to share it.

Worked example: the CubeSat EO-1 demo

Create the demo project (Manage Projects → Project Files ▾ → Create Demo Project) and open Diagrams. The status line under the tiles reads, for example, 59 diagrams · 31 saved · 28 derived views.

1. Choose Action Diagrams Only in the type filter and open OPS Run Nominal Imaging Pass.
2. In the Diagram type selector in the top bar, choose Sequence Diagram. Result: the same Actions as lifelines and messages; the Action Diagram is still one click away in the selector or the editor tabs.
3. Back on the Diagrams page, type EO-1 Spacecraft in Search diagrams… and open its Asset Diagram. Select a conduit: the inspector shows the Conduit entity with the Input/Outputs it transfers.
4. Select three assets with Shift-click (or Shift+drag a box around them) and click ☰ Align Horizontally in the format tools; the first asset you selected stays put.
5. Choose Export ▾ → Microsoft Word (DOCX). Result: a Word file with the diagram, its name as caption and the root's description.
6. On the Diagrams page, choose Report… with the type filter set to Showing All Diagrams for one Word file with every diagram.

Tips and good practice

• Name the root before you build: the name becomes the diagram's title, export file name and tile name.
• Keep one diagram per question. Use several diagram types of the same root rather than one crowded diagram.
• Use annotations, not entities, for explanations and title blocks, so the model stays clean.
• Remove from Diagram hides a shape without deleting the entity; Delete from Database removes the entity from the whole project. Read the dialog before choosing.
• Colors and fonts set with the format tools apply to this diagram only. Class colors come from the schema.
• Exports always use the light theme, whatever theme the app shows.

Common mistakes

How it connects to other features

• Diagrams read and write the same entities and relationships as the Database, documents, matrices and registers.
• Diagram images appear in documents, presentations, review packages and the Diagrams Report, rendered from the saved layout.
• The Simulator runs Action Diagrams; Functional Analysis writes the flow that Action Diagrams and FFBDs show.
• Comments on an entity selected in a diagram are the same comments as in its Entity View.

The Diagrams page

Open it with Diagrams at the bottom of the rail. Each diagram is a tile.

Top bar

• Report…: the Diagrams Report (below), of the diagrams in the current filter and sort.
• + Create Diagram and its ▾: Create Diagram (Default) and Create from Existing Entity.

View bar

Under the tiles: N diagrams · N saved · N derived views (with shown when filtered), ‹ Prev, Page N of M and Next ›.

Tiles

A tile shows the diagram type, the root's class badge, a thumbnail, the root's number and name, its description (No description. when empty), Derived view for views nobody has opened yet, the root's labels and the date the diagram was last changed. Click a tile to open the diagram.

⋯ on a tile:

Select and delete several diagrams

Tick a tile's checkbox, or ⌘-click or Shift-click tiles (Shift selects a range). The selection bar shows N selected, Select page/Deselect page, Select all N, Clear, the hint Click tiles to add or remove; Esc clears and Delete N…. Esc clears the selection.

The delete dialog (Delete type or Delete N diagrams) explains both choices:

• Delete Diagram (Delete Diagrams) removes the diagram and its saved layout; the root entities and their relationships stay in the database.
• Delete Diagram and Root Entity (Delete Diagrams and Root Entities) also deletes the root entities and their relationships; child entities are kept.

Both can be undone with ⌘Z. A deleted derived view no longer appears until you open that diagram again.

Diagrams Report

Report… builds one file with every diagram in the current filter and sort (N diagrams from the current filter and sort. The diagram image is always included.):

• Fields: Name, Number, Description, Diagram Type (on by default), Created On, Modified On.
• File name: default project Diagrams Report, 100 characters at most.
• Format: Microsoft Word (DOCX) or Web Page (HTML).

Run Report shows Building report… and then Report downloaded. Messages: No diagrams to report., Enter a file name., File name must be 100 characters or fewer.

The diagram editor

The editor has four parts: the toolbar row, the palette on the left, the canvas, and the inspector on the right.

Top bar

• Diagram type: every type that applies to the root's class. Choosing one opens that diagram of the same root.
• ▲ Parent: the same diagram type for the root's parent. Shown only when the root has a parent of a suitable class.

Toolbar

One row, in a fixed order of groups:

When the row is too narrow, items move into ⋯ (More actions (N hidden for space)) under their group headings, starting with type actions, then view, insert, output and edit items. ⚙ and Export ▾ always stay in the row. Below the overflowed items, ⋯ lists Open Entity View, All Diagrams, Help for type and Delete Diagram….

The type's AI tools are not in the toolbar: they are listed under ✦ AI ▾ in the top bar.

⚙ Diagram settings

The menu starts with Settings and lists, when the type offers them:

• Layout Diagram (automatic layout) and Reset Diagram (drop manual positions and options);
• the type's own options (show/hide, spacing, labels, colors, pictures, …);
• Auto Number… (Hierarchy, Tree, Action and Asset Diagrams): Prefix, Number in action-flow order (Actions), Number direct children only (one level). Numbers the children of "root" as Prefix.1, Prefix.2, … and their children below them. One undo step. Toast: Numbered N entities;
• Check Diagram…: lists entities with no relationships within the diagram (The following entities have no relationships within this diagram (orphans):) with the type's own reason, and decomposition cycles (The following entities form a cycle or many cycles in the decomposition:), or No orphans or cycles found in this type;
• Hide Sidebar / Show Sidebar: hides the left sidebar in every diagram.

Palette

The left sidebar holds the palette of the type and, at the bottom, the Annotations tools. Most types use the standard palette:

• Root card on top: class badge, number, name and description of the root. ✎ edits them in place (Done, Cancel; Name or number is required.).
• New tab: the type's constructs, then the classes it allows (Filter classes…). Drag an item onto a shape to create an entity related to it, or onto the background to create one related to the root.
• Existing tab: search entities (Search entities…) with a class filter (All classes). Entities already on the diagram are marked ✓ (Already on this diagram). Shows the first 200 matches; No matches. when none.
• Layout tab (Layout options): the type's layout commands.

The hint under the search reads Drag onto a diagram entity (or the type's own hint). With the keyboard, focus an item and press Enter or Space to insert it at the center of the view. Some types (Action Diagram, SysML diagrams) have their own fixed palette; see their pages.

Canvas

Zoom and position are saved per diagram. A diagram opens at its saved view, or fitted to the window but at no less than 70%; a larger diagram then starts at its top-left corner.

Search diagram

Type in Search diagram to highlight every element whose name, number, description, id or attribute values contain the text. The count reads N of M; ‹ and ›, Enter and ⇧+Enter move between matches in reading order and center each one. Esc clears the search.

Selection and the inspector

Selecting one shape shows the entity panel in the inspector:

• Name, Number and Description (rich text);
• Open Entity View and Open ▾ (Entity View and every other diagram of this entity), then the type's actions (for example + Add Child, Delete);
• Attributes of the entity's class;
• the Relationships, Metadata and Comments tabs. Relationship types that a diagram manages are locked there.

Selecting a line shows the relationship panel: the source, the relationship name and the target, the inverse reading in brackets, the relationship's description, Line Type (Straight, Orthogonal, Curved) where the type supports it, Hide Label/Show Label and Reset Label, Relationship Attributes (or This relationship has no attributes.) and Remove Relationship (or 🔒 Managed by this diagram). × or Esc closes the inspector; the selection stays.

Connections

Point at a shape (or select it): a green dot, the connect handle, appears. Drag it to another shape:

• valid targets are highlighted while you drag, invalid ones are marked;
• releasing on a valid target creates the relationship; when several relationships are allowed, Choose Relationship asks which one;
• releasing on an invalid target shows That connection is not allowed. (or the type's own reason), and on empty canvas some types create a new entity.

When you connect two existing entities in a type that offers both directions, Create Relationship lists every allowed relationship either way (A — relationship → B). If there is none: No relationships available to create or No relationship allowed from class to class.

Line routing and labels

Lines run between shape borders. Each relationship line can be Straight, Orthogonal (right-angle elbows) or Curved; some types add waypoints or a default line type in ⚙ (see the type's page). Drag a line's label to move it; a dashed leader line then joins it to the line. Reset Label puts it back, Hide Label hides it.

Formatting and alignment

The Hierarchy, Spider, Tree and Asset Diagrams show the format tools in the Edit group (other types have their own styling options; see their pages):

With nothing selected the tools say Select something to format first. Align and Clone Dimensions need two or more shapes. The color picker offers 16 preset swatches, the system color picker, a hex field (#rrggbb) with Apply, and Reset to default.

Resize a shape from its four corner handles; hold Shift to keep the proportions. Positions and sizes snap to a 5-pixel grid; the grid is not drawn.

Layers and stacking

Diagram elements are drawn in a fixed order for each type (containers behind their contents, lines behind shapes). Annotations have two layers of their own: ⤒ Bring to front (above the diagram) and ⤓ Send to back (behind the diagram). Diagram types with nested structure have a Levels control that sets how many levels of decomposition are shown; the Layer Diagram shows decomposition levels as nested boxes (Other Diagrams).

Annotations

Annotations are saved with the diagram, not as entities. Exports, reports, document images and thumbnails include them.

Tools

Open Annotations at the bottom of the left sidebar (click the heading to fold it). Click a tool to add it in the middle of the view, or drag it to a spot.

A new Note or Text opens for typing at once. A new Legend or Title Block shows Legend added. Double-click it to edit. (or Title Block added. …). A title block starts with the root's name and number, today's date and your name.

Editing annotations

• Click to select, Shift/⌘-click to add, or include them in a box selection. Drag to move; drag the corner handles to resize.
• Double-click (or Edit) to edit text, legend entries or title block fields. In text, ⌘+Enter saves and Esc cancels; clicking away saves.
• The floating bar for selected annotations: Edit, ◧ Fill color, ▭ Line color, A Text color, font size (8–40 pt), ┄ Dashed line on or off, ⤒ Bring to front, ⤓ Send to back, Pin ▾ (Bottom right, Bottom left, Top right, Top left, Not pinned) for legends and title blocks, Unanchor for anchored notes, and Delete.
• Arrow keys nudge by 5 pixels (Shift: 20). ⌘C, ⌘X and ⌘V copy, cut and paste annotations, also into another diagram (Copied N annotations). Delete removes them (Deleted N annotations).

Pinned legends and title blocks stay outside the diagram content in their corner as the diagram grows.

Export and print

Export ▾ in every diagram:

Connect handles, resize handles and selection boxes are never exported. Exports always use the light theme. If rendering fails: Could not render the image.; with no diagram drawn: Nothing to export.

Thumbnails

Holarch saves a small preview of each diagram 1.5 seconds after a change and when you leave the diagram. The Diagrams page renders missing previews in the background, one at a time, and shows No preview yet until then. Previews of derived views are rendered without saving the view. ⋯ → Refresh Image renders one again.

View-only access

People with the Viewer role on a project see the banner View only — You can read and export this project. Ask an owner for edit access. (Show members lists the project's members). In diagrams they can open, pan, zoom, search, switch diagram types and export, but:

• the palette, connect handles, resize handles and edit gestures are not shown;
• edit buttons and menu items are disabled with the tooltip View only: ask an owner for edit access;
• the AI control is disabled (View only: AI tools need edit access);
• any attempt to change the model shows View only: ask an owner for edit access. and nothing is saved.

Keyboard shortcuts

Options and settings

• Per diagram: zoom and position, layout, formatting, hidden items, show/hide options and annotations.
• In this browser: whether the left sidebar is hidden (⚙ → Hide Sidebar), whether the Annotations section is folded, and type defaults such as the Action Diagram toggles.
• Per project: shared diagram preferences, such as Spider relationship presets and the risk matrix.

Messages

Limits

• One diagram of each type per root entity.
• Zoom: 10% to 400%.
• Palette lists: the first 200 entities on the Existing tab.
• Image annotations: PNG, JPG or SVG up to the project's attachment limit.
• Report file names: 100 characters.
• Thumbnails: JPEG, at most 440 × 250 pixels.

Related pages

• Action Diagrams
• Functional Analysis (FFBD)
• SysML Diagrams
• Other Diagrams
• Whiteboards
• Help: Diagrams, Diagram Editor Basics