Draw.io Overview Diagrams

Generate valid draw.io XML and save as <name>.drawio using the Write tool.

Mapping Selection

• pick the shape mapping matching the architecture the user named or the composed skill implies:
  • BCE business components, or sdd4j-bce in context → BCE mapping
  • technical layer packages, or sdd4j-package-by-layer in context → Package By Layer mapping
  • feature/capability packages, or sdd4j-package-by-feature in context → Package By Feature mapping
  • ports-and-adapters layout, or sdd4j-hexagonal in context → Hexagonal mapping
• when invoked via diagrams, use the architecture it detected — the router is architecture-neutral
• no clear architecture → use the Default mapping
• never mix mappings inside one diagram

Lines

• rounded routing: edgeStyle=orthogonalEdgeStyle;rounded=1;
• black stroke: strokeColor=#000000;
• arrow at target: endArrow=block;endFill=1;
• async/optional dependencies: add dashed=1;
• label without shadow: shadow=0; on the label cell
• when an edge crosses container boundaries (source or target is nested in a container), pin explicit exitX/exitY on the source and entryX/entryY on the target so the orthogonal router does not take ugly paths; when multiple edges share a target, give each a distinct entry point to prevent overlap

Style

• all nodes: rounded=1;whiteSpace=wrap;html=1;shadow=1;
• corner radius: arcSize=10;
• font: fontColor=#000000;fontSize=13;fontStyle=0;
• grouping: container with title bar (container=1;collapsible=0;verticalAlign=top;), fill #f5f5f5, border #666666

Palette

Colors carry the same meaning across all mappings — and match the mermaid skill, so mixed-format diagrams stay visually consistent:

Default Mapping

Use when no architecture mapping applies.

BCE Mapping

BCE Robustness Icons (built-in)

Drawio ships with the Jacobson BCE icons. Use these — never reconstruct them from primitives (lines + ellipses + triangles).

• Boundary Object: shape=umlBoundary;whiteSpace=wrap;html=1;
• Control Object: ellipse;shape=umlControl;whiteSpace=wrap;html=1;
• Entity Object: ellipse;shape=umlEntity;whiteSpace=wrap;html=1;

Color them by adding fillColor=#ffffff;strokeColor=<layer-border>;. Typical icon size: width=30;height=32. These icons are BCE-specific — do not use them in other mappings.

Package By Layer Mapping

Layers are containers; nodes are the capability's classes inside each layer.

Package By Feature Mapping

Nodes are feature packages; containers group by module or base package. Drawing inside a feature package reuses the element styles from the Package By Layer mapping.

Hexagonal (Ports & Adapters) Mapping

Nodes are adapters, ports, use cases, and domain types. Lay out driving side left, driven side right; the hexagon boundary is a shape=hexagon container (container=1) holding ports, use cases, and domain when expanding a component, or a plain shape=hexagon node per capability in system view. Edges show call flow through ports — interface indirection is elided.

Content

• visualize only high-level concepts and modules
• show dependencies between components as directed arrows
• omit implementation details, classes, and methods
• group related components visually
• limit diagram to essential relationships

Layout

• arrange components in logical flow (top-to-bottom or left-to-right)
• consistent spacing: 40px between nodes, 20px padding inside containers
• avoid crossing lines where possible
• use container shapes (container=1;) for subsystem, layer, or module grouping
• if a node blends into its container's fill (e.g. gray infrastructure inside a gray layer container), set fillColor=none on the container
• default node size: width=160;height=60;

Labels

• use short, descriptive names
• avoid technical jargon unless domain-specific
• label arrows only when relationship type is ambiguous
• black font color for all labels
• do not use italic font
• connection labels must be without shadow
• connection labels must use fontSize=16;

XML Structure

Minimal skeleton — every .drawio file must follow this hierarchy:

<mxfile>
  <diagram name="Overview" id="diag1">
    <mxGraphModel dx="1024" dy="768" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- nodes and edges here, parent="1" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Example — Minimal 2-Node BCE Diagram

<mxfile>
  <diagram name="Overview" id="d1">
    <mxGraphModel dx="1024" dy="768" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <mxCell id="2" value="Orders" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;arcSize=10;fillColor=#dae8fc;strokeColor=#6c8ebf;fontColor=#000000;fontSize=13;fontStyle=0;" vertex="1" parent="1">
          <mxGeometry x="100" y="200" width="160" height="60" as="geometry"/>
        </mxCell>
        <mxCell id="3" value="Payments" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;arcSize=10;fillColor=#dae8fc;strokeColor=#6c8ebf;fontColor=#000000;fontSize=13;fontStyle=0;" vertex="1" parent="1">
          <mxGeometry x="380" y="200" width="160" height="60" as="geometry"/>
        </mxCell>
        <mxCell id="4" value="charges" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;strokeColor=#000000;fontColor=#000000;fontSize=16;fontStyle=0;endArrow=block;endFill=1;shadow=0;" edge="1" source="2" target="3" parent="1">
          <mxGeometry relative="1" as="geometry"/>
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

File Output

• save as <name>.drawio using the Write tool
• see references/example-bce.drawio, references/example-layered.drawio, references/example-feature.drawio, and references/example-hexagonal.drawio for complete per-mapping examples