Draw your first architecture

Start from a ready design, put components on the canvas, connect them, and keep, check and export the result.

In short

Designer draws how your software fits together. Start an architecture from a ready design, a few sentences for AI to draft, or an empty canvas; put components on it and connect them. It saves itself, keeps versions, and exports as a picture, Mermaid or documentation.

Before you start

Who: In an organization you need "Create and change designs" (an Organization Admin, Manager or Member holds it). A Viewer holds "See designs" and can read designs and the catalog. In your Personal Workspace you do everything on your own designs. Inside a design your level decides the rest: View opens it, Comment adds comments, Edit changes it and Manage shares it and deletes it.
Plan: Designer is part of every plan, Free included. The Free plan limits how many designs a workspace keeps; Plan & usage shows the limit and what you hold. "Describe it" is AI work, so on Free it needs your own AI key.
First: choose the workspace the design belongs in. A design lives in one workspace and starts open as its maker chose, else as its team's default.

Start a design

Open Designer and press "New design". Choose "Architecture", pick where to start and press "Create design".
Rename a component: double-click it on the canvas, or type in the inspector on the right.
Connect two parts: drag from the edge of one to the other, then say what the connection does.
Press "Share" to choose who can open it, or "Export" to save it as a picture, a document or diagram text.

On a new workspace the Designer offers "Start from the web app template" first, a web app with its API and database already drawn, and "Start from a workflow" second. More ways wait behind them. "Describe it" has AI draft an architecture for you to check. The others are "Empty canvas", "Add examples" (a sample online shop you can remove in one click), "More templates" and "Import a file".

Find and organize your designs

Designs lists every design you can open as a table. Switch to Cards for a grid; on a phone the rows become cards on their own.
Press a design to see a quick look beside the list: where it stands, its kind, team and proof. Open takes you into the design. J and K move to the next and previous design.
Search by name or description, and narrow by Kind, Team or Proof. "No team" shows the designs filed under no team. The address keeps every setting, so you can share a link to the list as you see it.
Sort by name, kind, team, proof or last change by pressing a column's name. A long list comes in pages of 50.
Save a filtered list as a view with the views button at the start of the toolbar. Your views are yours; you can share one with the workspace.
A Component detail is not listed: it opens from its component. The table says how many are left out, and "List them too" shows them.
Select designs to delete them or file them under a team at once. Only designs you manage change; the others are counted in a message.
Deleting a design never asks first. The message says it was deleted, and Undo brings it back. Only you can bring back a design you deleted, within a day.
With nothing selected in a design, the side panel shows the design itself: its name, kind, team and when it was last saved. If you manage it, change its team there.

The design list

The Designer home has four views: "Designs", "Catalog", "Services" and "Code". "New design" and "Import" sit in the header. Type in "Search designs" to find a design by its name or description.

"Designs" lists every architecture and workflow. A workflow with a plan shows how many of its steps are verified, such as "7/12 verified".
"Catalog" lists the components your workspace reuses, "Services" is the map of your services and "Code" lists your code sources.
The "Proof" filter sits under "Filters" until you have 20 designs, then it moves next to the search.
Drop a file anywhere on the list and the import opens. See /help/designer/import-a-design.
The header menu holds "More templates", "Architecture rules" (see /help/designer/architecture-rules), "System" (see /help/designer/system-map) and "Record of processing" (see /help/designer/record-of-processing). People who may change the Designer's rules also find "Designer settings" there. The download button above the list saves every design's coverage as Excel or PDF.

Rename or delete a design

On the Designs list, open the design's "More for" menu (its name follows).
Choose "Rename". In "Rename design", change the "Name" or the "Description" and press "Save".
Or choose "Delete design". It goes at once: the message says "Design deleted." and Undo brings it back.

Deleting a design is for people who manage it. Everyone it is shared with loses it too.
A design someone can only look at is marked "View only" in the list.
A design counts toward your plan's number of designs while it exists. Deleting one frees its place.

The canvas and the outline

The palette on the left holds every kind of component, the boundaries (system, network zone, cloud region, team) and your workspace's catalog. Drag one onto the canvas, or double-click the canvas to search for one. Drag components into a boundary to put them inside it. The "Outline" shows the same design as a tree you edit in place: each boundary with what it holds under it (fold it away with its arrow), then the connections. It is the fastest way to rename many things, and the main editor on a phone. Tick rows to select them on the canvas too; with two or more ticked, a bar offers "Change together", "Move into a boundary" and "Delete", each one step that one Undo takes back.

The toolbar

The toolbar is one row in three zones. On the left are "Add", "Undo" and "Redo". "Add" opens a quick list that puts a part on the nearest free spot. In the middle are the "Simple" and "Full editor" switch (see /help/designer/simple-and-full-editor), the "Canvas" and "Outline" switch and "Zoom". On the right are who else is here, one main next step, "Share" and the menus "Review", "Show", "Export" and "Panels". The main next step is "Add" while the design is empty, "Create the plan" for a workflow, and for an architecture "Check against code", or "Connect your code" while the workspace has no code. Zoom in and out and "Fit" are also on the canvas, with the percentage. On the right side of the screen, the properties panel has four tabs for what you select, or for the design when nothing is selected: "Properties", "Links", "Discussion" and "History". A panel you open from a menu sits beside it, or behind a switch at its top on a smaller screen.

