> For the complete documentation index, see [llms.txt](https://docs.ins-pi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ins-pi.com/models/work-in-the-app/ai/architecture-diagrams.md).

# Architecture & Process Diagrams

The AI Assistant can build structured diagrams that follow a notation, not just free-form boxes and lines. Ask for a **BPMN process**, a **C4 architecture** or an **ArchiMate view**, and the Assistant picks the right shapes from your shape libraries, places containers correctly and connects everything with the right relationship types.

<figure><img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2Fgit-blob-d4caa641e32a9c46bfd50f467ad1710e27573d7e%2Fv26.1-ai-bpmn-process.gif?alt=media" alt=""><figcaption><p>A three-lane BPMN process built from one prompt</p></figcaption></figure>

## Supported Notations

| Notation      | What the Assistant builds                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **BPMN**      | Pools and lanes, tasks, start/end events, gateways and sequence flows. Hand-offs between actors run left to right across the lanes of one pool. |
| **C4**        | Person, System, Container and Component shapes inside the matching boundaries.                                                                  |
| **ArchiMate** | Elements from the ArchiMate library grouped into ArchiMate Groupings, with the relationship types the notation expects.                         |

The shape libraries must be installed in your instance. If a library is missing, the Assistant falls back to Basic Shapes and tells you so. See [Shape Libraries](/models/work-in-the-app/editor/shape-libraries.md).

## Writing a Good Prompt

Name the notation, the actors or layers, and the decision points you care about:

* *"Create a BPMN process for purchase order approval with three lanes: Requester, Manager and Finance. Include a decision for orders above 10,000."*
* *"Draw a C4 container diagram for our online shop: web app, API, payment service and a PostgreSQL database."*
* *"Build an ArchiMate application layer view of the HR landscape from the records on this board."*

The Assistant works inside the diagram type you name. Asking for "a process" without saying BPMN gives you a plain flowchart.

## Working with Your Existing Records

When a prompt mentions something that already exists in your Data Hub, the Assistant reuses that record instead of drawing a duplicate:

* Existing records keep their binding, so Realtime Indicators and the Data Panel keep working.
* Relationships between existing records use a real, configured relationship type where one is verified. A visual connection is the fallback.
* Records that do not exist yet are staged as future-state proposals you can [commit](/models/work-in-the-app/editor/commit.md) later.

## Clarification Questions

If a request is ambiguous, for example two records share a name or the actors of a process are unclear, the Assistant asks a short clarification question before drawing. Answer it in the chat and the diagram continues. This only happens when a guess would likely be wrong.

## Editing a Generated Diagram

Follow-up prompts keep the structure intact:

* *"Add a step 'Check budget' in the Finance lane after the approval."* places the new task inside that lane.
* *"Move the gateway to the Manager lane."* keeps the flow attached.
* *"Rename the pool to 'Procurement'."*

After **Add** or **Merge**, only the parts that changed are selected, so you can see what the Assistant touched.

## Tips

* Pick a stronger model for large diagrams. See [Choosing a Model](/models/work-in-the-app/ai/models.md).
* Let the Assistant place things, then tidy with the format toolbar. Nudging a lane by hand is faster than describing the move.
* For a whole department's process, build one pool per system boundary rather than one pool per person.

## Related

* [AI Chat](/models/work-in-the-app/ai/chat.md) – Sending prompts
* [Reviewing & Staging Changes](/models/work-in-the-app/ai/staging.md) – Add, Merge and Discard
* [Attaching Files & Images](/models/work-in-the-app/ai/images.md) – Build a process from a document or a screenshot
* [BPMN Shapes & Swimlanes](/models/bpm-process/bpmn-shapes.md) – Working with the BPMN shapes by hand


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ins-pi.com/models/work-in-the-app/ai/architecture-diagrams.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.