End-to-End Flow¶
This page explains the full request lifecycle in the BESSER Web Modeling Editor — from user message through the BESSER Modeling Agent backend, LLM, frontend converter, Redux store, and finally the Apollon editor rendering.
On this page
The Big Picture¶
The system has three parts:
graph LR
subgraph FE["FRONTEND (browser)"]
ChatUI["Chat UI"]
Editor["Editor (Apollon)"]
Redux["Redux Store"]
end
subgraph BE["BACKEND (Python)"]
LLMCalls["LLM calls"]
Prompts["Prompts"]
Schemas["Schemas"]
end
FE <-->|"WebSocket<br/>JSON messages"| BE
BE -->|"API calls"| OpenAI["OpenAI<br/>(per-tier model routing)"]
Frontend (browser)¶
Chat UI: The chat panel where the user types requests and sees responses.
Editor (Apollon): The visual diagram editor rendering boxes, arrows, and classes. This is a third-party library — we do not control its internals.
Redux Store: A JavaScript object in memory holding all project data (every diagram, every tab, every model). When anything changes, the UI updates automatically.
Backend (Docker / Python)¶
WebSocket server: Listens for messages from the frontend chat.
Unified classifier: One structured-output LLM call decides what the user wants (create? modify? generate?) and every sub-routing detail, cached for the whole message.
Orchestrator: Plans which operations to run (e.g., “create ClassDiagram then generate code”).
Diagram handlers: One per diagram type. Each handler builds prompts and parses LLM responses for its diagram type.
LLM calls: Sends prompts to OpenAI and gets structured JSON back, validated by Pydantic schemas.
OpenAI API¶
The backend sends a prompt like “You are a UML expert. Create a class diagram for
a shoe store.” OpenAI returns structured JSON matching a Pydantic schema
(e.g., { classes: [...], relationships: [...] }). The backend validates the
response and sends it to the frontend.
Which model answers depends on the call site, not on one global setting: routing and repair run on the cheap classifier tier, complete-system generation on the large tier (the GUI tier for a GUI, the classifier tier for BPMN and User Profile), single-element and modification calls on the small tier, and file conversion from an image or PDF on the vision tier. Every tier is env-overridable — see Configuration.
If the user supplied their own API key, the generation and conversational calls in this flow run through a per-request client built from that key instead of the shared server key.
Creation Flow¶
Full walkthrough of what happens when the user types “create a shoe store”.
Step 1–2: User message to WebSocket¶
The user types in the chat panel. The frontend builds a JSON payload and sends it over WebSocket:
{
"action": "user_message",
"protocolVersion": "2.0",
"message": "create a shoe store",
"context": {
"activeDiagramType": "ClassDiagram",
"activeDiagramId": "654bfb6f-...",
"projectSnapshot": {
"diagrams": {
"ClassDiagram": [{ "model": { "elements": {}, "relationships": {} } }]
}
}
}
}
The context.projectSnapshot contains the entire project state so the backend
knows what already exists.
Step 3–4: Backend receives and classifies¶
The protocol adapter (protocol/adapters.py) parses the raw message into an
AssistantRequest object. Note that the payload arrives double-JSON-encoded:
BAF’s WebSocket platform preserves only four top-level keys, so the v2 payload
is a JSON string inside message.
The unified classifier (unified_classifier.py) then makes one
structured-output call and returns a UnifiedClassification — here
intent="create_complete_system_intent",
target_diagram_type="ClassDiagram",
model_disposition="new_from_scratch". The result is cached on the BAF
event id, so every transition condition and state body that asks afterwards
reads it for free.
Step 5–6: State machine and orchestrator¶
The BESSER Agent Framework routes to the matching state
(create_complete_system_state). The orchestrator
(orchestrator/request_planner.py) decides:
Target diagram type:
ClassDiagramMode:
complete_systemRequest text:
"create a shoe store"
Step 7–9: Handler calls the LLM¶
execution/model_operations.py calls the ClassDiagramHandler which builds a
system prompt and calls client.beta.chat.completions.parse() with a Pydantic
schema. OpenAI returns:
{
"systemName": "Shoe Store Management System",
"classes": [
{
"className": "Shoe",
"attributes": [
{ "name": "shoeId", "type": "str" },
{ "name": "brand", "type": "str" },
{ "name": "price", "type": "float" }
],
"methods": [
{ "name": "updatePrice", "parameters": [{ "name": "newPrice", "type": "float" }], "returnType": "any" }
]
},
{
"className": "Store",
"attributes": [
{ "name": "storeId", "type": "int" },
{ "name": "name", "type": "str" }
]
}
],
"relationships": [
{
"type": "Association",
"source": "Store",
"target": "Shoe",
"sourceMultiplicity": "1",
"targetMultiplicity": "0..*"
}
]
}
This is validated by Pydantic (SystemClassSpec). Class names are capped at 30
characters, actions use Literal types, and all fields are strictly typed.
Step 10: Backend sends response¶
The handler wraps the LLM response into a WebSocket payload:
{
"action": "inject_complete_system",
"diagramType": "ClassDiagram",
"diagramId": "654bfb6f-...",
"systemSpec": { "...the LLM response..." },
"message": "Built the **Shoe Store** class diagram with 2 class(es).",
"suggestedActions": [
{ "label": "Add attributes", "prompt": "add more attributes" }
]
}
Step 11–12: Frontend converter¶
The frontend receives the WebSocket message and detects it is an injection command. The ConverterFactory transforms the backend’s simple format into the Apollon editor’s detailed format:
Backend format (simple): Apollon format (detailed):
{ {
classes: [ elements: {
{ className: "Shoe", --> "uuid-1": {
attributes: [...] } type: "Class",
] name: "Shoe",
} bounds: { x: 0, y: 0, w: 220, h: 150 },
attributes: ["uuid-2"],
methods: ["uuid-3"]
},
"uuid-2": {
type: "ClassAttribute",
name: "shoeId",
visibility: "private",
attributeType: "str"
}
},
relationships: { ... }
}
The converter generates UUIDs, calculates positions using a grid layout, maps relationship types, and sets bounds/visibility. It is a pure function — no editor, no DOM, no React.
Step 13–14: Redux and editor¶
The converted model is written to the Redux store:
dispatch(updateDiagramModelThunk({ model: newModel }))
Then the editor revision counter is bumped:
dispatch(bumpEditorRevision())
The Apollon editor watches this counter. When it changes, the editor destroys itself and re-creates with the new model from Redux. The user sees the diagram.
Modification Flow¶
When the user says “change storeId to int”, the flow is shorter:
Frontend sends
{ message: "change storeId to int", context: { ... } }The classifier returns
modify_model_intentwithmodel_disposition="extend_existing"Handler builds prompt with the current model so the LLM knows what exists
LLM returns structured modifications:
{
"modifications": [{
"action": "modify_attribute",
"target": { "className": "Store", "attributeName": "storeId" },
"changes": { "type": "int" }
}]
}
Backend sends
{ "action": "modify_model", "modification": { ... } }Frontend ModifierFactory applies changes to the current model (pure function)
Updated model written to Redux + editor revision bumped
Editor re-renders with the updated attribute
Injection Payload Reference¶
The backend sends three types of injection payloads over WebSocket.
inject_complete_system¶
Injects a full diagram. Whether it replaces the current content or merges into
it is carried by replaceExisting, which the agent stamps after resolving
the user’s answer to a replace/keep/new-tab confirmation:
{
"action": "inject_complete_system",
"diagramType": "ClassDiagram",
"diagramId": "654bfb6f-...",
"systemSpec": {
"systemName": "Shoe Store",
"classes": [
{
"className": "Shoe",
"attributes": [{ "name": "shoeId", "type": "str" }],
"methods": [{ "name": "updatePrice", "parameters": [{ "name": "newPrice" }] }]
}
],
"relationships": [
{ "type": "Association", "source": "Store", "target": "Shoe",
"sourceMultiplicity": "1", "targetMultiplicity": "0..*" }
]
},
"message": "Built the Shoe Store class diagram.",
"suggestedActions": [{ "label": "Add attributes", "prompt": "add more attributes" }]
}
modify_model¶
Applies modifications to existing diagram elements. Supports single and batch:
Single modification:
{
"action": "modify_model",
"diagramType": "ClassDiagram",
"modification": {
"action": "modify_attribute",
"target": { "className": "Store", "attributeName": "storeId" },
"changes": { "type": "int" }
},
"message": "Updated attribute storeId in Store."
}
Batch modifications:
{
"action": "modify_model",
"diagramType": "ClassDiagram",
"modifications": [
{ "action": "remove_element", "target": { "className": "Shoe" } },
{ "action": "remove_element", "target": { "sourceClass": "Store", "targetClass": "Shoe" } }
],
"message": "Applied 2 changes."
}
inject_element¶
Adds a single element to an existing diagram:
{
"action": "inject_element",
"diagramType": "ClassDiagram",
"element": {
"className": "Review",
"attributes": [
{ "name": "rating", "type": "int" },
{ "name": "comment", "type": "str" }
]
},
"message": "Added Review class."
}
Frontend Processing¶
When the frontend receives an injection payload, it processes it as follows:
flowchart TD
WS["WebSocket message arrives"] --> AC["AssistantClient.handleMessage()"]
AC -->|"Parse JSON, detect action type"| MI["useModelInjection.handleInjection()"]
MI --> S1["1. Determine target diagram type"]
S1 --> S2["2. Switch diagram tab if needed"]
S2 --> S3["3. Push undo snapshot"]
S3 --> S4{"4. Action type?"}
S4 -->|inject_complete_system| CONV["ConverterFactory.convert(systemSpec)"]
S4 -->|modify_model| MOD["ModifierFactory.applyModification(model, mod)"]
S4 -->|inject_element| CONV2["ConverterFactory (single element)"]
CONV --> S5["5. dispatch(updateDiagramModelThunk)"]
MOD --> S5
CONV2 --> S5
S5 --> S6["6. dispatch(bumpEditorRevision)"]
S6 --> S7["7. Show success message in chat"]
S7 --> RENDER["Apollon editor re-renders from Redux"]
Key Architecture Insight¶
Redux is the model owner. The agent writes, the editor reads:
graph TD
Redux["Redux Store<br/>(source of truth)"]
Redux --> AgentW["Agent writes<br/>(converter)"]
Redux --> EditorR["Editor reads<br/>(renderer)"]
Redux --> OtherR["Other components read<br/>(export, preview)"]
This means:
The agent can work without the editor being mounted
Tab switching does not break injections
Multiple diagram types can be updated in sequence
The editor can be replaced without touching the agent
Component Responsibilities¶
Component |
Job |
Analogy |
|---|---|---|
Chat UI |
Show messages, take user input |
The cashier taking your order |
AssistantClient |
Send/receive WebSocket messages |
The phone line to the kitchen |
Backend |
Understand intent, call LLM, build response |
The chef deciding what to cook |
OpenAI (LLM) |
Generate the actual diagram content |
The recipe book |
Converter |
Transform LLM output to editor format |
The waiter plating the food |
Redux Store |
Hold the project data (single source of truth) |
The serving counter |
Apollon Editor |
Render the diagram visually |
The plate the customer eats from |