Getting started with C4
Create, edit, save, and export your first local-first C4 architecture project using AAL or the synchronized visual designer.
Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics
Starting from a diagram, codebase, or requirements? Choose visual authoring, built-in AI, or your own assistant.
Overview
C4 Architecture explains software structure through Context, Container, and Component views. Begin with the people and systems involved, then add internal detail. You can author the same model in two ways:
- Write AAL — a human-readable architecture language — in the source editor.
- Design visually — create and arrange elements directly on the canvas.
Editing elements and relationships updates both AAL and the canvas. Moving shapes changes the saved layout without changing the model’s meaning.
Diagrams follow the C4 hierarchy: Person → Software System → Container → Component. Each element carries a level-aware semantic type (its architectural role) and optional metadata (description, technology, owner, tags, color).
Getting Started
To start using Acefy Architecture:
Open the designer
Create a diagram or open Projects
Organize related diagrams
Try a small change

- Select a starter element, open Inspector from the left rail or the selection toolbar, and rename it.
- Check that its name changes in both the canvas and AAL source.
- Save, close the diagram, and reopen it from the Projects panel.
Managing Projects
A project is a folder for related diagrams and Markdown documents. Each project groups diagrams by capability and Markdown files under Documents. Each diagram has its own source, views, layout, and save status.
- Projects panel — show or hide it from the left toolbar. Local and Cloud diagrams are separate; every diagram in a project inherits its location.
- Create — New project creates an empty folder. New diagram keeps the name, capability and starter choices, using the selected project or Unfiled.
- Open and switch — expand any folder or capability group to browse while the active item stays open. Click a different diagram or document to switch. If you have unsaved work, choose how to proceed when prompted.
- Unfiled — keep diagrams and documents outside a folder. Open another item directly from Unfiled or a project.
- Manage — use each row's Actions menu to rename, duplicate, move, copy between storage locations, share or delete a diagram.
- Delete project — removes the folder and keeps every diagram and document in Unfiled in the same storage location. Deleting an individual diagram or document removes that item.
- Import — Import diagram opens a supported
.acefy.jsonfile in the selected project, or Unfiled.

Workspace Tour
The Designer (workspace) is divided into four regions:
The Main menu opens Projects and Documentation. The diagram name and C4 level sit in the center. Save and theme sit at the right.
Syntax-highlighted code editor where you write or inspect the AAL source. Open it with Show source on the left rail. Choose Pin source on desktop to give the editor its own space.
The interactive diagram — pan, zoom, select, drag, and connect elements.
Context-sensitive panel showing element or relationship properties for the current selection, or a group-style editor when multiple items are selected.
The divider between the editor and canvas is draggable — hover over the thin bar between them and drag to resize.
The Toolbar
Floating controls group project navigation at top-left, modeling and panels on the left rail, and document actions at top-right. Save stays visible as you resize the window.
- Main menu — open Projects, close the diagram, or open Documentation and Getting Started. Use Export at the top right for SVG, PNG, or editable diagram JSON.
- Add — create objects appropriate to the current C4 level.
- C4 level — choose Context, Container, or Component beside the diagram name.
- Undo — revert the last change, also available with Ctrl/Cmd+Z.
- Layout — run Auto Layout or change direction between Left → Right and Top → Bottom.
- View — find Focus Canvas in the Main menu. Open Source and Inspector from the left rail. Use the canvas controls at the bottom right for zoom, Fit View, and Canvas settings.
- Present — open the current diagram in Presentation Mode.
- Save — explicitly save to the open diagram’s Local or Cloud location.
- Account — manage your profile or sign out.
On compact screens, choose Modeling tools on the left or More at the top right for Add, Undo, Open AAL source, and Open Inspector. Choose More for Present and Export, or Main menu → Projects to switch diagrams. Source and Inspector open one at a time. Closing a panel preserves edits.
The AAL Editor
The left panel is a syntax-highlighted editor for the AAL source. As you type, the model is compiled and the canvas updates automatically.
- Compile status — a green "compiled" badge or a red "errors" badge appears in the editor header.
- Error panel — when the AAL has syntax errors, a panel at the bottom of the editor lists each error with its line number and a suggestion. The canvas keeps showing the last valid model until errors are fixed.
- Format — click Format (or press Shift+Alt+F) to re-indent and normalize the AAL.
- Indentation — the editor uses 4-space indentation. Tab indents and Shift+Tab outdents the current line or selection.
The Canvas
The center canvas renders your architecture as an interactive diagram. Navigation:
- Pan — right-click and drag the canvas to pan. Left-click is reserved for selecting and interacting with elements.
- Zoom — use the scroll wheel or the zoom controls at the bottom right.
- Fit View — use the canvas control to frame the visible elements.
- Select — left-click an element or connector to select it. Open Inspector through the floating toolbar ellipsis or the Inspector button on the left rail (More → Open Inspector on compact screens) to show its properties. Click empty canvas to deselect.
- Grid & background — toggle the grid and change the canvas background from the canvas controls.
- Mini-map — a small overview map helps you navigate large diagrams.
Creating Objects
You can create architecture objects without typing AAL:
Open the Add dialog
Fill in the details
Choose a parent (if required)
Create
+ Container / + Component button to create a child directly inside it.Creating Relationships
To connect two elements:
Reveal the handles
Drag to connect
Describe it
- Duplicate relationships (same source and destination) are blocked.
- Self-relationships are blocked.
- While AAL has syntax errors, new relationships can't be created.
The Inspector
Select an object for the floating styling toolbar. Background or Label, Text color, Border, and Line popovers expose applicable colors, widths, patterns, and arrowheads. Line routing changes geometry; Line pattern changes solid, dashed, or dotted paint. Mixed selections offer only common fields and one edit is one undo step. Custom colors require an account. External C4 outlines remain dashed. Font family, size, and weight remain in the inspector; open it explicitly through the ellipsis or the Inspector button on the left rail (More → Open Inspector on compact screens).
Icon opens the shared picker with Architecture Symbols, Brands & Technology, and Glyphs. Checkerboard previews and the background filter distinguish Transparent, Built-in background, and Unreviewed artwork. Built-in backgrounds remain part of the icon. Light readability backdrops are labeled separately. Icon plate in the toolbar and inspector offers Automatic, Show, or Hide for Acefy’s added white plate; it preserves backgrounds built into the artwork. Choose Automatic, then Use Automatic to remove the explicit artwork choice without changing architectural meaning.


