Getting started with System Design

Create, connect, inspect, save, and reopen your first system diagram.

Acefy Architecture Language (AAL) · AAL System Design 0.2 · Dictionary 0.2.0

On this page

Start with a description and optional JPG or PNG: create a System Design draft with AI, then review, refine, and save.

Create your first diagram

A project is a folder for diagrams and Markdown documents. For this walkthrough, create a System Design diagram called Orders request flow.

Create the diagram

  1. Open Diagram Studio to get started. Sign in if you want to save in Cloud. Optionally select a folder in Projects, then choose New diagram.
  2. Select System Design, choose a starting example, and enter Orders request flow as the name.
  3. A selected project supplies its Local or Cloud location. For an Unfiled diagram choose a location, then Create.

Choose a save location

LocationWhat it means
LocalStored in this browser, separately for guests and each signed-in account. No signup is needed in Diagram Studio. A local save is not a cloud backup.
CloudOptional private cloud persistence.
Project exportAn independent, portable copy of your editable diagram.

Find the diagram again

  • The Projects panel groups folders by Local or Cloud. Expand a folder to see its diagrams and documents. Search filters their names.
  • Click a diagram name to open it. Use Actions to rename, duplicate, move, copy to another location, share, or delete the individual diagram.
  • Browse folders while keeping your current diagram open. Select another item to switch, including from Unfiled. The designer asks what to do with unsaved work before switching.
Designer Projects panel with project folders, capability groups and named diagrams
  1. New project creates a folder in Local or Cloud; New diagram retains capability and starter choices.
  2. Expand a project to find its C4, Sequence, and System Design diagrams and Markdown documents.
  3. Use the row’s Actions menu to manage it. Deleting a folder moves its contents to Unfiled.

Select the screenshot to inspect it at full size.

Build a small request flow

An element is something in your system. In our example, Customer sends a request to Orders API, represented by an AWS Lambda element. The arrow describes the direction of that request.

Build the request flow

  1. Choose Add element twice and name the elements Customer and Orders API. Draw a connector or use Connect elements. Choose an optional type later in Inspector.
  2. Select each box. In Essentials, name them Customer and Orders API. Commit the field.
  3. Drag from a handle on Customer to Orders API. This immediately creates a one-way connect relationship with an empty label. Select it to add an optional label or change its kind.
  4. Save the diagram. Reopen it from Projects to check your names and arrangement.
Customer sends a request to Orders API.
Complete first request flow
aal system-design "0.2"
dictionary "0.2.0"
design OrdersFlow "Orders request flow" {
  element Customer "Customer"
  element Api "Orders API"
  relation Request Customer -> Api connect "Submit order"
}

Work safely with source and canvas

Save explicitly when you want to keep your work. It stores the source and durable visual settings, including your arrangement.

Understand the editing state

  • Unsaved means the current work has not been saved. Project navigation and Documentation offer Save, Discard, or Cancel when needed.
  • If AAL is invalid, the editor keeps your text and the canvas keeps the last valid diagram. Read the diagnostics and repair the source before continuing model edits on the canvas.
  • Undo and Redo recover supported authoring and visual changes. Export a diagram file for a separate recovery copy.

Optional: start with an external assistant

Attach the System Design AI instructions and resource dictionary from the Downloads menu to your external assistant. Describe your requirements, then copy its AAL into a new System Design project. Check diagnostics before saving.

Prepare a prompt for your AI assistant when you are starting from existing material.

Connected customer experience

Connect a customer portal, orders, CRM, and payments around one customer journey.

Application Integration · Beginner · Application Integration · Purposeful relationships · Stable resource IDs

Application Integration illustrative example. Connect a customer portal, orders, CRM, and payments around one customer journey.Customer · Customer portal · Orders API · Customer CRM · Payments
Example
aal system-design "0.2"
dictionary "0.2.0"
design Example "Connected customer experience" {
  element Customer "Customer" { type generic.customer }
  element Portal "Customer portal" { type generic.application }
  element Orders "Orders API" { type generic.application }
  element CRM "Customer CRM" { type generic.external_system }
  element Payments "Payments" { type generic.external_system }
  relation Flow1 Customer -> Portal connect "Uses"
  relation Flow2 Portal -> Orders request_response "Place order"
  relation Flow3 Orders -> CRM write "Update customer"
  relation Flow4 Orders -> Payments request_response "Take payment"
}

Try changing…

  • Rename Customer while preserving its ID; its relationships remain connected.
  • Change the label of Flow1; its semantic direction stays the same.
  • Arrange the diagram and export it as SVG; visual changes stay outside AAL.