Visual C4 diagram authoring

Create and edit C4 elements and relationships on a visual canvas while Acefy keeps the underlying AAL source synchronized.

Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics

On this page
Independent diagram copies
Copy to Cloud or Local creates an independent diagram in the chosen destination and leaves the original open. Future changes do not sync. Duplicate keeps the same project and location. Cloud folder and diagram counts are unlimited; document size and write-rate limits still apply.
Projects panel with a folder expanded to show its diagrams and Markdown documents
Expand a folder to browse its diagrams and Markdown documents. Click an item to open it.

Visual Authoring

Acefy Architecture supports two synchronized authoring approaches:

  • AAL Authoring — write AAL source directly in the editor.
  • Visual Designer Authoring — create and edit architecture on the canvas.

Both surfaces operate on the same normalized Architecture Model. Visual actions update the model and synchronize valid AAL source; typing AAL updates the model and the canvas. There is only ever one source of truth.

Synchronization
AAL Source ↔ Architecture Model ↔ Designer ↔ Inspector

Visual authoring never bypasses C4 hierarchy or semantic validation. A visually-created object is identical to an AAL-created object once stored in the model.

Creating Objects

Use the + Add button in the Designer toolbar to create architecture objects without typing AAL. The available object types adapt to the current view:

  • Context View — Person, Software System
  • Container View — Person, Software System, Container
  • Component View — Person, Software System, Container, Component

The creation dialog collects a Name (required), an auto-generated ID (editable), a level-aware Semantic Type, and optional metadata (description, technology, owner, tags, color).

Hierarchy is enforced: a Container requires a parent Software System, and a Component requires a parent Container. If a parent is not already selected, the dialog asks you to choose one.

Quick add from parent: when a System or Container is selected, its Inspector header shows a + Container / + Component button to create a child directly inside it.

Example flow:

Visual creation
Select a Software System
  → + Add → Container
  → Name: "Payment API"
  → Semantic Type: api
  → Create

The equivalent AAL is generated automatically and appears in the source editor. IDs are derived from the name as PascalCase (e.g. "Payment API" → PaymentAPI), with a numeric suffix if the ID is already in use.

Creating Relationships

Create relationships by dragging from one object's connection handle to another object. Move near an object edge to reveal its small +; its invisible hit target is larger and zoom-aware. The pointer-down object is always source and the release object is always destination, independent of geometry.

On a successful drop, a relationship Source -> Destination is created in the model and synchronized to AAL:

Example
MobileApp -> API

The new edge is selected automatically and its Inspector opens with the Description field focused, so you can immediately describe the relationship without switching to AAL.

Validation rules apply: relationships to nonexistent elements, self-relationships, and exact duplicate edges are blocked. Empty description, technology, protocol, and mode are left unset by default — enrich them in the Inspector.

Editing Objects & Relationships

Select an object, then open the Inspector through the floating toolbar ellipsis or the Inspector button on the left rail (More → Open Inspector on compact screens) to edit its metadata — name, semantic type, description, technology, owner, tags, and color. Changes update the model and synchronize AAL immediately.

Select a relationship, then open Inspector to edit its semantics:

  • Description — the primary edge label, editable as a text field. Clearing it removes the description from AAL.
  • Technology — editable text field.
  • Protocol — controlled-vocabulary dropdown (not free text).
  • Interaction Mode — synchronous, asynchronous, event, stream, batch, file.

Example: editing a relationship description updates AAL and the canvas label together.

Example
API -> PolicySystem "Retrieves policies"

The Line routing and Connection Points sections remain visual-only View Layout Metadata — they are not written to AAL.