Relationships

Relationships show how architecture elements communicate, depend on, or interact with each other. They are a crucial part of architecture documentation.

Creating Relationships

Drag and Drop

1. Hover over the source element
2. Click and drag from the connection point (small circle)
3. Drop on the target element
4. A relationship is created automatically

Context Menu

1. Right-click on the source element
2. Select "Create Relationship"
3. Click on the target element

Relationship Properties

Label

The label describes what the relationship represents:

• "Sends orders to"
• "Reads data from"
• "Authenticates using"
• "Deploys to"

Best practices:

• Use active voice
• Be specific about what flows
• Keep it concise

Technology

Optionally specify the technology or protocol:

• "REST/HTTPS"
• "gRPC"
• "AMQP"
• "SQL/TCP"
• "WebSocket"

Direction

Relationships have a direction shown by the arrow:

• Unidirectional: One-way communication (most common)
• Bidirectional: Two-way communication

Styling Relationships

Line Style

• Solid: Direct dependency or communication
• Dashed: Optional or async communication

Color

Use colors to categorize relationships:

• Blue for data flow
• Green for success paths
• Red for error handling
• Gray for optional

Curved vs Straight

• Curved lines: Better for complex diagrams, avoid overlaps
• Straight lines: Cleaner for simple diagrams

Common Patterns

Request-Response

Web App --"Makes API calls [REST/HTTPS]"--> API Server

Event-Driven

Order Service --"Publishes events [AMQP]"--> Message Queue
Notification Service <--"Subscribes to events [AMQP]"-- Message Queue

Database Access

API Server --"Reads/writes data [SQL/TCP]"--> Database

External API

Payment Service --"Processes payments [REST/HTTPS]"--> Stripe API

Cross-Level Relationships

Relationships can span across different containers when viewing at the Component level:

• Components can connect to containers in other parts of the system
• This helps show the full picture without leaving the current view

Tips

Don't Over-Connect

Not every possible relationship needs to be shown. Focus on:

• Primary data flows
• Important dependencies
• Non-obvious connections

Group Related Relationships

If multiple elements communicate the same way, consider:

• Using an intermediary (API Gateway, Message Queue)
• Grouping with overlays

Keep Labels Readable

• Position labels to avoid overlapping
• Use shorter labels for cleaner diagrams
• Add details in element descriptions instead