On a narrow screen the labelled menus shrink to icons, then fold into "More tools", while the main step and "Share" stay in the row. On a phone the toolbar keeps "Add", "Undo", the view menu and the next step, and a button opens a sheet with the rest.

The catalog

A component such as Payments API exists once in your workspace's catalog and can appear in many designs. A shape you draw starts as part of its design only; choose "Add to catalog" in the inspector to share it with the workspace. The Catalog view lists every component, and each opens on a page of its own.

Add, edit or delete a catalog component

Open the Designer's "Catalog" view and press "New component".
In "New catalog component", give a "Name" (required: "A component needs a name."), a "Kind", a "Technology" and a "Description".
Add "Tags" separated by commas, and the "Repository" and "Documentation" links if you have them.
Press "Add to catalog".

Result: in an organization everyone who uses the Designer sees the component in the catalog and can use it in their designs. In your Personal Workspace it joins your own catalog.

The kinds are Application, Service, Database, Queue or topic, Storage, External system and Person.
Open a component and press "Edit" to change it. The component shows its "Revision" number.
"Delete from catalog" removes it at once and offers Undo. Designs that use it keep their shapes and stop following the catalog; Undo brings the component back, and they follow it again.
Changing the catalog needs "Create and change designs" in an organization. A Viewer reads the catalog.

Read the services map

Open the Designer and choose "Services".
In an organization, under "Show", choose "All services", "My services" or "A team's services" and pick the team.
Read each row under "Services", then press a service's name to reach its page (see /help/designer/service-page).

A catalog component becomes a service once it has an owner or a linked record. Each row shows its health: Failing, Flaky, Passing or Untested. It says "No owner" or "Depends on one person" where that is true. It also shows the open bugs, and "Not shipped yet" or the deploy or release that shipped it.

The list shows the first 50 services by name.
"My services" lists the services you own. With none it says "You own no service yet. When someone adds you as an owner, it shows here."
In an organization, a row offers "What to read first": "Workflows using it", "Decisions" and "Recent timeline". "Hide what to read" closes it.

Who can open a design

A design in your Personal Workspace is yours alone. In an organization, a new design filed under a team starts open to that team, and private when filed under none. The catalog stays the organization's: everyone whose role sees designs reads it.

To show a design to someone outside, such as a customer, a contractor or a partner, press "Share", type their email address and choose "A guest". A guest sees only the designs shared with them, and can view or comment at most. The catalog, services and code stay closed to them. A guest takes one of your plan's guest places, not a member place, and no paid seat.

Good to know

A design saves itself a moment after every change; unsaved changes are kept on your device until the server has them.
Several people can edit one design at the same time. Each person's changes reach the others as they save. A part or connection someone is changing shows a lock with their picture: pick another part, or wait until they move on.
If someone else changed a part you changed too, a line names those parts. Press "Keep mine" or "Use theirs". Your other changes and theirs are both kept.
For a big rework, press "Edit alone" beside the faces at the top. The others watch until you press "Stop editing alone". Someone who manages the design can press "Take over".
"Versions" keeps the design every half hour of editing, when the editor leaves, before AI changes and whenever you "Keep" one by name. View a version, compare any two, or restore one. See /help/designer/compare-versions.
"Checks" points at what a reviewer would ask first. It lists components connected to nothing, connections without a label, a database many services share, external systems outside every boundary and rings of synchronous calls.
"AI help" explains a design, suggests changes or generates one. Every proposal is shown on the canvas first and applied only when you choose.
"Export" saves a picture (PNG or SVG), documentation (PDF, Word or Markdown), Mermaid text or a file, or a {{brand}} file you can import again. See /help/designer/export-a-design.
"Present" under "Show" turns a design into a full-screen talk. See /help/designer/present-a-design.
What happens next: the design saves itself and appears in the Designs list. To undo a change use Undo or restore a kept version; to remove the design, someone who manages it deletes it.
Phone and tablet: the Outline is the main editor on a phone, and a button opens a sheet with the toolbar's other menus (see the toolbar section above).
A Component detail and a function's flow say where they sit at the top of the screen: "System", the component, then the parts above them. Each name opens its design, and "System" opens the System map. Opened from another design's step, the top shows the designs you came through instead.

If something goes wrong

"Someone else is editing this design alone. You can look at it while they do.": wait until they stop, or ask a manager of the design to take over. Changes you had not saved stay on your screen.
"Your role in this organization lets you view designs, not create or change them. Ask an organization admin."
"This design is too large to save. Split it into smaller designs."
"Describe the system you want to design.": Describe it needs a few sentences.

/help/designer/design-a-workflow
/help/designer/design-comments
/help/designer/service-page
/help/designer/export-a-design