Excalidraw Architecture Diagrams for Jira – User Guide

How to use Excalidraw Graphviz for Jira: DOT text to laid-out graphs on issues and epics, hand-drawn notes, project diagrams, history and permissions.

Excalidraw Graphviz draws graphs on a Jira issue from a few lines of text. You list what connects to what, the app lays the boxes out for you, and then you explain the picture by hand on a whiteboard: circle a weak spot, add an arrow and a note.

How to read the pictures. Every screenshot comes from a real Jira site. The red boxes with numbers show where to look or click. Number 1 in the picture is step 1 in the text, number 2 is step 2, and so on.

Get started in 2 minutes

  1. Install Excalidraw Graphviz from the Atlassian Marketplace. You need to be a Jira admin. It is free for up to 10 users.
  2. Open an issue. Under its title, open the apps menu and choose Excalidraw Graphviz. The panel appears in the issue, above the activity.
  3. Press Edit in the panel. The editor opens over the page: draw with the hand-drawn tools, or choose Insert diagram → Graphviz. The dialog opens with a ready example; press Insert.
  4. Save. The diagram now shows on the issue for everyone who can see it.

Open the app on an issue

  1. Open any issue and click the apps button under its title.
  2. Choose Excalidraw Graphviz. The panel appears in the issue, above the activity.

An issue without a diagram offers three ways to start: Create diagram (a new diagram for this issue only), Choose a template → Start from this template (a copy of an existing scene) and Link a shared scene (show a scene that lives on other issues too).

The app is also on every project (in the project’s navigation, under More when the row is full) and in Jira’s sidebar under Apps → Excalidraw Graphviz.


The diagram on the issue: Edit, full screen, update by name

The panel shows the drawing with its name, here “This issue’s diagram”.

  1. Edit opens the editor.
  2. The full-screen button shows the drawing as large as the window, with its name, Edit and ×.
  3. ⋯ holds View settings and Show a shared diagram.

After Close in the editor the panel reloads in place; the page does not jump to the top.


Graphviz diagrams from text

  1. In the editor, click Insert diagram.
  2. Choose Graphviz, first in the list.
The Insert a Graphviz diagram dialog. Box 1 marks the examples Directed graph, Clusters and State machine. Box 2 marks the DOT source: digraph G with rankdir=LR and arrows from Idea to Design, Build and Release. Box 3 marks the Preview, four rounded boxes laid out left to right with a feedback arrow. Box 4 marks the diagram's name, Directed graph. Box 5 marks Insert.
  1. Start from an example: Directed graph, Clusters or State machine.
  2. Write the graph in Source, in Graphviz DOT. Each line like Build -> Release; is one arrow. rankdir=LR lays it out left to right.
  3. The Preview lays the graph out as you type.
  4. Give it a name, so you find it in Update later.
  5. Press Insert.

It draws dependency and call graphs, clusters and state machines. To change a graph later, choose Update ▾: it lists the diagrams on the canvas by name. Select a graph on the canvas and the button becomes Update “its name”; it keeps its place and scale. Then explain it by hand: circle what matters, add arrows and notes.

Other diagram types in the same scene

  • PlantUML: UML from text with the official PlantUML engine: sequence, class, activity, use case and state diagrams, and C4 architecture diagrams.
  • 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.
  • LaTeX Math: equations typeset with MathJax as sharp vector images.
  • Vega-Lite: bar, line and pie charts from data you paste into the spec. The chart never loads data from a URL.
  • WaveDrom: digital timing diagrams: clocks, data lines and bus groups.

PlantUML and C4 diagrams

  1. In the editor, open Insert diagram ▾ and choose PlantUML (second in the list).
  2. Pick an example: Sequence, Class, Activity, Use case, State or C4 container.
  3. Edit the text. @startuml and @enduml are optional, and labels can use any script, Cyrillic included. The preview redraws as you type.
  4. Give it a name if you want to find it in Update later, then Insert.

C4 is built in. !include <C4/C4_Context>, <C4/C4_Container>, <C4/C4_Component> and the other C4-PlantUML files, and the same files linked from GitHub (raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/…), are drawn from C4-PlantUML 2.14.0 inside the app. Any other !include is refused: “External includes are not supported: everything stays inside Atlassian.”

Errors. A mistake shows as a message with the line in your own text, for example “PlantUML: Syntax Error? (Assumed diagram type: sequence) on line 2.” Insert stays off until the text draws.


All diagrams of the site

  1. In Jira’s sidebar, open Apps → Excalidraw Graphviz.
  2. Filter the scenes: All, Global, or one project, sorted by Last edited.
  3. New diagram starts a scene that does not belong to one issue.
  4. Each card shows a preview, the project, the last edit and the issues it is on. Its ⋯ menu has Show on Jira… (a project page or an issue) and Delete….

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.

  1. In the issue’s panel, open ⋯ → Show a shared diagram.
  2. Narrow the list: All, Global (the whole site) or This project, sorted by Last edited; the search box finds a scene by name. New diagram starts a new shared scene.
  3. Pick a scene. The one already on this issue says Shown here.

On the global page (Apps → Excalidraw Graphviz) each card’s ⋯ → Show on Jira… puts a scene on a project page or on an issue: choose a Project, optionally an Issue, and press Show here.

Delete… asks first: 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

  1. Click ⋯ next to Edit on the panel and choose View settings.
  2. Change how the diagram 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.
  • The − / + / Fit buttons below the diagram zoom.

The scene’s own defaults for everyone (the project it is listed under, max height, Fit diagram and theme) are in the editor under ⋯ → Diagram settings.


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.
  • PlantUML and C4: the PlantUML engine (@plantuml/core 1.2026.9) and C4-PlantUML 2.14.0 ship inside the app and load only when a PlantUML diagram is shown or edited. Nothing is fetched from plantuml.com, GitHub or any other server.
  • 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 with Show a shared diagram.
  • “This scene no longer exists” — the shared scene was deleted; show another or create a new diagram.
  • “Excalidraw needs an active licence” — a Jira admin renews it in Manage apps.

Still stuck? Contact support.