Excalidraw Architecture Diagrams for Jira – User Guide

Overview

Excalidraw Architecture & Dependency Diagrams for Jira lets you map services, components and dependencies on Jira issues: describe them in Graphviz DOT and get a laid-out graph, then sketch and annotate around it on an Excalidraw whiteboard.

A diagram is an Excalidraw scene. It can live in three places:

• the issue panel — a diagram that belongs to one issue, or a shared scene shown there;
• a project page — the project’s diagrams, one of them shown on the page;
• the global page (Jira’s Apps menu) — every scene on the site, to preview, edit, attach or delete.

Diagrams from text are built in: Graphviz, Mermaid, LaTeX Math, Vega-Lite, WaveDrom. The source of each stays with the diagram, so you can change it later. Everything runs on Atlassian Forge: scenes are stored in your Atlassian site and rendered in your browser; the app makes no external calls.

---

Install and open the app

1. Install Excalidraw Architecture & Dependency Diagrams for Jira from the Atlassian Marketplace.
2. On an issue: open the apps menu under the issue’s title and choose Excalidraw Graphviz. The panel appears in the issue, above the activity.

3. On a project: Excalidraw Graphviz is in the project’s navigation (under More when the row is full).
4. All scenes: in Jira’s sidebar, open Apps → Excalidraw Graphviz.

---

Draw a diagram on an issue

An issue without a diagram offers three ways to start:

• Create diagram — a new diagram that belongs to this issue only.
• Choose a template → Start from this template — a copy of an existing scene, to change freely.
• Link a shared scene — show an existing scene here; a change to it shows everywhere it is attached.

The editor opens over the page:

Draw with Excalidraw’s tools — shapes, arrows, freehand, text, images — and pick from over 200 shape libraries under Library; they ship inside the app, nothing is fetched from the internet. Save stores the scene; Close asks first only when there are unsaved changes (“Discard unsaved changes?”).

---

Graphviz diagrams from text

Insert → Graphviz opens the Graphviz dialog: a name, the source, and a live preview. Start from an example — Directed graph, Clusters and State machine — or type your own. It draws graphs in Graphviz DOT with automatic layout: dependency and call graphs, clusters, state machines.

Insert places the diagram in the scene. To change it later, choose Update → Graphviz, pick the diagram on the canvas, edit the source and save: the diagram keeps its place and scale.

Other diagram types in the same scene

Every Excalidraw Graphviz scene can also hold the other built-in editors:

• Mermaid — flowcharts, sequence, class, state and ER diagrams, Gantt charts, mind maps and timelines (Mermaid 11). Insert as shapes turns a Mermaid diagram into ordinary Excalidraw shapes you can move and restyle one by one. Examples: Flowchart, Sequence and Mind map.
• LaTeX Math — equations typeset with MathJax as sharp vector images: fractions, matrices, aligned equations, sums and integrals. A mistake shows the reason (“Missing close brace”) instead of a broken image. Examples: Quadratic formula, Matrix, Series and Aligned.
• Vega-Lite — bar, line and pie charts from data you paste into the spec. The chart never loads data from a URL. Examples: Bar chart, Line chart and Pie chart.
• WaveDrom — digital timing diagrams: clocks, data lines and bus groups. Examples: Clock and data, and Bus groups.

---

Show one diagram on many issues

A shared scene is one diagram shown in many places: on several issues and on the project page. A change to it shows everywhere.

• In an issue panel, open the Scenes tab, choose a Scene (scenes of the whole site and of this project) and press Attach. Preview shows it first, Edit opens it in the editor.

• On the global page, every scene has Preview, Edit, Attach and Delete. Attach asks where to show it — a project (its project page), or an issue of that project (its panel):

The project page lists the project’s scenes as cards with a preview, when each was last edited and where it is attached:

Delete asks “Delete “…”?” — the scene disappears from every issue and page that shows it, so this cannot be undone. A scene can be deleted by its author, a project admin (project scenes) or a Jira admin (global scenes).

---

View settings

View settings above a diagram change how it looks to you; the diagram and other people’s views stay as they are:

• Max height of the panel (at least 120 px), Fit diagram to the panel width, Match Atlassian theme (Jira’s light or dark theme).
• Scroll inside the diagram lets the mouse wheel move the diagram instead of the page; Ctrl/⌘ + wheel zooms.
• Expand opens the diagram large; the − / + / Fit buttons below it zoom.

The Settings tab of the editor holds the scene’s own defaults — its title, the project it is listed under, max height, Fit diagram and theme:

---

Saving, history and conflicts

• Version history: History in the editor lists the last 10 saved versions. Restore saves an old version as a new one, so the current version stays in the list.

• Two people at once: if someone saved while you were editing, the app does not overwrite their work. Your changes stay in the editor and you choose: merge them with the latest version (for each shape the newer edit wins), reload the latest version, or save yours as a copy.
• Unsaved work: if the browser closes during editing, the editor offers “You have unsaved changes” with restore or discard the next time you open the scene.
• Size: a scene holds up to 5 MB, images included. The meter next to Close shows how much is used; shrink or remove images to make room.

---

Permissions and data

• Who can change a diagram: changing an issue’s diagram or attaching a scene needs Edit issues permission; a project’s scenes need Edit issues in that project. Everyone who can see the issue sees the diagram.
• Scopes: the app asks only to read Jira work (issues, projects) and for its own storage.
• Where data lives: scenes, their images and the text sources are stored in the app’s Forge storage inside your Atlassian site. Diagrams render in your browser; Mermaid, MathJax, Graphviz, Vega-Lite and the shape libraries ship inside the app.
• Languages and themes: Cyrillic, Chinese and other scripts work in shapes and text; light and dark themes.

See the privacy policy.

---

Troubleshooting

• “The diagram could not be loaded. Check your connection and try again.” — press Try again.
• Insert is disabled in a text dialog — the preview shows the error in the source; fix the line it names.
• “No scene here yet” on a project page — choose one on the Scenes tab.
• “This scene no longer exists” — the shared scene was deleted; attach another or create a new diagram.
• “Excalidraw needs an active licence” — a Jira admin renews it in Manage apps.

Still stuck? Contact support.

---

Related apps

• Excalidraw Architecture & Sequence Diagrams for Confluence — the same app for Confluence.
• Excalidraw Whiteboard & Mermaid Diagrams for Jira — Mermaid first.
• Excalidraw Math Equations & LaTeX Whiteboard for Jira — LaTeX Math first.
• Excalidraw UML & Class Diagrams for Jira — Nomnoml first.