Projection Configuration Cascade and Mapping Registry

Purpose

This document specifies how SOTER resolves the four projection parameters (standard, target, projector, output format) for a given pipeline run, and how the resolved standard is bound to a concrete rendering engine. It defines the six-level configuration priority cascade and the two-tiered mapping/registry layer (projections.json and mappings/*.json) that connects logical standards (e.g. BPMN, UML) to physical projector implementations and layout parameters.

Scope

This document covers:

• the priority cascade used by run_pipeline to resolve standard, target, projector, and format from six possible sources (CLI/API, .view file, model.json, tenant soter.json, global soter.conf, hardcoded defaults),
• the macro-registry file projections.json that binds standards to default projectors and lists projector export capabilities,
• the micro-mapping files mappings/*.json that route Logos semantic elements to notation-specific visual nodes and supply layout parameters,
• the end-to-end decision flow from run_pipeline invocation to rendered artifact,
• concrete worked resolution use cases and a configuration reference guide,
• a brief architectural orientation to the Virtual Graph Model (VGM) pipeline stage that consumes the resolved configuration, including the Providence-ledger hash-binding relationship between a .view file and its VGM output.

Non-Goals

• This document does not define the VGM JSON schema (nodes, edges fields) in full; see ProjectionVgmSpecification.md.
• It does not define the three isolated VGM development phases or text metrology; see ProjectionLayoutStrategiesSpec.md.
• It does not define BPMN-specific mapping, flow inference, or layout rules; see ProjectionBpmn.md.
• It does not define the Logos language grammar; see LogosOverview.md (via ProjectionOverview.md).

Terminology

Model or Contract

1. Pipeline Overview: Where Configuration Resolution Fits

Business models are expressed purely in Logos text DSL files (.model and .fact), which are entirely devoid of styling, visual coordinates, shapes, or rendering instructions. Projections transform these semantic structures into visual notations through a unified pipeline:

Logos Source Code (.view) ──► Semantic Graph (NetworkX) ──► Virtual Graph Model (VGM) ──► Projector Source (.puml, .bpmn, .d2) ──► Presentation (.svg, .png)

Before this pipeline can run, SOTER must resolve which standard, target, projector, and output format apply to a given .view file. That resolution is the subject of this document.

2. The Priority Cascade

When SOTER executes a pipeline (run_pipeline), it resolves the active standard (e.g., BPMN, UML), target (diagram type), projector (rendering engine), and output format (final asset) through a strict priority cascade. Higher priority levels override lower ones, but explicit CLI or API overrides are absolute and can never be modified by configurations.

2.1. Priority Level Hierarchy

2.2. Level-by-Level Specification

Level 1: CLI & API Overrides (Priority 1)

All command-line arguments and programmatic API options bypass lower configurations, writing directly to context.overrides.

• Command Line Interface (CLI):

bash # Override with UML, D2 Projector, and SVG presentation output python soter.py run workspace/acme/input/views/main.view \ --standard UML2.5 \ --target umlclass \ --projector D2 \ --format svg

• Python API Integration:

```python from modules.pipeline import run_pipeline

# Explicit UML v2.5 pipeline outputting SVG via D2 run_pipeline( "workspace/acme/input/views/main.view", standard="UML2.5", target="umlclass", projector="d2", output_format="svg" ) ```

Level 2: Individual Logos View Files (Priority 2)

The .view file records domain-level visual perspectives. To ensure separation of concerns, it specifies only semantic options (standard and target diagram types), ignoring concrete technical engines (projector and format).

• Example View File:

```logos soter v1

element organization_chart() type: view name: OrgDiagram parent: MainBoard label: "01. Organizational Structure" standard: UML2.5 # Specifies standard target: umlclass # Specifies target diagram type ```

Specifying projector or format attributes directly within .view files is strictly forbidden. Such attributes will be silently ignored to protect domain logic from visual implementation details.

Level 3: Model Configuration (Priority 3)

Specifies technical defaults for all views located within a specific model subdirectory (e.g., workspace/{tenant}/{model}/model.json).

• Example model.json:

json { "standard": "UML2.5", "target": "umlclass", "projector": "plantuml", "format": "svg" }

Level 4: Tenant Configuration (Priority 4)

Defines tenant-wide execution configurations for an entire workspace directory (e.g., workspace/{tenant}/soter.json).

• Example soter.json:

json { "standard": "BPMN2.0", "target": "collaborationdiagram", "projector": "bpmn-io", "format": "svg" }

Level 5: Global Configuration (Priority 5)

Provides general fallback values for all SOTER instances across all tenants via soter.conf (written in TOML format).

• Example Global soter.conf ([projections] section):

toml [projections] standard = "UML2.5" target = "umlclass" projector = "plantuml" format = "svg"

Level 6: System Defaults (Priority 6)

If no overrides, configurations, or manifests specify options, SOTER defaults to:

• Standard: UML2.5
• Target: umlclass
• Projector: plantuml
• Output Format: svg

3. The Mapping and Registry Layer

SOTER maps standard specifications to physical generation engines through a two-tiered registry layer: a macro-registry (projections.json) and a micro-mapping registry (mappings/*.json).

3.1. SOTER Mappings Registry: projections.json

Located at analytics/projections/projectors/projections.json, this acts as the central system dictionary binding logical standards to default rendering engines:

{
  "standards": {
    "BPMN": {
      "default_version": "2.0",
      "default_projector": "bpmn-io",
      "versions": {
        "2.0": { "default_projector": "bpmn-io" }
      },
      "mapping_file": "mappings/bpmn.json"
    },
    "UML": {
      "default_version": "2.5",
      "default_projector": "plantuml",
      "versions": {
        "2.5": { "default_projector": "plantuml" }
      },
      "mapping_file": "mappings/uml.json"
    }
  },
  "projectors": {
    "bpmn-io": {
      "native_format": ".bpmn",
      "export_formats": [".svg", ".png"]
    },
    "plantuml": {
      "native_format": ".puml",
      "export_formats": [".svg", ".png"]
    },
    "d2": {
      "native_format": ".d2",
      "export_formats": [".svg", ".png", ".pdf"]
    }
  }
}

3.2. Semantic Mapping Files (mappings/*.json)

While projections.json binds standards to projectors, individual files inside the mappings/ directory (e.g., bpmn.json, uml.json) perform micro-mappings. They define exactly how individual semantic elements from the Logos DSL are mapped to visual nodes and placed on the mathematical coordinate grid of the Virtual Graph Model (VGM).

Each mapping file is parsed by SOTER's projection module (analytics/projections/standards.py) and contains three core configuration matrices:

{
  "id_prefix": "id_",
  "rules": [
    { "query": "class = 'Subject' OR type = 'actor'", "then": "actor" },
    { "query": "class = 'Object' OR type = 'class'", "then": "class" },
    { "query": "class = 'Action' OR type = 'usecase'", "then": "usecase" }
  ],
  "layout": {
    "x_start": 100,
    "x_step": 180,
    "lane_h": 150,
    "pool_w": 2000,
    "node_sizes": {
      "actor": { "w": 80, "h": 100 },
      "class": { "w": 120, "h": 90 },
      "usecase": { "w": 140, "h": 70 }
    }
  }
}

Mapping Configuration Sections

• ID Prefix (id_prefix): Namespace prefix prepended to generated visual node IDs to prevent collisions with SOTER core runtime IDs.
• Translation Rules (rules): SOTER's Semantic Router containing sequentially evaluated SQL-like queries mapping Logos elements to notation-specific elements (e.g. mapping Action to usecase in UML, or task in BPMN).
• Spatial Layout Parameters (layout): Node sizes and positioning step values utilized by layout solvers to compute grid coordinates.
• x_start and x_step: Initial coordinate offset and step-interval increments.
• lane_h and pool_w: Default vertical height of lanes and horizontal width bounds of canvas pools.
• node_sizes: Direct bounding dimensions (w for width, h for height) for visual containers and tasks to ensure text fits cleanly within borders.

4. Downstream Stage: The Virtual Graph Model (VGM)

Once standard, target, projector, and format are resolved, and Logos elements are routed by a mapping file, the pipeline hands off to the VGM layout stage. To prevent visual regressions (the "Word Alignment Effect," where minor semantic model updates cause visual lines or shapes to overlap unexpectedly), SOTER delegates visual calculations to a mathematically isolated spatial model — the Virtual Graph Model. The full VGM JSON contract and the three-phase development blueprint (Bottom-Up contract definition, Top-Down semantic isolation, Meet-in-the-Middle solver bridge) are specified in ProjectionVgmSpecification.md and ProjectionLayoutStrategiesSpec.md respectively and are not repeated here.

One relationship not covered by those documents is how a VGM output is bound back to its originating .view file for provenance purposes, shown in the pipeline diagram below:

flowchart TD
    %% Style definitions
    classDef file fill:#2d3436,stroke:#74b9ff,stroke-width:2px,color:#fff;
    classDef process fill:#0984e3,stroke:#74b9ff,stroke-width:2px,color:#fff;
    classDef math fill:#6c5ce7,stroke:#a29bfe,stroke-width:2px,color:#fff;
    classDef data fill:#00b894,stroke:#55efc4,stroke-width:2px,color:#fff;
    classDef render fill:#d63031,stroke:#fab1a0,stroke-width:2px,color:#fff;
    classDef ledger fill:#e17055,stroke:#ffeaa7,stroke-width:2px,color:#fff;

    %% Input
    Input(📄 .model File<br/>Logos DSL):::file

    %% Phase 1: Topology and Semantics
    subgraph STEP 2: Bottom-Up Topology and Semantics
        Parser(⚙️ SOTER Parser<br/>Lark):::process
        AST(🌳 AST Tree):::data
        Analyzer(🔍 Semantic Analyzer<br/>& Strict Mode Linter):::process
        NetX(🕸️ Logical Graph<br/>NetworkX):::data
    end

    Input --> Parser
    Parser --> AST
    AST --> Analyzer
    Analyzer --> NetX

    %% Phase 2: Meet-in-the-Middle (VGM)
    subgraph STEP 3: Meet-in-the-Middle
        Solver(🧮 Layout Solver<br/>Graphviz / pydot):::math
        VGM(📦 VGM JSON<br/>Data Contract):::data
    end

    NetX -->|Topology only| Solver
    Solver -->|Computed X, Y, W, H| VGM

    %% Phase 3: Projection
    subgraph STEP 1: Top-Down Projectors and Rendering
        BPMN_Gen(🛠️ Adapter BPMN<br/>bpmn_generator.py):::process
        UML_Gen(🛠️ Adapter UML<br/>puml_generator.py):::process
        BPMN_File(📄 .bpmn File<br/>XML):::file
        UML_File(📄 .puml File<br/>Text):::file

        HollowClient(🌐 Epiphany Web<br/>Hollow Client + SSE):::render
        PlantCLI(🖥️ PlantUML CLI):::render

        SVG1(🖼️ SVG - BPMN):::render
        SVG2(🖼️ SVG - UML):::render
    end

    VGM -->|Coordinate read| BPMN_Gen
    VGM -->|Relation read| UML_Gen

    BPMN_Gen --> BPMN_File
    UML_Gen --> UML_File

    BPMN_File -->|Stream to BPMN.io| HollowClient
    UML_File -->|Background compilation| PlantCLI

    HollowClient --> SVG1
    PlantCLI --> SVG2

    %% Ledger
    Providence[(🔒 Fact Ledger<br/>Providence)]:::ledger

    VGM -.->|Hash-Binding .view/VGM| Providence
    HollowClient -.->|User interaction| Providence

The raw Mermaid code for this architectural pipeline is maintained in the standalone file VgmPipeline.mermaid.

5. Decision Flow Diagram

The complete pipeline logic for standard and projector resolution during execution:

graph TD
    A[Start run_pipeline for view] --> B{Is parameter set in CLI / API?}
    B -- YES --> C[Use value from CLI and lock as override]
    B -- NO --> D{Is standard/target defined in .view?}
    D -- YES --> E[Use standard/target from .view]
    D -- NO --> F{Are values defined in model.json?}
    F -- YES --> G[Retrieve values from model.json]
    F -- NO --> H{Are values defined in tenant soter.json?}
    H -- YES --> I[Retrieve values from soter.json]
    H -- NO --> J{Are values defined in soter.conf?}
    J -- YES --> K[Retrieve values from soter.conf]
    J -- NO --> L[Use hardcoded default values in code]

    C & E & G & I & K & L --> M[Resolve projector based on projections.json]
    M --> N[Generate source file in native projector format via VGM solver]
    N --> O{Is output format 'native'?}
    O -- YES --> P[Save only native source file]
    O -- NO --> Q[Generate source file + render presentation format e.g. SVG/PNG]

Rules

• Explicit CLI or API overrides (Priority 1) are absolute and cannot be modified by any lower-priority configuration.
• .view files may only specify standard and target. Specifying projector or format in a .view file is forbidden and such attributes are silently ignored.
• projections.json is a narrow, static system mapping dictionary:
• No Domain Logic: It must not contain conditional rules, user extensions, or dynamic variables.
• Truth Belongs to Logos: All process rules, variables, and organizational structures must reside in .model and .fact files, not in rendering mechanisms. The projector is merely an unaware executioner.
• Projectors must not perform independent layout calculations; they only translate VGM geometry into target syntax (see ProjectionVgmSpecification.md).

Examples

Case A: UML → PlantUML → Native File Only (.puml)

• View File (*.view):

plaintext standard: UML2.5 target: umlclass

• Model Configuration (model.json):

json "format": "native"

• Resolved Pipeline Execution:
• standard = UML2.5 (from .view)
• target = umlclass (from .view)
• projector = plantuml (resolved from projections.json)
• format = native (from model.json)
• Generated Artifact: output/main.puml (no visual rendering performed).

Case B: UML → D2 → SVG Presentation Format (CLI Override)

• CLI Execution:

bash python soter.py run main.view --projector d2 --format svg

• Resolved Pipeline Execution:
• projector = d2 (explicit CLI override)
• format = svg (explicit CLI override)
• Generated Artifacts: output/main.d2 + output/main.svg.

Case C: BPMN → BPMN.io → SVG Presentation Format

• View File (*.view):

plaintext standard: BPMN2.0

• Tenant Configuration (soter.json):

json "format": "svg"

• Resolved Pipeline Execution:
• standard = BPMN2.0 (from .view)
• target = collaborationdiagram (default fallback from projections.json)
• projector = bpmn-io (default fallback from projections.json)
• format = svg (from tenant soter.json)
• Generated Artifacts: output/main.bpmn + output/main.svg (with coordinates dynamically computed via VGM).

Configuration Reference Guide

Use this index to determine where to place configuration adjustments:

Validation

There is no dedicated automated check described in this document beyond the pipeline resolution tests in tests/unit/pipeline/test_pipeline.py (e.g. test_run_pipeline_view_d2, test_run_pipeline_bpmn) and the projector test suites referenced in ProjectionBpmn.md. Any change to the priority cascade, projections.json, or a mappings/*.json file should be verified by running a pipeline against representative .view, model.json, tenant soter.json, and global soter.conf combinations to confirm the expected level wins.

Compatibility

• The six-level priority order (CLI/API > .view > model.json > tenant soter.json > global soter.conf > hardcoded defaults) is a stability boundary. Reordering these levels is a breaking change for any workspace relying on the current override behavior.
• Adding a new resolvable parameter (beyond standard, target, projector, format) must specify its own priority row in the table in Priority Level Hierarchy rather than being silently folded into an existing level.
• Changes to the projections.json schema (standards, projectors objects) or to a mappings/*.json schema (id_prefix, rules, layout) are breaking changes for the projection module (analytics/projections/standards.py) and must be coordinated with ProjectionVgmSpecification.md and ProjectionBpmn.md.

Open Questions

• None currently tracked in this document.

Related Documents

• ProjectionVgmSpecification.md - VGM JSON contract and the triple projection procedure consumed after configuration resolution.
• ProjectionBpmn.md - BPMN projector implementation behavior, one consumer of the bpmn.json mapping file described here.
• ProjectionOverview.md - entry point for projection documentation.
• ArchitectureOverview.md - technical documentation entry point.
• DocumentationStyleGuide.md - writing profile and document-type rules.
• TechnicalSpecTemplate.md - technical document template.