Reset appearance in an appearance popover clears applicable visual overrides, including typography, while preserving positions, dimensions, routes, label placement, and icons.
The right panel is context-sensitive — it shows properties for whatever is selected.
Element Inspector
When an element (Person, System, Container, Component) is selected:
- Name & ID — the display name and identifier.
- Semantic Type — a searchable dropdown of valid semantics for the element's level, grouped by category.
- Description, Technology, Owner — editable text fields.
- Tags — comma-separated labels.
- Color — a curated pastel palette for visual classification.
- + Child — add a child element directly (when applicable).
Relationship Inspector
When a connector is selected:
- Endpoints — source and target (read-only).
- Description — the primary edge label.
- Technology — editable text field.
- Protocol — controlled-vocabulary dropdown (not free text).
- Interaction Mode — synchronous, asynchronous, event, stream, batch, file, tool, a2a, realtime.
- Label Color — set a background color for this relationship's label.
- Edge Style — Orthogonal, Curved, or Straight (visual only).
- Connection Points — choose the source and target sides (Top/Right/Bottom/Left/Auto).
- Label Placement — Automatic or Manual (with a reset option).
Moving & Resizing
- Move an element — left-click and drag it to a new position. Manual positions are saved with the diagram.
- Resize a boundary — System and Container boundaries can be resized by dragging their edges/corners. Custom dimensions persist.
- Manual layout is preserved — your positions and boundary sizes survive save, reload, and source edits. They are only discarded when you run Auto Layout or change the layout direction (with confirmation).
Label Positioning
Adjust the line itself: select one connector and drag a horizontal segment vertically or a vertical segment horizontally. Adjacent segments adjust while unrelated parts stay in place. Double-click a segment or use Inspector → Routing → Add bend to add a local detour. Focus its raised segment to enable Remove bend when it can be safely removed. Reset route restores automatic routing. Arrow keys move a segment only perpendicular to its direction; Escape cancels a drag.
Orthogonal routes retain subtle rounded corners. Curved connectors instead show one shape handle: drag it in any direction to reshape the S-curve smoothly, or use arrow keys. Reset curve restores the automatic curve. Straight lines have no routing handles; choose another style to reshape them. Source/destination objects and attachment sides stay fixed. Routes survive Save and export. Auto Layout resets manual adjustments; Undo restores them with the previous layout. Presentation hides editing handles. These interactions also apply to System Design.
Relationship labels (the description text on a connector) can be repositioned along the edge:
- Drag a label — click and drag a relationship label along its connector. It snaps to common positions (20%, 35%, 50%, 65%, 80%).
- Manual vs Automatic — once dragged, the label becomes Manual. Use Reset to Auto in the Inspector to return it to the automatic midpoint.
- Persistence — label positions are view-layout metadata; they persist and export but aren't written to AAL.
Auto Layout & Direction
Two actions recalculate the diagram and clear manual layout for the current view:
- Auto Layout — reruns the layout engine and discards all manual node positions, label placements, edge styles, and connection overrides for this view.
- Change Direction — switches between Left-to-Right and Top-to-Bottom and resets manual layout for the current view.
Saving Your Work
Save explicitly to persist edits. Opening Share for the active Cloud diagram also saves pending valid changes before creating or copying its link. Share is available for Cloud diagrams, documents and project folders. To share an account-local item, use Copy to Cloud in Projects, then open the Cloud copy. Local items have no Share action.
See Project documents and sharing for Markdown, companion diagrams, and Cloud sharing permissions.
- Save — click Save in the toolbar or press Ctrl/Cmd+S. The toolbar shows Saved when it finishes.
- Unsaved indicator — any change brings back the Save button when the diagram can be saved.
- Leave protection — if you switch items or close a diagram with unsaved changes, choose Save and continue, Leave without saving, or Cancel. Unapplied AAL must be applied or discarded before Save is available. Closing the browser tab uses its own leave confirmation.
Exporting Diagrams
Open the top-right Export menu (More on compact screens) to export the current view as a static image:
- PNG — a high-resolution raster image, ideal for slides and documents.
- SVG — a scalable vector, ideal for print and further editing.
Export captures the exact current layout — no auto-layout runs during export. It preserves node positions, boundary dimensions, hierarchy, edge styles, attachment sides, label positions, object colors, and the canvas background. Only the diagram is exported; no toolbar, editor, or inspector UI.
Presentation Mode
Presentation Mode turns the canvas into a clean, fullscreen view for sharing and walkthroughs — the toolbar, AAL editor, and Inspector are hidden.
- Enter — click Present in the toolbar or compact More menu.
- Exit — click Exit in the floating control bar or press Esc.
- Floating controls — a control group at the top-right lets you toggle theme, change C4 level, change canvas background, and exit. Projects returns to editing and opens the Projects panel.
- Selection glow — selecting a connector highlights its endpoint nodes; selecting nodes highlights the lines between them, so you can trace a path end-to-end.
- Multi-select still works — Ctrl/Cmd+click adds items to the selection during a walkthrough.
Use Canvas settings → Animate lines in the designer to turn connector motion on or off for editing and presentation. The choice is saved with the diagram. Reduced-motion preferences always disable animation.
Multi-Selection Editing
Select multiple items to style them together with the Group Style Inspector.
- Add to selection — hold Ctrl/Cmd and click items to toggle them into the selection.
- Box select — drag on empty canvas to select all nodes in the rectangle. Connector lines that cross the box are selected too.
- Group edits — with multiple nodes selected, change their color at once. With multiple connectors, change edge style and label color at once. With multiple labels, change label color at once.
Diagram Import / Export
Move an editable diagram between browsers or share it with a colleague — the export captures its name, AAL source, selected view, and full layout configuration. The architecture model is rebuilt from AAL when the diagram is imported. Folder membership is not exported.
- Export — in the toolbar, open Export (More on compact screens) and choose Export…, then choose Diagram (.acefy.json) in the export dialog.
- Import — on the Projects panel, click Import diagram and select a previously exported
.acefy.jsonfile. A new independent diagram is created in the selected project or Unfiled.
Keyboard Shortcuts
| Action | Shortcut |
|---|---|
| Save | Ctrl/Cmd+S |
| Undo | Ctrl/Cmd+Z |
| Format AAL | Shift+Alt+F |
| Copy selected element | Ctrl/Cmd+C |
| Paste element | Ctrl/Cmd+V |
| Delete selected element | Delete / Backspace |
| Indent line / selection | Tab |
| Outdent line / selection | Shift+Tab |
Light & Dark Mode
Use Toggle theme at the top right. The theme applies live to the entire workspace — canvas nodes, accent labels, edge text, and the inspector all switch to theme-aware variants without re-running layout.
- Object colors use dedicated dark-mode variants so pastel backgrounds stay readable on dark canvas.
- Relationship label text shifts to a warm gold in dark mode for contrast.
- Your theme choice is stored in this browser and restored on the next load.
Copy, Paste & Delete
- Copy — select an element and press Ctrl/Cmd+C. The element and its connected relationships are copied to the clipboard.
- Paste — press Ctrl/Cmd+V. A duplicate is created with a unique, human-readable ID (e.g.
PaymentAPI→PaymentAPICopy) and a Copy suffix on the name. Connected relationships are duplicated with substituted IDs, and edge styles/connections are carried over. - Delete — select an element and press Delete/Backspace. Deleting a System or Container also removes all of its children and any relationships touching them.