layouts/connectors.md

GitHub

Connectors 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ézier C/S/Q commands), or any non-90° segments. All connectors must consist of strictly horizontal and vertical segments only, using the SVG <path> element with M and L commands.

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

System Architecture with Connectors
User Interface Layer
Web App
React
Mobile App
React Native
API Client
REST
Application Layer
Auth Service
OAuth 2.0
API Gateway
Routing
Business Logic
Core
Data Layer
Primary DB
PostgreSQL
Cache
Redis
Search
Elasticsearch
Storage
S3
queries

Usage Guidelines

  1. Container setup — Wrap the diagram content in a <div style="position: relative;">, then place the <svg> overlay as the last child
  2. Coordinate system — SVG coordinates are relative to the container's top-left corner. Estimate positions based on grid layout and component sizes
  3. Arrow markers — Define <marker> elements in <defs> once, reference via marker-end="url(#arrowhead)"
  4. Line types — Use class="arch-conn" for solid lines, class="arch-conn-dashed" for dashed/abstract relationships
  5. Labels — Use <text class="arch-conn-label"> to annotate connectors
  6. 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>