> > > GuideManualDeveloper

SOTER Developer & Engineer Manual — System Implementation

Audience

Software engineers, backend developers, and systems integrators who work on or extend the Logos compile pipeline, database materialization, and the Hollow Client server-driven UI.

Goal

Understand the seven-stage Logos compile pipeline, the JIT Auto-UUID mechanism, how compiled models are materialized into SQLite and KuzuDB, and how the Hollow Client renders UI from server-driven UI-AST, so that changes to the engine or its integrations respect the existing architecture.

Prerequisites

Familiarity with the pipeline code in modules/pipeline/.
Familiarity with Lark grammar (for the parser stage) and NetworkX (for graph resolution).
Familiarity with SQLite and Cypher/KuzuDB query syntax.
Familiarity with Server-Sent Events (SSE) or WebSockets (for the presentation pipeline).

Workflow

Loader: read the target .model and execute structural references (include).
Auto-UUID Injection: scan source files for plain-text identifiers, generate stable UUIDs, and update files in-place using LogosTracer.
Parser: compile the concrete syntax tree (CST) using Lark grammar and custom indentation rules.
Analyzer: validate semantic models and build a central Symbol Table.
Graph Resolution: resolve implicit workflows and construct NetworkX directed graphs.
Materialization: build relational indices (SQLite) and Cypher graph schemas (KuzuDB).
Projection: export the model into presentation artifacts (D2 diagrams, BPMN 2.0 XML).
For interactive UI, keep analytic views (.view) free of interactive components; place interactive bindings in .interaction files and let the presentation pipeline serve them:
Epiphany backend reads .interaction files.
Compiles a declarative JSON AST representing the UI contract (UI-AST).
Streams the UI-AST over SSE (Server-Sent Events) or WebSockets.
The Hollow Client browser shells interpret the UI-AST dynamically and draw the DOM. No local application logic exists in the browser.

Commands

JIT Auto-UUID rewriting, shown before and after a compile run:

# BEFORE compilation
element MyAction
    type: Action

# AFTER compilation (modified in-place)
element u-550e8400-e29b-41d4-a716-446655440000()
    type: Action
    name: "MyAction"

Database materialization targets:

SQLite Index: relational tables include elements (UUID, type, name, attributes) and relations (source, target, carriers). Used for BI and standard SQL queries.
KuzuDB Graph: used for topological path tracing.

Example Cypher query against the KuzuDB graph:

MATCH (s:Element)-[r:Relationship]->(a:Element)
WHERE s.type = "Subject" AND a.type = "Action"
RETURN s.name, a.name

Expected Result

Running the pipeline against a .model produces a compiled Symbol Table, a materialized SQLite index and KuzuDB graph, and exported projection artifacts (D2 diagrams, BPMN 2.0 XML). Interactive screens render entirely through the Hollow Client from server-pushed UI-AST, with no client-side application logic.

Troubleshooting

Compile touches files you did not expect to change

Cause:

Stage 2 (Auto-UUID Injection) rewrites plain-text identifiers to stable UUIDs in-place via LogosTracer. This is expected behavior, not a bug: the file's business naming reference is preserved as the name attribute.

Fix:

Review the diff to confirm only identifier rewriting occurred; commit the rewritten file rather than reverting it.

Interactive components appear in a `.view` file