Getting started with Acefy Architecture

Acefy Architecture is a code-to-diagram tool that turns architecture descriptions into clean, professional C4 diagrams. You can author architecture two ways — and both stay in sync:

• Write AAL — a human-readable architecture language — in the source editor.
• Design visually — create and arrange elements directly on the canvas.

Both surfaces operate on the same model, so typing AAL updates the canvas and dragging on the canvas updates the AAL. There is only ever one source of truth.

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).

To start using Acefy Architecture:

A project is a single architecture model — one AAL source, one set of views, and one saved layout. The Projects page lists all your projects, most recent first.

• Create — New Project opens a fresh workspace with starter AAL.
• Open — click any project card to open it in the Designer.
• Rename — rename a project from the toolbar once it's open, or from the card menu on the Projects page.
• Delete — remove a project from the card menu. This is permanent.
• Switch — use the project switcher in the toolbar to jump between projects without returning to the Projects page.
• Import — click Import Project on the Projects page to load a previously exported .json project file.

The Designer (workspace) is divided into four regions:

The divider between the editor and canvas is draggable — hover over the thin bar between them and drag to resize.

The single-row toolbar keeps project actions and visual modeling tools within reach. Save stays visible as you resize the window.

• Project — click the project name to rename, switch projects, return to Projects, export SVG/PNG/project JSON, or open Docs.
• Add — create objects appropriate to the current C4 level.
• C4 level — choose Context, Container, or Component.
• 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 — show or hide AAL source and Inspector, choose Professional/Executive appearance, toggle Dark theme, or Fit View.
• Present — open the current diagram in Presentation Mode.
• Save — explicitly save to the open project’s location. The button and separate status identify Local or Cloud and show whether changes are saved.
• Account — manage your profile or sign out.

Below 1024px, secondary controls move into More while Project, Present, Save, and Account remain on one row. The compact save indicator uses a pencil for unsaved changes, a spinner while saving, and a check when saved; the full status is available in the project menu. AAL source and Inspector start closed and open one at a time as overlays from More. Selecting a diagram element does not open the compact Inspector automatically. Closing a panel preserves edits, and returning to desktop width restores the prior desktop panel choices. Canvas zoom and fit controls remain available beside the diagram.

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 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 in the bottom-left corner.
• Fit View — click View → Fit View (or the canvas control) to frame all elements.
• Select — left-click an element or connector to select it. The Inspector updates 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.

You can create architecture objects without typing AAL:

To connect two elements:

• Duplicate relationships (same source and destination) are blocked.
• Self-relationships are blocked.
• While AAL has syntax errors, new relationships can't be created.

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).

• Move an element — left-click and drag it to a new position. Manual positions are saved with the project.
• 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).

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.

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.

Projects are not auto-saved — save explicitly to persist changes:

• Save — click Save in the toolbar or press Ctrl/Cmd+S. The status indicator shows Saving… then Saved locally or Saved to cloud, matching the project’s location.
• Unsaved indicator — any change marks the project Unsaved changes. A pencil indicator appears beside Save; open the project menu for the full status in smaller windows.
• Leave protection — if you try to switch projects or close the tab with unsaved changes, you're prompted to save, leave without saving, or cancel.

Open the project-name menu 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 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.
• Exit — click Exit in the floating control bar or press Esc.
• Floating controls — a control group in the bottom-right lets you switch projects, toggle theme, change C4 level, switch preset, change canvas background, and exit.
• 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 and drag-box selection are available, but all editing, dragging, and resizing are disabled.

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.

Move an editable project design 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 project is imported.

• Export — in the toolbar, open the project-name menu and choose Export…, then choose Project in the export dialog.
• Import — on the Projects page, click Import Project and select a previously exported .acefy.json file. A new project is created from it.

Toggle Dark theme in the View menu (inside More on smaller windows). 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 — 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.