Collaborate on a cloud project

A cloud project (Pro) is one shared copy with a team around it. Each member edits a checkout on their own device and pushes their work with Save to cloud — or lets the quiet background sync do it at natural pauses. Sooner or later two people's work meets, and what happens then is decided by one idea worth understanding: the project is tracked as many small independent parts, and work combines part by part.

This page is the practical handbook — what those parts are, how a merge runs, how to settle a conflict, and the habits that keep all of it uneventful. The guarantees underneath (what can never be lost, what each escape hatch costs) are on Sync, merges & conflicts.

The parts a project tracks separately

When your save meets a teammate's, the app doesn't compare two files — it compares the project part by part. Two people who touched different parts combine without a single question asked, whatever else happened in between. A question is only raised when both of you changed the same part.

So the practical map of "what can we work on at the same time" is the list of parts:

C4 model

Tracked as its own partSo…
Each elementTwo people editing two different elements never collide
Each connection (keyed by the two elements it joins)Relabeling one line while a teammate draws another combines cleanly
Each diagram's settings (name, description, subject, line style)Renaming a diagram doesn't contest the work happening on it
Each diagram's membership, per elementTwo people adding cards to the same diagram both keep them
Each boundary group on a diagramGrouping work merges per boundary
Each element style, display type and connection line style (per named entry)Two new styles from two people both arrive
Each rolled-up connection label (per element pair)Labelling different levels never collides
The default connection line, boundary fill opacity, model titleSingle project-wide facts — shared, so simultaneous changes to the same one are contested

Deployment

Tracked as its own partSo…
Each environment's settingsRenaming dev doesn't contest work inside prod
Each placement in an environmentTwo people deploying things into one environment both keep them
Each connection in an environmentWiring merges per line
Each definition (the reusable element)Editing two different items never collides
Each instance group and each shared connectionInternal wiring merges per line
Each rolled-up level label, templates, the deployment settingsPer entry / one part each

F4 process flows

Tracked as its own partSo…
Each process and each board's settingsRenaming a board doesn't contest its content
Each section, lane, step, line and group on a boardTwo people extending the same board both keep their work
The visibility settings (tags, Ghost/Hide)One shared part

Decisions

Each decision record is its own part — two people writing two different ADRs both keep them, and linking a decision to an element never contests the element itself.

Arrangements

Each diagram's arrangement, at each abstraction level, is one part: positions, boundary frames, hand-routed lines, label positions. Arranging different diagrams — or the same diagram at different levels — always combines. If you both rearranged the same diagram at the same level, yours wins on your screen without a prompt: there is no useful question to ask about two layouts, and either of you can re-drag in seconds. Text typed at a collapsed level (a renamed merged card, a rolled-up line's label) is content, not geometry, and gets real conflict handling.

Yours alone: view state

Panel widths, folded sections, the level you're looking at, export settings in force — device-local view state is never overwritten by loading a teammate's save. How you look at the project is not part of the project.

The one rule that surprises people

A part is contested as a whole. The element is the unit of comparison — not the field. If you edit an element's description while a teammate changes the same element's technology, that element is contested even though your edits never touched the same character: the conflict row shows exactly which fields differ, and choosing Mine or Theirs takes that side's whole element.

The same applies inside a description: it is one field, so two people editing different perspective sections of one element's description is still one contested element — the pick takes one side's entire text, both sections included.

The habit that follows: divide work by part, not within a part. Two people can write descriptions all afternoon without a single conflict — as long as they're writing on different elements.

How a merge happens

  1. You edit. Changes save on your device; the pill shows you have unsaved cloud changes.
  2. You save — the Save to cloud button, or the background sync at a natural pause (leaving the editor, hiding the tab, going idle). Every push states which cloud revision it was built on.
  3. Nothing moved in between? The save is accepted, and becomes a snapshot in version history.
  4. Someone saved before you? Your push is refused instead of overwriting them. An explicit Save opens the resolve dialog; a background sync never interrupts you mid-edit — the pill flips to Remote newer and the button beside it reads Review & save.
  5. You review. The dialog shows everything that happened between your copy and the cloud: anything that would be deleted (its own always-visible section), conflicts to decide, and the count of changes that combine cleanly.
  6. You combine. Both sides' work plus your picks becomes one new revision. A short summary states what the merge did, and the audit log records it.

Closing the dialog changes nothing — your edits stay on your device until you choose.

How to fix a conflict

  1. Open the row. Each conflict names the part and states how many fields differ; opening it shows your value against theirs, field by field — exactly what differs, nothing else.
  2. Pick Mine or Theirs. The pick takes that side's whole record, so read the field table as the price list: it shows precisely what each choice keeps and gives up.
  3. Many rows? Decide the remaining applies one answer to everything you haven't picked yet.
  4. Combine. It stays disabled until every conflict is decided, and it refuses a combination that would break the project (one side deleted a system, the other added a container inside it) — you'll be asked to pick differently rather than push a broken model.
  5. Prefer Combine over the wholesale exits. Keep my version and Take the remote version both discard the other side entirely — they state the count and confirm, and Take the remote offers Save my version to a file first, because unsaved local edits exist nowhere else. Their full costs are on the resolve dialog.
  6. Check the result if in doubt. Every accepted save is in Version history on the project detail page, and the audit log records who resolved what.

The best way of working

None of this needs ceremony — the machinery merges almost everything on its own. These habits keep the remainder small:

  • Load latest before you start. If the pill says Remote newer and you haven't edited yet, one click puts you on the current version. And Save doubles as sync: pressing Save with nothing to save checks the cloud and loads the latest if it moved — so pulling is always one click, whatever the pill says. The cheapest merge is the one that never happens.
  • Save at milestones, not at the end of the day. Small, frequent saves mean small, obvious reviews — and your teammates' tabs pick your work up sooner.
  • Divide by part. By diagram, by subsystem, by model (one on C4, one on deployment, one on flows) — any split along the tracked parts above means zero conflicts by construction.
  • One author per element at a time. Descriptions — perspective sections included — are contested per element. Handing an element to one writer at a time costs nothing and removes the commonest conflict.
  • Agree who arranges a diagram. Two people rearranging the same diagram each keep their own layout locally; give an arrangement pass an owner so the diagram everyone loads is the one someone chose.
  • Make deletions loud. A deletion of something untouched goes through (listed, never buried); deleting what a teammate is actively editing raises a conflict for whoever saves second. Say what you're removing, or do removals as their own small save.
  • Record the why as decisions. A structural change lands better with an ADR beside it — decision records merge per record and link to the elements they're about, so the reasoning travels with the model.
  • Give readers a link, not a membership. Stakeholders who only need to see the architecture get a read-only link; fewer editors means fewer simultaneous edits.
  • Export before a cliff. About to take a wholesale action, or restructure half the model? A JSON export costs seconds and is the one backup that also holds work you never pushed.

Where next