layouts/connectors.md
GitHubConnectors Layout
Layout: SVG overlay for drawing orthogonal (right-angle) lines/arrows between components Best for: Showing data flow, dependencies, API calls, or any relationship between architecture components
How It Works
Use an absolutely-positioned SVG element overlaid on the diagram container. Components get id attributes, and SVG <path> elements with orthogonal segments (horizontal + vertical only) connect them visually.
Key principle: The outer container must have position: relative, and the SVG overlay uses position: absolute; top: 0; left: 0 with pointer-events: none so it doesn't block clicks.
IMPORTANT: Always use orthogonal (right-angle) paths for connectors. Do NOT use diagonal lines (
<line>), curved paths (BézierC/S/Qcommands), or any non-90° segments. All connectors must consist of strictly horizontal and vertical segments only, using the SVG<path>element withMandLcommands.
Connector Types
| Type | CSS Class | Use Case |
|---|---|---|
| Solid orthogonal line | .arch-conn |
Direct dependency, data flow |
| Dashed orthogonal line | .arch-conn-dashed |
Abstract relationship, optional dependency |
| Arrow (with marker) | Add marker-end="url(#arrowhead)" |
Directional flow |
| Bidirectional | Add markers on both ends | Two-way communication |
Template
React
React Native
REST
OAuth 2.0
Routing
Core
PostgreSQL
Redis
Elasticsearch
S3
Usage Guidelines
- Container setup — Wrap the diagram content in a
<div style="position: relative;">, then place the<svg>overlay as the last child - Coordinate system — SVG coordinates are relative to the container's top-left corner. Estimate positions based on grid layout and component sizes
- Arrow markers — Define
<marker>elements in<defs>once, reference viamarker-end="url(#arrowhead)" - Line types — Use
class="arch-conn"for solid lines,class="arch-conn-dashed"for dashed/abstract relationships - Labels — Use
<text class="arch-conn-label">to annotate connectors - Orthogonal paths — Always use right-angle connections:
<path d="M x1,y1 L x1,yMid L x2,yMid L x2,y2">(vertical → horizontal → vertical)
CSS Reference
Add these classes to your <style scoped> section:
/* Solid connector line */
.arch-conn { stroke: #94a3b8; stroke-width: 1.5; fill: none; }
/* Dashed connector line */
.arch-conn-dashed { stroke: #94a3b8; stroke-width: 1.5; fill: none; stroke-dasharray: 6 4; }
/* Connector label text */
.arch-conn-label { font-size: 9px; fill: #64748b; font-family: sans-serif; }
Arrow Marker Definitions
Include these in the SVG <defs> block:
<defs>
<!-- Open arrowhead (stroke only) -->
<marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
<path d="M0,0 L8,3 L0,6" fill="none" stroke="#94a3b8" stroke-width="1"/>
</marker>
<!-- Filled arrowhead -->
<marker id="arrowhead-fill" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
<path d="M0,0 L8,3 L0,6 Z" fill="#94a3b8"/>
</marker>
<!-- Bidirectional marker (for marker-start) -->
<marker id="arrowhead-reverse" markerWidth="8" markerHeight="6" refX="0" refY="3" orient="auto">
<path d="M8,0 L0,3 L8,6" fill="none" stroke="#94a3b8" stroke-width="1"/>
</marker>
</defs>
Orthogonal Path Patterns
<!-- Vertical → Horizontal → Vertical (standard cross-layer connection) -->
<path d="M 100,50 L 100,100 L 300,100 L 300,150" class="arch-conn" marker-end="url(#arrowhead)"/>
<!-- Straight vertical drop (same column) -->
<path d="M 200,50 L 200,150" class="arch-conn" marker-end="url(#arrowhead)"/>
<!-- Labeled orthogonal connector -->
<path d="M 100,50 L 100,100 L 300,100 L 300,150" class="arch-conn-dashed" marker-end="url(#arrowhead)"/>
<text x="200" y="96" class="arch-conn-label">async event</text>