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.

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: ClassDiagram

  • Mode: complete_system

  • Request 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:

  1. Frontend sends { message: "change storeId to int", context: { ... } }

  2. The classifier returns modify_model_intent with model_disposition="extend_existing"

  3. Handler builds prompt with the current model so the LLM knows what exists

  4. LLM returns structured modifications:

{
  "modifications": [{
    "action": "modify_attribute",
    "target": { "className": "Store", "attributeName": "storeId" },
    "changes": { "type": "int" }
  }]
}
  1. Backend sends { "action": "modify_model", "modification": { ... } }

  2. Frontend ModifierFactory applies changes to the current model (pure function)

  3. Updated model written to Redux + editor revision bumped

  4. 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