Describe a system to get a first draft
On an empty diagram, a few sentences are enough for a first model. The Assistant drafts the people, systems, containers and flows you describe; you check them as ghosts, then apply. Everything stays editable afterwards.
On this page
Before you start
- An empty diagram you can edit. Create one from your library: see Create a diagram.
- The Assistant on, and credits left. See How the Assistant uses credits.
- Two or three sentences about the system: who uses it, what it is made of, what it talks to.
Get the first draft
- Open the empty diagram
An empty sheet asks What do you want to build? with a few examples. The Assistant box reads Describe your system in a sentence or two…
- Describe the system
Write what a colleague would need to draw it. For the Claims Platform:
“Policyholders submit claims through a web portal and a mobile app. Both call the Claims API, which stores claims in a PostgreSQL database and publishes a ClaimSubmitted event to a message broker. A Fraud Scoring service consumes the event. Adjusters work in a back-office web app. The Claims API sends e-mails through an external mail provider.”Press Enter. The request is shown as First model · adds only: a first draft only adds, it never removes anything.
- Check the first model
When it is ready, the sheet says Your first model is ready in the Assistant panel: check it, then Apply. Read the list on the card and look at the ghosts. Untick what you do not want; ask for a change in the same conversation if something is missing (“Add the identity provider that the portal and the back office use.”).
- Apply the draft
Select Apply on the card.
The people, systems, containers and relationships you described are on the canvas, and each one can be selected and edited in the Inspector.
Write a description that works
- Name things as you want them labelled: Claims API, Fraud Scoring, not the service.
- Say who calls whom, and how: calls synchronously over HTTPS, publishes an event, reads nightly files.
- Say what is outside your system: an external mail provider, a payment gateway, a partner's API.
- Add technologies when you know them: PostgreSQL 16, Kafka. The checks and the technology radar use them later.
- Keep it short. Two to six sentences give a better first model than a long specification. For a long brief, attach it instead: see Bring images and PDFs.
Variants and limits
- On a diagram that already has elements, the same request becomes a change proposal on that diagram. Its card says where it goes before you apply.
- From a photo or a sketch: add a photo of a whiteboard instead of typing. See Bring images and PDFs.
- Without AI, start by hand or from a template: the empty sheet offers both.
Coming soonA proposal for a new diagram opens in that new diagram.
If it doesn't work
“Nothing was staged”
The change could not be prepared in a form the diagram accepts. Ask again in other words, or describe fewer parts at once and add the rest in a second request.
Parts of my description are missing
Ask for them in the same conversation, before you apply: the proposal updates. After the Apply, a new request adds them as another change.
“AI is off here. Start by hand or from a template.”
The Assistant is off for this workspace or this diagram. See What the Assistant reads and, in an organisation, Turn on the Assistant for your organisation.
More symptoms: Assistant troubleshooting.
Was this page helpful?Your answer is anonymous and counts only if you accepted measurement.
What went wrong?
Don't write personal data.