Documentation

Shared guide · C4 and System Design

Create an architecture draft with AI

Turn a description into an editable starting point, review the architecture, and make it your own.

Open ProjectsChoose another starting point

1. Open a project and describe the system

Sign in with a confirmed account, create a C4 Architecture or System Design project, and open its designer. Choose Create draft with AI in the toolbar, or under More on a smaller screen. Start in a new project when you want to keep an existing design.

Prepare your request

  1. Describe the responsibilities, boundaries, and interactions you want to model. Use the order-processing request below as a starting point.
  2. Choose the diagram focus. For this example, select Containers in C4 or Event-driven system in System Design. Add constraints under Additional instructions.
  3. Optionally attach one JPG/JPEG up to 5 MB and 16 megapixels. The combined text limit is 12,000 characters. Code repositories, URLs, PDFs, and multiple images are not supported inputs for built-in drafting.

Try this order-processing request

Model an online store. The storefront sends orders to an Orders API, which requests payment from an external payment provider and publishes order events. Fulfillment consumes those events. Show the relationships and keep the payment provider outside the store boundary.

2. Generate a fresh draft

Complete security verification, then choose Generate and replace. Keep the designer open while Acefy generates and checks the draft. Successful generation automatically replaces the current AAL and diagram layout as one undoable change. It does not save the project.

To stop a pending request, choose Cancel and confirm cancellation. A cancelled or closed designer does not apply a late result. A completed server request can still count toward your allowance even if its result does not reach your browser.

3. Review and refine the architecture

Expect an editable diagram and AAL, potentially with up to five editable comments describing assumptions. The example below illustrates a possible result; your generated structure, names, and layout can differ.

Review before relying on the draft

  • Check that the storefront, order service, event channel, and fulfillment belong within the store boundary, with the payment provider outside it.
  • Check relationship direction and responsibilities: storefront to orders, orders to payments and events, then events to fulfillment.
  • Read any assumptions and remove or correct invented technologies or requirements. Compiler validation checks supported language and model rules; it does not prove architectural correctness.
  • Select Orders API and rename it to Order service in the inspector. Verify that the diagram and AAL both show the new name. Use Undo if you want to revert an edit or the draft replacement.
System DesignC4 Architecture
Online store · nested elementsStorefrontApplicationOrder serviceApplicationOrder eventsEvent channelFulfillmentConsumerPayment providerExternal system
  1. 01 Storefront Place order ↓
  2. 02 Order serviceRequests payment → External payment provider
  3. 03 Order events Deliver order event ↓
  4. 04 Fulfillment Consumes the event

Illustrative result after renaming Orders API to Order service. These are separate capability examples, not an automatic conversion.

View and copy the complete System Design example
Reviewed order-processing example
aal system-design "0.2"
dictionary "0.2.0"
design Store "Order processing" {
  element Commerce "Online store" {
    element Storefront "Storefront" { type generic.application }
    element Orders "Order service" { type generic.application }
    element Events "Order events" { type generic.event_bus }
    element Fulfillment "Fulfillment" { type generic.subscriber }
  }
  element Payments "Payment provider" { type generic.external_system }
  relation PlaceOrder Storefront -> Orders request_response "Place order"
  relation Pay Orders -> Payments request_response "Request payment"
  relation Publish Orders -> Events publish "Order placed"
  relation Deliver Events -> Fulfillment deliver "Fulfill order"
}

4. Save and present

Keep the result

  1. Choose Save explicitly after reviewing your changes. Local saves stay in this browser; Cloud saves use your private cloud project. A local save is not a cloud backup.
  2. Use Present for a focused architecture discussion. Export SVG or PNG for a document, or a project file for an editable portable copy.

Allowances and troubleshooting

Each account can generate up to four successful drafts per UTC day, shared across both capabilities, projects, and devices. The dialog shows the remaining allowance and your local reset time. Failed attempts do not consume the successful-draft quota, but separate attempt limits and cooldowns apply.

When generation cannot complete

  • If the service is unavailable or security verification cannot complete, continue with visual authoring, AAL, or an example. Follow the dialog’s retry guidance.
  • If a request fails, your diagram remains unchanged. For an uncertain network result, refresh/check the allowance before trying again; a completed draft can count even when the response was lost.
  • If your allowance is exhausted, wait until the displayed reset time. There is no automatic retry or recovery of a lost generated result.

Your inputs and the two AI workflows

Built-in drafting sends your submitted description, additional instructions, and optional JPG to OpenAI. Acefy does not store those inputs; provider retention policies apply. Your existing project is not transmitted. Generated AAL and its comments become project content when you explicitly save.

Use my AI assistant is a separate workflow: Getting Started prepares a prompt and matching language references for an external assistant you choose. That workflow can help you work with diagrams, codebases, notes, and mixed source material. You bring the returned AAL into Acefy yourself. The built-in generator does not access your repository or browse URLs.