Reference architecture
Group the running pieces so a failure domain is obvious.
Related: System context · Sequence / fan-out flow
When to use
Use after context, when the room needs boxes inside the system. Do not use to retell the business case (Consulting). Do not flatten every microservice.
Guidelines
Dashed groups with labels (edge / app / data). Title says why the split exists.
Example
Harbor in one DC
Keep scan, queue, and ledger in separate boxes so a jam cannot lock receiving.
Edge
Scanner clients
App
Harbor API
Work queue
Data
Ledger DB
Generic boxes · no vendor icons
Three groups, generic nodes. Steal failure-domain grouping, not a marketplace icon set.
Rules
- Groups have labels. Ungrouped boxes are a last resort.
- No official cloud icon packs.
- Title states an architectural constraint, not “Architecture.”
- Legend or source line names the abstraction level (one DC, one region).
- No unlabeled arrows.
User recipe
Pick family: Cloud architecture first.
Insert objects:
- Text: title stating the constraint, kicker, source line with abstraction level
- Panel: for each failure domain or logical group (edge / app / data)
- Junction: for each component inside panels
- Connector: arrows between junctions
Assemble:
- Label every panel
- Place junctions inside appropriate panels
- Generic boxes only; no cloud icon packs
- Every connector labeled or clearly showing data flow
Anti-patterns
- Every product in the bill of materials.
- Mixing a KPI table onto the diagram.