Draughtsman by OverpassDraughtsman by OverpassDocumentation Draughtsman home Quick start

Using Draughtsman

Diagram types

Ten kinds of diagram, each drawn here in Draughtsman and exported as SVG from the editor. Nothing on this page is a mock-up.

Technically a document has one of four types, and the type picks the vocabulary of node and connector kinds: flowchart, architecture, freeform (no vocabulary, every shape family available) and sequence. ER, UML class, BPMN, swimlane, org chart and state diagrams are shape families that live inside those types, and the New diagram menu offers each as a starting point. That is why a BPMN process is a flowchart document and a UML class diagram is an architecture document. An agent asking get_schema for a type gets the exact kinds back.

Each figure below is the SVG the editor's Export SVG produced, drawn with the shipped neutral diagram theme so that it reads on white paper. Select a figure's link to open the SVG on its own, where the text is easier to read.

Flowchart

Processes, decisions, terminators, data, documents and the wider ISO 5807 symbol set (delay, manual operation, display, stored data, multi-document, merge, extract, summing junction, collate, sort, loop limit, internal storage, card and more). Decisions leave room for a long word. A flowchart document is also where BPMN, swimlane and state shapes are placed.

A flowchart: Order received, then a Valid order decision which leads to Reject and notify on no and to an In stock decision on yes; In stock leads to Accept and pack and then Shipped, or to Backorder on no.
Order approval, the sample the home screen offers. Open the SVG.
node n_start terminal "Order received" @ 200,40 160x56
node n_check decision "Valid order?" @ 200,140 160x100
edge e_1 flow n_start.bottom -> n_check.top routing=orthogonal
edge e_2 flow n_check.bottom -> n_stock.top "yes" routing=orthogonal

Architecture

Services, databases, queues, actors, external systems, containers and notes, plus the generic technology icons: server, load balancer, API gateway, cache, CDN, firewall, object storage, function, router, switch, VPN, DNS, ingress, deployment and namespace objects, and VPC, subnet and availability-zone boundaries. A boundary icon draws as a labelled container with its artwork in a corner. Org-chart boxes, UML class shapes and database tables are available here too.

An architecture diagram: Shoppers go through a CDN and a load balancer to an API gateway inside a private network. The gateway reaches an orders service and a catalogue service. The orders service reads and writes an Orders DB, publishes to an Order events queue, and sends a score to a Fraud check. The catalogue service reads images from object storage.
A shop platform. A container, three icons, a database cylinder and a queue, with connectors that carry their meaning (flow, data). Open the SVG.

Freeform

No kind vocabulary at all: every shape family in the palette is available, and any kind word is accepted. Use it for a whiteboard-style picture that is not a flowchart or an architecture, or when you want to mix families. The trade-off is that the structural review has little to check.

Sequence

Participants are nodes and messages are connectors, and the order of the messages is time. No positions are stored: the layout is derived every time, so an agent only has to write the messages in the order they happen. Combined fragments (with operands and guards), notes, create and destroy, interaction use, activations and a stick-figure actor are supported. In the editor you add a message by dragging a connector between two lifelines, and reorder by dragging.

The editor with the checkout sequence diagram: lifelines for a customer, web app, orders API and payments, messages in order, and an activation bar on the orders API. The panel on the right offers Move to end, Move later, Move earlier and Move to start.
The sequence editor. The panel's Arrange buttons move a selected message in time.
A sequence diagram with a Customer actor and Web app, Orders API and Payments participants. The customer places an order, the web app posts to orders, the API charges the payments service which returns a receipt, then the API sends declined and 201 Created back to the web app, and finally calls audit on itself.
Checkout, the sample the home screen offers. Open the SVG.
type sequence
node p_user actor "Customer"
node p_web participant "Web app"
node p_api participant "Orders API"
edge m_1 sync p_user -> p_web "Place order"
edge m_2 sync p_web -> p_api "POST /orders" activate=true
edge m_3 return p_api -> p_web "201 Created" deactivate=true

Fragments, notes, create and destroy

