Modeling and the canvas

Elements and relationships

The palette has three tabs. New offers the element kinds of the view's notation, grouped by layer, with your favourites (star a kind) and recent kinds at the top. This model places elements that already exist, and Other models places elements from elsewhere in the workspace as references. Relationships to blocks already on the view are drawn for you. When you connect two blocks, Arq offers only the relationship types the metamodel allows for that pair, most likely first.

The inspector

Select an element anywhere to open the inspector. Properties and Relationships edit it; Appears in lists its home model, the models that reference it and every view that shows it; Trace goes up to why it exists (what it realizes, supports or satisfies, and what motivates it) and down to what realizes it; History shows its revisions and where it came from; Exports says which sibling systems (Lattix, Savant, Kepler) receive it and what it becomes there.

Your own attributes

Every kind has a description, a lifecycle and an owner, plus attributes of its own. A workspace owner can add more in workspace Settings, under Attributes: a name, the kind it applies to (or every kind), and a type such as text, number, date, link or a choice list. The inspector shows them beside the built-in ones, and every change in the workspace is checked against them.

Databases and data stores

A Data Store is any database, cache, queue or bucket. Give it a store type (relational, document, key-value, graph, search, object storage, cache, message queue, warehouse and more), a technology such as PostgreSQL 16, and a classification. A system or component composes the stores it owns, so in C4 a database is a container of its software system. A store composes the tables (physical data objects) and entities it holds, is hosted on a node, and applications access it. On an ER view, tables drawn inside a store are its contents.

Branches

A model's main line is Current, the architecture as it is. Choose New branch in the model header to plan a transition step, the target state or an alternative. A branch starts from a revision of Current and keeps its own changes; Current does not see them. Views open on the branch too: each view starts from its Current layout and then keeps its own, so you can draw the target state.

The Changes tab compares the branch with its starting point (the plan) or with Current as it is now (the plan plus what changed since), and lists other models that reference anything the branch removes. Promote to Current applies the branch's changes to Current in order, checked against Current as it is then, merges what you drew on its views into their Current layouts, and closes the branch. When Current has moved on, Update from Current starts the branch from Current's latest revision with its changes checked again on top, and Freeze as baseline keeps a named, hashed copy of the plan that stays as it is.

Matrices

The Matrix tab of a model edits many relationships at once. RACI lays out roles, actors, units and positions against activities and processes; each cell records R, A, C or I on the performs relationship, and an activity with assignments needs exactly one A. CRUD lays out applications, components, services, APIs and processes against data entities and stores; each cell records which of create, read, update and delete the accesses relationship carries. Cells the metamodel does not allow are shaded, and every matrix downloads as CSV.

Personnel: skills and staffing

Skills needed and Skills held are heatmaps: roles, positions and activities against skills, and organization units, positions and people against skills, at four levels (awareness, working, practitioner, expert). A skill needed at a higher level than anyone holds it is marked as a gap. Staffing sums the FTE of staffing allocations per role and quarter: link each allocation to the role it staffs, give it an FTE and a period, and link the units that allocate it.

Legend and keyboard

Legend in a view's header (or ?) shows the notation's shapes, how each relationship is drawn, what the status marks mean and the keyboard map. With a block selected, the arrow keys move to the nearest connected block in that direction, Shift and an arrow nudge it, . moves focus to the inspector and Enter renames it. / searches the palette and Ctrl+L (Cmd+L) lays the view out.

The palette's Library

The palette's Library tab lists building blocks published to the architecture hub. Importing one copies its elements into this model as one change; place them from This model.

Containers

Drop blocks into a container (an environment, a boundary, a pool or a lane) to nest them. When nesting implies a relationship, Arq offers to add it rather than adding it silently.

Layout

Auto-layout arranges a view in the background without blocking the editor. Edges are routed orthogonally.

Shift-click or drag a lasso to select several blocks; the Arrange toolbar aligns them to an edge or centre line and, with three or more, distributes them evenly. Drag the middle of an edge to reshape it; the shape is kept when you move the blocks. Drag an edge's end onto another block to reconnect it: a relationship moves only if the metamodel allows it for the new pair, as one change in history.

Removing things

Deleting a block removes it from the view only. To remove an element from the model, retire it from the inspector; history keeps it.

Keyboard

Links to elements

Every element has a stable link, /app/w/<workspace>/e/<element>, that opens it in its home model. Copy it from the inspector's header; the catalog uses it too.

Catalog, outline and text

The workspace Catalog lists every element with search and a kind filter. A model's outline edits elements without a canvas, and the Text tab shows the model as a .arq.yaml text projection you can also edit. When you add an element in the outline with a name like an existing one, or rename one in the inspector, Arq points out the possible duplicate. Data that has no classification gets a suggestion from its name and description, which you can apply in one click.

Validation

Every change is checked as you make it, so a model never holds a relationship the metamodel refuses. The Validation tab checks the whole model for what still needs attention: errors, warnings such as a C4 container that is not part of a software system or two elements that look the same, and suggestions such as an activity with no performer or data with no classification. On a view, blocks with errors or warnings carry a small ! glyph, and the list under the canvas selects the block. Coding agents get the same check through the arq_check_model MCP tool.

Rule packs

Workspace owners choose rule packs in Settings: built-in packs for data classification, ownership and C4 hygiene, or custom packs written as JSON. A rule selects element kinds (optionally only in some notations) and requires attributes, relationship counts or name patterns, combined with all, any and not. Findings appear in every model's Validation tab, to coding agents through arq_check_model, and in the validation API. A rule with severity block stops a baseline until it passes; it never stops drafting.

Baselines

On the History tab, Create baseline freezes the model as it is now under a name such as Current state or Target 2027. A baseline never changes: it records the revision and a SHA-256 hash of the model's text at that revision. Compare any two baselines, or a baseline and the current model, as a semantic diff, and download a baseline as .arq.yaml to export a fixed state rather than whatever is current.

Lifecycle

A model moves from Draft to In review, Approved and Retired. Editors change it from the model header; each change is recorded in the audit log.

Working offline

If the connection drops, keep working. Model edits are queued on your device and view layout is kept there too; the editor shows Offline: kept on this device. When the connection returns, everything is sent and merged with what others changed meanwhile, even if you closed the tab in between. Models and views you have opened before open again without a connection, as you last saw them. Signing out removes these offline copies from the device.

History

Every change is a validated changeset that creates a revision. The History tab lists revisions and shows a semantic diff of each: which elements and relationships were added, changed or removed.