> > > SpecProjectionPipelineSpec

Projection Pipeline Specification

Purpose

This specification defines the projection pipeline as a product-generating process. The pipeline does not only produce diagrams. It may produce databases, diagram files, auxiliary JSON, UI surfaces, interaction formats, validation reports, and other materialized views of the same semantic model.

Scope

This document covers:

pipeline stages from Logos source to output artifacts;
projection product families;
separation between mapping, layout, rendering, and materialization;
cross-product consistency requirements.

Non-Goals

This document does not define VGM geometry; see ProjectionVgmSpecification.md.
This document does not define layout strategy details; see ProjectionLayoutStrategiesSpec.md.
This document does not define BPMN-specific output; see ProjectionBpmn.md.
This document does not define configuration precedence; see ProjectionConfigurationCascadeSpec.md.

Terminology

Term	Meaning
Pipeline product	Any materialized output created from the semantic model.
Materialization	Durable projection such as SQLite, KuzuDB, JSON, or generated files.
Presentation artifact	Human-facing product such as SVG, BPMN, PlantUML, Mermaid, D2, or UI surface.
Auxiliary artifact	Machine-facing support output such as render plans, layout JSON, diagnostics, or mapping reports.

Model or Contract

Logos files
  -> parse
  -> validate
  -> semantic graph
  -> projection mapping
  -> optional layout
  -> product-specific materialization

Different products may stop at different stages:

Product family	Pipeline endpoint
Graph database	Semantic graph materialization
Relational database	Selected model/read-model materialization
Diagram source	Target mapping and render plan
Diagram image	Target mapping, layout, renderer
Auxiliary JSON	Semantic graph, render plan, diagnostics, or layout payload
UI form/surface	Interaction/view model generated from semantic graph
Interaction file	Command/action surface derived from semantic contracts
Validation report	Parser, linter, semantic, and ontology diagnostics

Rules

The semantic graph is shared across pipeline products.
A product may add presentation data, but it must not change core semantics.
Layout is required only for products with visual geometry.
Database products should preserve stable IDs and provenance.
Auxiliary JSON must declare which stage it represents.
UI and interaction products must remain projections of Logos contracts, not separate source models.

Examples

Diagram Product

Logos -> semantic graph -> mapping -> VGM -> layout -> SVG/BPMN/Mermaid

Database Product

Logos -> semantic graph -> graph or relational materialization

UI Interaction Product

Logos -> semantic graph -> interaction contract -> generated command surface

Validation

Pipeline validation should verify:

stable IDs survive every product path;
diagnostics identify the stage that produced them;
visual products and data products derive from the same semantic graph;
auxiliary artifacts are versioned or schema-tagged;
generated UI/interaction products do not introduce undocumented commands.

Compatibility

Older projection documentation often treated diagram generation as the pipeline. This specification broadens the term: diagrams are one family of pipeline products, not the whole pipeline.

Open Questions

Which auxiliary JSON products are stable public contracts and which are internal diagnostics?
Should UI form generation use the same mapping registry as diagram targets?

SOTER