Modeling C4 relationships
Model directional C4 relationships with descriptions, technologies, protocols, interaction modes, tags, and attachment points.
Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics

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
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
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:
Web & API
Real-Time & Streaming
Messaging & Events
File Transfer
Data & Database
Identity & Security
AI & Agent
Industrial & IoT
Industry Standards
Legacy & RPC
Transport
Interaction Mode
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
}Connector Attachment Points
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.