SAMP Platform Specification

SAMP (Symbiotic Analytical Modeling Platform) is a closed-source analytical modelling platform in which the SAMP DSL acts as a meta-language for existing notations (BPMN, UML, ArchiMate). The platform redefines the approach to process modelling by placing the ontological model above the graphical notation.

SAMP is the direct predecessor of the SOTER platform. The core concepts — Model-First, Git-Native storage, semantic separation of model from view — were carried forward and refined in SOTER. This document is preserved as a historical specification artefact.

Purpose

SAMP defines a platform for describing models of organisational reality, not another diagramming tool.

Core Principles

Model-First, Diagram-Second The truth about a system is the semantic model. Diagrams (e.g. BPMN) are merely filtered projections of that model. A model can exist without diagrams; diagrams cannot exist without a model.

Transformational Paradigm Unlike procedural BPMN, SAMP models changes in state (what changed?) rather than just steps (what is happening?). Every Activity must modify the state of a business artefact.

Implementation as Standard (Binding Spec) The reference implementation of SAMP DSL v1 constitutes the ultimate source of semantic truth. The working code defines the standard; documentation is secondary. This enables rapid development without getting stuck in years of theoretical standards committee debates.

Git-Native Text files (.soter) are the sole Source of Truth. The database (SQLite) serves exclusively as a secondary index and cache, enabling full change history and team collaboration (Merge Requests, Code Reviews).

Strategic Comparison

Scope

This document covers the SAMP DSL v1 core ontology, the DSL syntax and UUID identity rules, the platform architecture (components and compilation pipeline), and the CLI-based MVP.

MVP Scope (BPMN Subset)

The MVP focuses on a stable CLI tool supporting:

Entities: Process, Start/End Event, Task, Exclusive/Parallel Gateway, SubProcess.

Relationships: SequenceFlow only.

Commands: validate (semantic consistency) and render (SVG generation).

Non-Goals

• Full BPMN mapping (Pools/Lanes, MessageFlow) is out of scope for the MVP; it is deferred to the v2 roadmap phase (see Compatibility).
• Multi-notation support (ArchiMate/UML) and the SAMP RT execution engine are out of scope for the MVP; they are deferred to the v3 roadmap phase.
• Custom node-positioning/layout algorithms are out of scope: SAMP may delegate all coordinate geometry to D2 or Graphviz rather than implementing its own layout solver.

Terminology

Users and Roles

The system supports five permission levels, with emphasis on roles 2 and 3:

Model or Contract

SAMP DSL Specification

The language is declarative, indentation-based (Python-style), and relies on stable UUID identifiers.

# Process model definition
pbpmn v1
namespace crm

element Customer(550e8400-e29b-41d4-a716-446655440000)
  type: entity

element Order(id=auto)
  type: activity
  in: Quote[Accepted]
  out: Invoice[Draft]

relationship Customer -> Order type=owns

# View definition (Projection to BPMN)
diagram SalesProcess
  show Customer
  show Order
  relationships:
    mode: global
    exclude:
      - Customer->AuditLog

UUID Management

• Automatic: Writing element Name() causes the parser to generate a UUID and inject it into the file.
• Stable: UUID is the only identity. Renaming an element does not change its identity.

Platform Architecture

System Components

Compilation Pipeline

Load (FS) → Parse (Lark) → Semantic Analysis (UUID/Graph) → Build Runtime Model → Projection (BPMN/UML)

D2 — Declarative Diagramming Engine

D2 is a modern open-source text-to-diagram language and layout engine. In the context of SAMP, D2 is considered as a powerful layout backend capable of automatically positioning complex graph structures. This avoids the need to build a custom node-positioning algorithm from scratch.

Rules

• No Flow Across Autonomy Boundaries: Standard Flow cannot cross the boundary of a Subject(autonomous=true). A Message is required.
• Domain Effect Requirement: Every Activity without an assigned data transformation generates an error/warning. SAMP does not model physical events without a business consequence.
• Identity over State: Changing the state of an artefact (e.g. Contract: draft → signed) is a mutation of the same entity, not the creation of a new one.

Examples

CLI Interface

pbpmn validate .    # Global model consistency check and UUID uniqueness verification
pbpmn render .      # Generate diagrams for all declared views
pbpmn index         # Build local SQLite index for large repositories

Validation

Model consistency and UUID uniqueness are verified with pbpmn validate .. Projections are regenerated deterministically with pbpmn render ., and a local SQLite index for large repositories is built with pbpmn index. Projections must remain 100% deterministic and read-only; manual edits to generated views are not a valid way to change the model (see Semantic Drift in Open Questions).

Compatibility

Roadmap (Backlog)

SAMP is the direct predecessor of SOTER; concepts defined here (Model-First, Git-Native storage, semantic separation of model from view) were carried forward into SOTER's own specifications rather than being replaced.

Open Questions

• Semantic Drift — The biggest threat is the moment when an analyst starts manually editing a generated BPMN view instead of correcting the SAMP model. Projections must be 100% deterministic and read-only.
• Entry Threshold — The DSL itself is simple, but transformational thinking (artefact states) is difficult. Platform success will depend heavily on the quality of VS Code tooling (LSP, autocompletion, live validation).
• Meta-Language Trap (MOF) — SAMP must not try to model everything at once. Instead of building a meta-meta-model, the focus must remain on SAMP Core, which defines universal state-transformation rules. Notations such as BPMN and ArchiMate are treated as specific projections of those transformations, not as full standard implementations.
• Whether D2 or Graphviz is adopted as the layout backend has not been finalized.

Related Documents

• DocumentationStyleGuide.md - writing profile and document-type rules.
• TechnicalSpecTemplate.md - technical document template.
• ArchitectureOverview.md - technical documentation entry point.
• LogosOverview.md - language and model semantics.