Add elements and relationships
Elements are the people, systems, containers, data stores and services of your architecture; relationships say who calls whom. Add them on any structural view and they join the model, so every other view can draw them.
On this page
Before you start
- A diagram you can edit, open on a structural view such as Containers. See Create a diagram.
- On a Sequence or a BPMN view you cannot place shapes: their steps come from a scenario or a process. See Draw a sequence or dynamic view.
Add elements
- Add an element with Quick add
Press N, or select Element on the left of the canvas (E). In the field, type a kind and a name, as the hint shows: Type a kind and a name, like: db Order DB. For the Claims Platform, type db Claims DB.
Enter adds the element, Shift Enter adds it and keeps the field open for the next one, Tab completes the kind, Esc cancels.
- Or pick a shape
Select Shapes and official logos on the left of the canvas. Shapes are grouped: People & systems, Apps & compute, Data, Messaging & integration, Security & ops, Zones and Annotations. Type in Search shapes and services to find a product, such as PostgreSQL or Azure API Management: the element comes with its official logo. See Shapes and official logos.
- Describe it in the Inspector
With the element selected, press Ctrl I to open the Inspector. Fill in what readers need:
Field Example for the claims database Name Claims DB Type Database Technology PostgreSQL 16 Description Claims, their documents and their status Tags pii, critical (letters, digits and _ . : -, no spaces) Lifecycle Existing, New, Changed or Retiring Outside our scope (external or SaaS) ticked for Payments, which another company runs
Connect them
- Pick the Relationship tool
Select Relationship on the left of the canvas, or press R. Holding C works too: it draws one relationship and goes back to the tool you had.
- Drag from one element to the other
Start on the Claims Service and release on Claims DB. iyedy routes the line at right angles and asks for a label: Describe it: a verb phrase. Type Reads and writes claims in and press Enter, or Esc to leave it unlabelled.
In the app · editor, Containers view The editor with the Relationship tool selected and a new relationship between two elements, open in the Inspector.
- The Relationship tool is pressed.
- The new relationship, selected.
- In the Inspector, choose its kind, or press 1 to 4.
- Say what kind it is
With the relationship selected, press 1 to 4, or choose its Kind in the Inspector:
Key Kind Use it for 1 Sync request a call that waits for an answer, such as HTTPS 2 Async message an event or a message on a queue 3 Data flow data moved from one place to another, such as a nightly export 4 Dependency one thing needs another, without a call Add its Technology, for example JDBC or JSON/HTTPS.
Faster ways
- Add a connected element. Select an element and press A (Add connected element): the new one comes already joined.
- Rename in place. Select an element and press Enter or F2; Shift Enter edits its description.
- Turn a relationship around. Right-click it and choose Reverse direction, or Add reverse relationship for a call both ways.
- Group elements. Select them and press Ctrl G (Wrap in zone); Ctrl Shift G unwraps.
- Duplicate. Ctrl D copies the selection.
Remove or delete
Delete removes the selection from this view only. Ctrl Delete deletes it from the model, so from every view: iyedy asks first and says how many views and scenario steps use it. Ctrl Z undoes both. See One model, many views.
An element you add on a Deployment view joins the model and gets an instance in that environment. Network and edge shapes (load balancer, firewall, DNS) and zones such as region or subnet are placed on Deployment views only.
If it doesn't work
“These two cannot be connected in this view.”
The view does not allow that relationship, for example between two zones. Connect the elements inside them, or draw the relationship in a view where both elements show.
“Self-relationships are refused. Use a note or a component view.”
A relationship needs two different elements. To show what happens inside one element, open its Components view, or add a note with the Text tool (T).
“Added ‘Claims DB’ to the model. This view does not show it.”
The open view does not draw that kind of element, for example a component on a Containers view. Choose Show it here, or Open that view to go where it is drawn.
More symptoms in Diagram troubleshooting.
Was this page helpful?Your answer is anonymous and counts only if you accepted measurement.
What went wrong?
Don't write personal data.