A fragment (the frame that says alt, opt, loop, par and so on) is a node of kind fragment that takes no column. Its tab text is the operator prop and its guards are the operands prop, one string per operand. Membership is written on each message, never on the fragment: in="f_1" and, for a message under a later operand, operand=1. The frame is derived from the first to the last member, and a fragment can nest in another. A note is an edge of kind note: a row in the time order whose label is the text. create is a message whose target's header is drawn at that row, and destroy ends the target's lifeline there with an X. The product's own example uses all four, and we opened it in the editor:

The editor showing the Checkout with a fragment, a note and a created participant sequence diagram: participants Customer, Web app, Orders API and Payments, an alt frame with the guards card ok and declined around the charge and receipt messages, a note reading Idempotent by key, and a Mailer participant whose header appears part-way down, is sent a message and then ends with an X.
checkout-fragments, the example in the product's repository. The alt frame, the note, the Mailer created partway down and destroyed at the end are all derived from order and props.
node f_1 fragment "alt" operator="alt" operands=["[card ok]","[declined]"]
edge n_1 note p_web -> p_api "Idempotent by key"
edge m_3 sync p_api -> p_pay "charge(total)" activate=true in="f_1" operand=0
edge m_5 async p_api -> p_web "declined" in="f_1" operand=1
edge m_7 create p_web -> p_mail "new Mailer()"
edge m_9 destroy p_web -> p_mail "close()"
  • Editing in the editor is by order. A sequence diagram has no free positions: you add a message by dragging a connector between two lifelines (the release point picks its slot), reorder by dragging a message or with Move earlier and Move later, and the editor works out which fragment a message falls in from its new neighbours. Resizing, free moving and waypoints are not offered for the type.
  • The Text pane works for it too. A sequence diagram's order is the order of its lines: the nodes are the participants, left to right, and the edges are the messages, top to bottom. To add a message between two others, put its line between theirs. The Text pane applies it as one undo step.
  • Mermaid in. A Mermaid sequenceDiagram imports as a sequence document; a construct Draughtsman cannot represent is one warning, while the messages inside it still import. Import Mermaid.
  • In a pull request, order is a change. draughtsman diff reports a moved message as a change, because for a sequence diagram order is time (for other types it counts as layout). See Diagrams in git.
  • Agents. patch_document has an addEdge with before or after, and a moveEdge, for exactly this.
  • Server-side rendering of a sequence diagram (render_document, server PDF) needs the layout service running; the picture is drawn by the same code as the editor's.

What we ran: the editor on this example (the picture above) and the Text pane on it. The Mermaid import and the agent operations are described from Overpass's guide for this page; the Mermaid sequence import was run on the earlier build (see Import Mermaid), and we did not repeat it.

Entity-relationship (ER)

A database table is one node whose rows are its columns, written one per line in the form [PK] [FK] name type [not null | null]. Relationships are connectors with crow's-foot ends, and a connector can attach to a column's row rather than to the table box. You can build tables by hand, import them from SQL (T-SQL, PostgreSQL, MySQL, SQLite), or import Mermaid erDiagram text. A weak entity (a table whose primary key includes a foreign key) draws with a double border.

The editor with the shop schema ER diagram: four tables with key, name and type columns, joined by crow's foot connectors that attach to column rows.
Tables in the editor. A connector attaches to a column's row, so moving or editing columns keeps it attached.
An ER diagram with four tables: customer, customer_order, order_line and product. customer_order points to customer by customer_id, order_line points to customer_order by order_id and to product by product_id, each with crow's foot ends.
The shop schema sample, rearranged into a two-by-two grid. Open the SVG.
node t_customer entity "customer" @ 40,60 262x92 columns=["PK id INT not null","name VARCHAR(120) not null","email VARCHAR(254) not null"]
edge e_1 association t_customer_order.col:customer_id -> t_customer.col:id "customer_id" style.arrowStart=zeroOrMany style.arrowEnd=oneAndOnlyOne

UML class

A class or interface is one node: the label is its name, and its attributes and operations are lists, one member per line, with + - # ~ for visibility. The compartments are derived, so editing members refits the box as one undo step (double-click a compartment to edit it). Provided-interface (lollipop) and required-interface (socket) symbols are included, and the relationship line ends (inheritance, aggregation, composition, realisation, dependency) are connector styles.

