End-to-End: New Diagram Type + DSL

This guide explains the full workflow for adding a new diagram type with a new DSL that must work across both repositories:

  • WME repo (frontend + editor package): BESSER-WEB-MODELING-EDITOR

  • BESSER repo (backend + BUML): this repository

Use this when you need new elements, new rendering, and new backend processing. If you only need to expose an existing UML diagram type in the webapp, follow the WME checklist in packages/webapp/src/main/features/project/ADDING_NEW_DIAGRAM_TYPE.md.

Decision Tree

  1. Diagram type already exists in the editor package (packages/editor)?

    • Yes: only do the webapp wiring (sidebar, project model, import/export labels).

    • No: you must add editor package support + webapp wiring + backend processing.

  2. New DSL / new semantics?

    • Yes: update the BUML metamodel and backend converters in the BESSER repo.

Repository Boundaries (who owns what)

  • WME repo (frontend, diagram engine)

    • Editor package (diagram types, elements, rendering, palette, property panels)

    • Webapp (project model, sidebar, import/export, UI)

  • BESSER repo (backend, BUML)

    • BUML metamodel (new DSL concepts)

    • JSON <-> BUML converters

    • Validation and generation endpoints

Step 1: Extend the BUML Metamodel (BESSER repo)

  1. Add new DSL concepts under besser/BUML (metamodel classes, relationships, constraints).

  2. Update serializers/deserializers if the model format changes.

  3. Add or update tests under tests/BUML and tests/BUML_invalid.

  4. Update docs under docs/source/buml_language.

Step 2: Add the Diagram Type in the Editor Package (WME repo)

These files live in the WME repo under packages/editor:

  1. Register diagram and element types

    • packages/editor/src/main/packages/diagram-type.ts

    • packages/editor/src/main/uml-element-type.ts

    • packages/editor/src/main/uml-relationship-type.ts (if you add new relationships)

  2. Create a new diagram package folder

    • Create packages/editor/src/main/packages/<your-diagram>/

    • Add element classes (model), React components (rendering), and palette previews.

  3. Wire registries

    • packages/editor/src/main/packages/components.ts (component map)

    • packages/editor/src/main/packages/uml-elements.ts (element map)

    • packages/editor/src/main/packages/uml-relationships.ts (relationship map)

    • packages/editor/src/main/packages/compose-preview.ts (palette previews)

    • packages/editor/src/main/packages/popups.ts (property panels)

    • packages/editor/src/main/components/create-pane/create-pane.tsx (diagram type selection)

  4. Translations

    • packages/editor/src/main/i18n/en.json (and other locales if needed)

Tip: Follow patterns from existing diagram packages (e.g. uml-class-diagram).

Step 3: Wire the Diagram into the Webapp (WME repo)

Once the editor package can render the diagram, expose it in the webapp. Follow the checklist in:

packages/webapp/src/main/features/project/ADDING_NEW_DIAGRAM_TYPE.md

That checklist covers:

  • Project model types (types/project.ts)

  • Sidebar entries (DiagramTypeSidebar.tsx)

  • Export labels, settings badges, import handling

  • Default project creation for the new diagram

Step 4: Add Backend Processing (BESSER repo)

The BESSER backend uses a modular router architecture. The application factory (backend.py) registers middleware and includes routers from backend/routers/. Endpoints are organized by concern:

  • routers/generation_router.py — code generation

  • routers/conversion_router.py — BUML import/export

  • routers/validation_router.py — diagram validation

  • routers/deployment_router.py — deployment integration

The BESSER backend must understand the JSON produced by the editor:

  1. JSON -> BUML

    • Add a processor in besser/utilities/web_modeling_editor/backend/services/converters/json_to_buml/

    • Register it in besser/utilities/web_modeling_editor/backend/services/converters/json_to_buml/__init__.py and re-export it from besser/utilities/web_modeling_editor/backend/services/converters/__init__.py.

    • Add or update endpoints in the appropriate router (e.g., routers/generation_router.py for generation, routers/conversion_router.py for export).

    • If the diagram is part of a project payload, update besser/utilities/web_modeling_editor/backend/services/converters/json_to_buml/project_converter.py to include the new diagram type.

  2. BUML -> JSON (if import/export back to the editor is required)

    • Add a converter in besser/utilities/web_modeling_editor/backend/services/converters/buml_to_json/

    • Update besser/utilities/web_modeling_editor/backend/services/converters/buml_to_json/project_converter.py to include the new diagram in project JSON outputs.

  3. Validation

    • Update validation logic and OCL checks under besser/utilities/web_modeling_editor/backend/services/validators as needed.

  4. Error handling

    • Use the @handle_endpoint_errors("endpoint_name") decorator from routers/error_handler.py on new endpoints. It maps custom exceptions (ConversionError, ValidationError → 400; GenerationError → 500) to consistent HTTP responses.

Step 5: Sync Contracts Across Repos

Keep the following consistent between WME and BESSER:

  • Diagram type strings (UMLDiagramType)

  • Element and relationship type names

  • JSON schema structure (element fields, relationship fields)

  • Property panel fields vs backend expectations

Step 6: End-to-End Verification

  1. Start the BESSER backend:

    python besser/utilities/web_modeling_editor/backend/backend.py

  2. Start the WME webapp:

    npm run dev

  3. Create a new project using your diagram type.

  4. Add elements and relationships, edit properties, and save.

  5. Trigger generation or validation and confirm the backend accepts the JSON.

Step 7: Sync Repos and Open PRs

  1. Commit WME changes in the WME repo.

  2. Update the submodule SHA in the BESSER repo:

    cd besser/utilities/web_modeling_editor/frontend
git fetch
git checkout <wme-commit-or-branch>
cd ../../../..
git add besser/utilities/web_modeling_editor/frontend

  3. Commit BESSER changes and link the two PRs.

Common Pitfalls

  • The webapp sidebar shows the diagram but the editor package does not know it.

  • JSON type strings in the backend do not match the editor package.

  • Backend is not running on http://localhost:9000/besser_api when you test.

  • Existing projects do not include the new diagram slot (create a new project).