Modeling C4 relationships

Relationships connect two elements by their ID using the arrow operator. Relationship modes are level-independent — they may be used between Systems, Containers, or Components.

MobileApp -> API "Requests services"

Relationships can include a metadata block:

AccountService -> AccountRepository "Retrieves account data" {
    technology "Spring Data JPA"
    mode synchronous
}

technology specifies the implementation technology or framework. Technology is metadata, not structure — do not create semantic types for specific technologies.

component PolicyRepository "Policy Repository" repository {
    technology "Spring Data JPA"
}

Here repository is the architectural role; Spring Data JPA is the implementation technology.

protocol specifies the communication protocol. Protocol is a controlled vocabulary — it is not free text. Values are matched case-insensitively and canonicalized to lowercase. Unknown values produce a validation error with a "did you mean" suggestion.

API -> IdentityProvider "Validates identity" {
    protocol oidc
}

75 protocols across 12 categories:

AAL C4 v0.2 semantic relationship mode. Mode describes architectural interaction semantics — it is independent of visual edge style and level-independent.

AccountService -> AccountRepository "Retrieves account data" {
    mode synchronous
}

TransactionPublisher -> EventBus "Publishes transaction event" {
    mode event
}

tags are comma-separated string labels for additional characteristics beyond the primary semantic type:

container API "Customer API" api {
    tags "Cloud", "Critical", "Customer Facing"
}

Only one primary semantic type is allowed in positional shorthand. Use tags for additional characteristics.

Each object has four logical connection points: Top, Right, Bottom, and Left. You can reposition the endpoint of an existing connector between these attachment points.

Attachment sides are View Layout Metadata — they are NOT part of AAL. The architecture relationship (source → destination) does not change; only the visual connection side changes.

To reattach an endpoint:

• Select a relationship on the canvas.
• Drag the source or target endpoint to a different side of the same object.
• Alternatively, use the Source Side and Target Side dropdowns in the Inspector.

Attachment sides are independent of edge style (Orthogonal / Curved / Straight). They persist across save/reload and are preserved in export.