A UML class diagram: Customer places Order; Order is composed of OrderLine; Order depends on the PaymentGateway interface; CardGateway realises PaymentGateway. Each class shows attributes and operations in compartments.
An order domain: classes with attributes and operations, an interface with a stereotype, composition, a dependency and a realisation. Open the SVG.
The editor with the Order class selected and its attributes compartment open for editing as a text field, one member per line.
Editing a class's attributes in place.
node c_order class "Order" attributes=["- id: UUID","- placedAt: DateTime","- total: Money"] operations=["+ addLine(sku: string, qty: int)"]
node c_gw interface "PaymentGateway" operations=["+ charge(amount: Money): Receipt"]
edge e_4 association c_card -> c_gw style.dash=dashed style.arrowEnd=inheritance

There is no separate "class diagram" document type, and no Mermaid classDiagram import.

BPMN

35 shapes: start, intermediate and end events (message, timer, signal, error, link and more), tasks (user, service, script, manual, send, receive, business rule), sub-process and call activity, five gateways, data objects and stores, and an annotation. Message flow, association and data association are connector kinds, and sequence flow is the ordinary flow. Events and gateways fill their box and put their label below it. Compensation, loop and multi-instance markers, several event types and choreography diagrams are deliberately left out.

A BPMN process: a start event Claim submitted, a user task Check receipts, an exclusive gateway Over 500 pounds. No leads to a service task Auto-approve; yes leads to a user task Manager review and an Approved gateway, whose yes leads to a send task Pay claim and whose no leads to a Rejected end event. Auto-approve also leads to Pay claim, which ends at Paid.
An expense claim: events, tasks and two exclusive gateways. Open the SVG.
node n_start bpmn-start "Claim submitted" @ 40,170 40x40
node n_gate1 bpmn-exclusive-gateway "Over £500?" @ 315,165 50x50
edge e_4 flow n_gate1 -> n_mgr "yes" routing=orthogonal

Swimlane

A pool is a container with a title band, and a lane is a band inside it. Lanes can run as rows or columns. Add, delete and reorder lanes from the editor, and resizing a pool repacks its lanes; a shape dropped into a lane becomes its child. Choose New Swimlane diagram and the pool arrives with two lanes at a working size.

A swimlane diagram titled Order fulfilment with three lanes, Sales, Warehouse and Finance. Take order leads to an In stock decision, which leads to Pick and pack and Ship in the Warehouse lane, then Raise invoice and Order closed in the Finance lane.
Order fulfilment across three lanes. Open the SVG.

Org chart

Four boxes: role (a plain box with a name over a title), executive (double border), assistant (a left spine, drawn beside its manager by the tree layout) and vacancy (dashed). A dotted-line report is the dotted-report connector. The tree layout (Tidy layout (Tree)) arranges it top-down.

An org chart: a managing director at the top with an executive assistant beside; three heads of engineering, operations and support beneath; and below them a dev lead, an open senior developer vacancy shown dashed, a service desk and customer success, with a dotted line between service desk and customer success.
A small team, with a vacancy and a dotted-line report. Open the SVG.

State machine

Nine UML pseudostate and composite shapes: initial, final, choice, fork/join (the one shape that resizes along one axis), shallow and deep history, entry and exit points, and composite state (a container with a name compartment). A plain rounded box is an ordinary state. The pseudostate glyphs are drawn from the shorter side of their box and hide their label.

A state machine: an initial dot leads to Pending, then to a choice diamond for payment. Approved leads to Paid then Shipped then Delivered then a final state. Declined leads to Cancelled then a second final state labelled archive.
An order lifecycle: initial and final states, a choice, and labelled transitions. Open the SVG.

How these were made

The documents were created through the product's own MCP create_document tool from the DSL, laid out by hand or by the ELK layout engine, adjusted with patch_document, and then exported with File, Export SVG in a real browser. The only edit to the SVG files is that a small subset of the Inter font is embedded in each, so the text keeps its shape when the SVG is shown as an image.