> > > SpecProjectionVgmSpecification

Virtual Graph Model (VGM) Specification

Purpose

This document specifies the Virtual Graph Model (VGM): the notation-agnostic visual graph dataset that sits between SOTER's semantic projection mapping and format-specific visual output adapters (BPMN, UML/PlantUML, D2, SVG, Mermaid). It defines the shared VGM contract, not the whole projection pipeline.

Scope

This document covers:

the VGM boundary between semantic mapping, layout, and rendering,
the VGM JSON structure for nodes and edges,
a worked example translating a Logos model into visual graph data and target output,
the layout stability principle that keeps projectors from introducing independent geometric logic.

Non-Goals

This document does not define the projection pipeline's non-visual products; see ProjectionPipelineSpec.md.
This document does not define layout strategies or text metrology; see ProjectionLayoutStrategiesSpec.md.
It does not define BPMN-specific mapping rules (pools, lanes, gateways, data associations); see ProjectionBpmn.md.
It does not define the Logos language grammar; see LogosOverview.md.

Terminology

Term	Meaning
VGM	Virtual Graph Model — the notation-agnostic geometry dataset of nodes and edges.
Logical graph	The NetworkX representation of business relations (subjects, actions, objects, triggers), free of coordinates or styling.
Projector	A format-specific adapter (e.g. `bpmn_generator.py`, `uml_generator.py`) that maps VGM coordinates directly onto a target notation.
Butterfly effect	Layout instability where a minor model change causes a disproportionately large change in rendered layout topology.

Model or Contract

The Triple Projection Procedure

SOTER isolates semantic domain transformations from physical layout rendering (XML/graphics output) using a three-step projection pipeline:

Step 1: Logos (.model) to Logical Graph (NetworkX). Processes pure business ontology (subjects, actions, objects, triggers). This layer is entirely devoid of visual layout coordinates or styles.
Step 2: Logical Graph to VGM (Virtual Geometry). The logical graph is processed by a mathematical layout solver (e.g. NetworkX hierarchical layout algorithms, or Graphviz/dot as an execution backend). This step calculates raw coordinates: mapping elements to rectangles (X, Y, W, H) and edge connections to precise waypoint vectors (X, Y).
Step 3: VGM to Target Projector. The computed VGM is passed to format-specific adapters (such as bpmn_generator.py or uml_generator.py). These adapters act as "dumb translators" that map VGM coordinates directly onto target notations (e.g. XML tags for BPMN, or coordinate syntax for D2/PlantUML).

graph TD
    A[1. Logos Source Code .model] -->|Lark Parser| B(2. AST Tree)
    B -->|Semantic Analyzer| C(3. Logical Graph NetworkX)
    C -. Topology/Semantics Ends, Geometry Begins .-> D

    subgraph Virtual Geometry
    D[4. VGM Layout Engine dot/Graphviz]
    D -->|Computes X, Y, W, H| E[(5. VGM JSON Dataset)]
    end

    E -->|1:1 Mapping| F[BPMN XML Adapter]
    E -->|1:1 Mapping| G[PlantUML/D2 Adapter]

    F --> H[6a. .bpmn / BPMN.io Render]
    G --> I[6b. .puml / SVG Render]

VGM JSON Structure

The VGM freezes the layout: any semantic change updates this JSON. Downstream projectors consume this exact geometry, ensuring consistent placement across formats.

{
  "nodes": [
    {"id": "pool_Distributor", "type": "Pool", "x": 0, "y": 0, "w": 800, "h": 400},
    {"id": "lane_Verification", "type": "Lane", "x": 50, "y": 0, "w": 750, "h": 200},
    {"id": "Check_Credit", "type": "Task", "x": 100, "y": 50, "w": 100, "h": 80},
    {"id": "pool_Courier", "type": "Blackbox", "x": 0, "y": 500, "w": 800, "h": 100}
  ],
  "edges": [
    {"source": "Check_Credit", "target": "Is_Creditworthy", "waypoints": [[200, 90], [250, 90]]},
    {"source": "Fulfill_Order", "target": "pool_Courier", "type": "MessageFlow", "waypoints": [[400, 300], [400, 500]]}
  ]
}

Rules

Output adapters (BPMN, UML, D2) must not contain hardcoded coordinate arithmetic or custom arrow-bending logic.
The VGM acts as the sole source of geometric truth: output generators must strictly map the input VGM nodes and edge waypoints onto their target syntax.
The logical graph (Step 1/2 boundary) must remain free of coordinates, pixels, fonts, and visual presentation state.
Projectors must not perform independent layout calculations; they only translate VGM geometry into target syntax.

These rules exist to prevent the "Butterfly Effect": minor model adjustments triggering disproportionately large changes in layout topology.

Examples

1. Logos Source Code (`B2B_Order.model`)

Written by the analyst, capturing strictly semantic flows.

# Logistics process definition
model B2B_Order

pool Distributor
    lane Verification
        element Check_Credit
            type: Task
            produce: credit_score
        gateway Is_Creditworthy
            type: XOR
            route_yes: Fulfill_Order
            route_no: Reject_Order

    lane Warehouse
        element Fulfill_Order
            type: Task
            consume: credit_score
            produce: dispatch_note
            message_out: [Shipping_Notice -> Courier]

pool Courier
    type: Blackbox

2. Logical Graph (NetworkX)

The engine constructs a directed network of relationships to verify business logic rules. Coordinates are not present at this stage.

3. Virtual Graph Model (VGM JSON)

The layout solver computes the spatial coordinates and outputs the notation-agnostic geometry model shown in Model or Contract above.

4. BPMN 2.0 XML Projection

The bpmn_generator.py mapping translates the VGM nodes directly to BPMN XML shapes:

<bpmn:definitions ...>
  <bpmn:collaboration id="Collab_1">
    <bpmn:participant id="pool_Distributor" name="Distributor" processRef="Process_1" />
    <bpmn:participant id="pool_Courier" name="Courier" />
    <bpmn:messageFlow id="Msg_1" sourceRef="Fulfill_Order" targetRef="pool_Courier" />
  </bpmn:collaboration>

  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Collab_1">
      <bpmndi:BPMNShape id="Shape_Check" bpmnElement="Check_Credit">
        <dc:Bounds x="100" y="50" width="100" height="80" />
      </bpmndi:BPMNShape>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
</bpmn:definitions>

5. UML Component Projection

The puml_generator.py mapping translates the relationships to component shapes:

@startuml
skinparam componentStyle rectangle

package "Distributor" {
    component "Verification" as Verification {
        [Check_Credit]
        artifact "credit_score" as credit_score
    }
    component "Warehouse" as Warehouse {
        [Fulfill_Order]
        artifact "dispatch_note" as dispatch_note
    }
}

component "Courier (Blackbox)" as Courier

[Check_Credit] --> credit_score : produces
credit_score --> [Fulfill_Order] : consumes
[Fulfill_Order] --> dispatch_note : produces
[Fulfill_Order] .down.> Courier : <<message>> Shipping_Notice

@enduml

Validation

There is no dedicated automated check described in this document beyond the BPMN projector test suite referenced in ProjectionBpmn.md. Any change to the VGM JSON structure is a change to a shared contract and should be verified against every downstream projector (BPMN, PlantUML/D2), not only the one being modified.

Compatibility

The VGM JSON structure (nodes, edges, and their fields) is the contract boundary between the layout solver and all projectors. Changing field names, coordinate units, or waypoint semantics is a breaking change for every projector and must be coordinated across ProjectionBpmn.md, ProjectionPipelineSpec.md, and ProjectionLayoutStrategiesSpec.md.

Open Questions

None currently tracked in this document.