SOTER

Logowanie
> Welcome > Archive > SpecTechnicalArchitectureSpec

SOTER Technical Architecture Specification

Purpose

This document defines SOTER's module architecture from the implementation perspective: the compiler pipeline's technical components, the hexagonal (ports and adapters) boundary between the core engine and its infrastructure, the product scope and design challenges the architecture must solve, the canonical grammar rules for element definitions and facts, and the interim documentation access policy.

Identity, axioms, and ontology foundations are defined separately in PhilosophyConstitution.md. Milestones and roadmap are tracked in PhilosophyConstitution.md § Vision, History & Strategic Roadmap.

SOTER rejects manual diagram drawing in favor of a deterministic textual language using the Docs-as-Code approach:

  • Logos DSL and Text-First: An indentation-based DSL allows for versioning models in Git. Changes are diffable, enabling code review of business processes.
  • Separation of Model and View (CQRS): A single .model file can generate an infinite number of filtered, dynamic .view projections.
  • Iron Auditor Loop and Ledger: An Event Sourcing system records events in a bitemporal, immutable .fact file. Errors are corrected by new correcting facts rather than erasing history.
  • Hollow Client: Server-Driven UI powered dynamically via WebSockets/SSE, preventing logic drift between the frontend and the engine.

Scope

This document covers:

  • the compiler pipeline's technical components (parser, analyzer, graph, materialization stores, projections, web interface, linter/formatter);
  • the in-place source modernization (Auto-UUID) mechanism;
  • the repository directory structure;
  • the Hexagonal Architecture (Ports and Adapters) boundary between the core engine and infrastructure/frontend adapters;
  • product scope, user stories, and the key technical design challenges;
  • the expansion strategy and current implementation limits;
  • canonical grammar rules for element definitions, facts, .api, .view, and .interaction;
  • the interim documentation access policy (directory naming and public/private/protected visibility).

Non-Goals

Terminology

Term Meaning
Pipeline The deterministic, 7-step compilation assembly line that turns Logos source files into AST, graph, materialized stores, and projections.
AST Abstract Syntax Tree produced by the Lark-based parser from .model / .view / .fact / .interaction source text.
LIBERAL_ID A human-authored, semantically meaningful identifier that Auto-UUID modernization replaces with a stable UUID in place.
VGM Virtual Graph Model — the layout/coordinate adapter that renders the pure ontology graph into notation-specific visual output (BPMN, D2, PlantUML).
Hollow Client The Server-Driven UI client: it interprets .view and .interaction definitions pushed from the server rather than holding independent business logic.
Ledger The Fact Ledger & Providence adapter that computes cryptographic hashes and appends immutable facts.
Strict Mode The business-logic linter mode that audits the compiled graph for rule violations (Pure Waste, Silent Edit, Circular Loop, etc.).

Model or Contract

Technical Components

Parser (core/parser.py)

The grammar of the Logos language is based on the Lark library. The key component is SOTERIndenter, which overrides Lark's default indentation handling to correctly interpret the block structure of .model and .view files.

  • Input: raw text of .model / .view / .fact / .interaction files.
  • Output: AST tree (lark.Tree).

Analyzer (core/linter.py)

Semantic analysis of the AST tree:

  • Builds a global symbol table (UUID → element attributes).
  • Detects references to non-existent UUIDs.
  • Runs the strict mode linter (attribute ordering, required fields).
  • Detects cycles in include directives.

Graph (core/pipeline/graph.py + NetworkX)

Builds a directed graph (DiGraph) based on the symbol table:

  • Nodes: element, gateway.
  • Edges: relationship.
  • Handles same and vague operators (Implicit Flow Resolver):
  • same — internal reference to the output status in the same element.
  • vague — a point requiring expansion up or down the stream.

Materialization — SQLite (core/pipeline/store.py)

SQLite database as a fast, searchable model index:

  • Rebuilt on every compilation (not the source of truth).
  • Schema maps directly to Logos attributes plus localized labels (@lang).
  • Designed for BI integration (PowerBI, Metabase, DBeaver).
  • Location: out/<model>.sqlite3.

Materialization — KuzuDB (core/pipeline/store.py)

Property graph database for Cypher queries:

  • Initialized once per project (not rebuilt like SQLite).
  • Schema: Element nodes, Relationship edges with full attributes.
  • Location: out/kuzu/.

Projections — Visual Generators (analytics/projections/)

Module Output Format Description
d2_generator.py D2 → SVG/PNG Default diagram renderer.
bpmn_generator.py BPMN 2.0 XML Export to BPMN-compatible tools.

Filters and views use the slice_view() algorithm with touching-only / all / none modes (description: ADR-004). The detailed cascade of projector and format configuration priorities is defined in the projection specification tracked from ProjectionOverview.md.

Web Interface (Hollow Client & Epiphany) (portal/portal/)

The Django server (configured via portal/gateway_admin/ and run via portal/application/ logic) provides the backend with streaming interfaces (Epiphany) and the Hollow Client for visualization:

  • REST API — endpoints to list models, views, databases, and logs.
  • SSE (Server-Sent Events) — push notifications and streaming of the pre-compiled AST interface (UI-AST) on file changes.
  • No static GUI files in the classical sense; application logic is served and maintained from the backend (Server-Driven UI pattern).
  • Default port: 8000.

Design guidelines and CSS tokens for portal interfaces (modeled after the Carbon Design System) are defined in DesignSystemSpec.md, DesignSystemSpec.md, and DesignSystemSpec.md.

Linter and Formatter (core/linter.py / soter-fmt)

Two levels of validation:

  1. Stylistic Linter — checks attribute order (type → name → functional → metadata). Run as a pre-commit hook.
  2. Business Logic Linter (Strict Mode) — audits rules (Pure Waste, Silent Edit, Circular Loop, etc.). Rules description: ManualAnalyst.md § Level 2 Compilation.

soter-fmt automatically sorts attributes upon saving.

In-Place Source Modernization (Auto-UUID)

The pipeline implements a mechanism for automated source code modernization. If the auto_uuid flag is enabled (default):

  1. Loader detects LIBERAL_ID type identifiers and generates stable UUIDs for them.
  2. Tracer (LogosTracer) opens the source files at the end of the process and performs physical replacement of identifiers with UUIDs, preserving structure and comments.

The pipeline/ module is responsible for sequencing, error handling, and propagation of exit codes.

Directory Structure (1_soter/)

core/                  ← Core compiler engine, parser, validator, and pipeline steps
├── pipeline/          ← Orchestration package (7 steps)
│   ├── __init__.py    ← Entry point (run_pipeline)
│   ├── loader.py      ← File loading, Include Resolver, Auto-UUID Logic
│   ├── tracer.py      ← LogosTracer: In-place Source Modernization
│   └── context.py     ← PipelineContext (state and settings)
├── config.py          ← SOTER config file parser
├── linter.py          ← Strict mode business rules & soter-fmt
├── logger.py          ← Custom execution logging
├── parser.py          ← Lark Grammar + SOTERIndenter
└── workspace.py       ← Tenant and user workspace handling
analytics/             ← Projectors, visual engines & simulators (D2, BPMN, PlantUML)
├── projections/       ← Renderers and adapters (D2, BPMN, PlantUML)
└── simulator/         ← Existence engine & validation models
portal/                ← Web Gateway administration and Django portals
├── application/       ← Business services, UI context & workflows
├── gateway_admin/     ← Django main project settings & configuration
└── portal/            ← Django app (views, URLs, middleware & templates)
ledger/                ← Workflows ledger, crypto & storage operations
cli/
└── commands/          ← Autoloaded CLI commands (build, commit, verify)
soter.py               ← Primary CLI entry script

Hexagonal Architecture (Ports and Adapters)

To manage complexity and ensure clean segregation of concerns, SOTER is designed using the Hexagonal Architecture pattern (also known as Ports and Adapters or Microkernel architecture). This architecture isolates the logical core from visual rendering, infrastructure backends, and frontend frameworks.

The Core (Hexagon Interior / Pure Domain)

The core SOTER Engine processes organizational truths. It has zero knowledge of databases, file formats, network protocols, HTML, or visual layout coordinates. It is strictly responsible for:

  • Parser (core/parser.py): Compiling indentation-based Logos DSL syntax into an Abstract Syntax Tree (AST).
  • Ontology Engine (core/pipeline/graph.py): Transforming the AST into a directed logical graph (using NetworkX).
  • Strict Mode Linter (core/linter.py): Auditing the logical graph to identify dead paths, unresolved loops, role conflicts (ontological dissonance), and compliance violations.

Ports (Boundary Interfaces)

Ports define abstract boundary interfaces (sockets) through which the core communicates with the outer world. The Core only declares the events it emits or the commands it accepts, remaining unaware of what sits on the other end:

  • Auditing Port: "An event occurred; capture its metadata."
  • Projection Port: "Here is the compiled logical graph for rendering."

Adapters (External Circle / Plugins)

Adapters translate the language of the external world (infrastructure, visualization libraries, and frameworks) into the domain models of the core (Driving Adapters) and vice versa (Driven Adapters):

  • Fact Ledger & Providence Adapter (ledger/): Listens to the auditing port, computes cryptographic hashes, and appends facts to the ledger database (SQLite/FS). Changing the storage backend from SQLite to a graph database or PostgreSQL only requires swapping this adapter; the core remains unchanged.
  • Virtual Graph Model (VGM) & Projectors Adapter (analytics/projections/): Fetches the pure ontology graph from the core, performs font metrology, calculates visual positioning via layout solvers, and outputs notation-specific files (BPMN, D2, PlantUML).
  • Hollow Client Adapter (portal/portal/): Handles interactive I/O. It interprets .view and .interaction definitions, translating them into Server-Driven UI updates pushed to the client via Server-Sent Events (SSE).
  • Integration Adapters: Listening to state transitions in the graph to trigger actions in external systems (ERP, SAP, API webhooks).

Product Scope, User Stories & Design Challenges

SOTER is a full-fledged, event-sourced engine (Event Sourcing) tracking real-world business processes. It provides a digital footprint of organizational reality with cryptographic non-repudiation, matching strict regulatory requirements (such as NIS2 or DORA in the financial sector).

User Stories

  • As a Business Analyst: I want to write business rules in clean text (Logos DSL) without having to manually draw and arrange diagram shapes and arrows.
  • As an Executive: I want to view the real-time state of organizational processes in the browser, with the absolute guarantee that what is displayed corresponds exactly to the compiled process code.
  • As an Auditor: I want to have a cryptographically secure, immutable log of events (Ledger) proving who, when, and on what basis made a business decision.

Key Technical Challenges

  • Visual Stability (The Butterfly Effect): Translating Logos code into diagrams is deterministic (re-compiling the same .model always yields the same .bpmn or .svg). However, small semantic changes in the model can cause massive, unpredictable shifts in the rendered layout. SOTER solves this via the Virtual Graph Model (VGM) coordinate containment.
  • Notation Portability: Projecting a single source of truth (Logos) to multiple different layout standards (e.g., BPMN choreography, UML class diagram) without coupling the core logic to any single notation standard.

Expansion Strategy (Future)

Detailed plan: PhilosophyConstitution.md § Vision, History & Strategic Roadmap.

Key technical directions:

  • LSP Server — Language Server Protocol for Logos files (error highlighting in the editor, go-to-definition).
  • soter watch — file watcher + SSE push → hot-reload of diagrams without Ctrl+F5.
  • Graph Exports — GraphML/JSON (Gephi), Neo4j (Cypher), RDF/SPARQL (Semantic Web).

For SOTER to maintain its "negentropic" function, it must have hard edges:

  • It is not a diagram "drawer": SOTER is not for "pushing pixels". A diagram is merely a rigorous projection of Logos code.
  • It is not a "soft" management system: It ignores office politics and bluff. It operates on a hard balance of mass and energy.
  • No syntax sugar: In Strict Mode, Logos intentionally removes shortcuts, forcing the model author into full awareness and rigor of recording.
  • Implementation limits: The current implementation (Milestone 1) is about 15% of the system's potential.
  • The model is not autonomous: SOTER does not "think" for the architect. It is a compiler of reality — ontological errors of the modeler will be compiled.
  • Rejection of defaults: Most actions require explicit intent and autonomy. The absence of these fields is a fatal error.

Language and Architectural Assumptions

The following clarifications are enforced in the runtime, examples, tests, and tooling. They are supplementary to, and do not replace, PhilosophyConstitution.md.

Rules

Canonical Element Definition Line

The canonical element u-uuid() definition rule, its rationale, and the .model composition and dependency contract are specified in LogosModelFileSpec.md; not repeated here.

Facts and Their Identifiability

A fact can have its own u-uuid, but this is not the business or integration identifier of the Ledger.

  • The fact u-uuid serves solely for SOTER debugging.
  • The fact u-uuid does not serve to manage the graph, ongoing operational work, or to identify the fact by external systems.
  • A fact should enter the Ledger with a dedicated sending identifier field originating from the source system.
  • It is the sending system that is responsible for the complete identifiability of its fact towards Providence.

Ontological consequence: for SOTER itself, facts are not unique. The Ledger may attempt to heuristically distinguish them by declared source, recording time, content, or other metadata, but these are not reliable methods. This behavior is conscious and consistent with the phenomenological assumption: full identifiability of a fact does not stem from SOTER's perception itself, but from the responsibility of the sending system.

Temporary Status of .api

.api's current status as a temporary mirror of .interaction, and the conditions for superseding that status, are specified in LogosApiFileSpec.md; not repeated here.

.view and .interaction Grammar Negative Rules

The .view/.interaction grammar negative rules (button, action) and the open vocabulary question are specified in LogosViewFileSpec.md and LogosInteractionFileSpec.md; not repeated here.

Documentation Access Policy

Directory and File Naming

Documentation directories use lower_case names, for example:

docs/01_guide/
docs/01_guide/manuals/
docs/02_spec/
docs/03_philosophy/
docs/assets/

Markdown files use CamelCase.md, for example:

Quickstart.md
ArchitectureDecisions.md
BpmnProjectionImplementation.md
DocumentationAccessPolicy.md

Non-Markdown documentation assets are stored in one shared directory, docs/assets/. This includes files such as Mermaid diagrams, SVG files, BPMN files, PNG files, JSON/Postman collections, and other documentation attachments.

Visibility Rules

  • Public — served by Portal without authentication: README.md, CHANGELOG.md, LICENSE.md, docs/WELCOME.md (the public documentation welcome page).
  • Private — other Markdown files in the repository root, private by default, for example AGENTS.md, AGENTS_GUARDRAILS.md, AGENTS_DICTIONARY.md, CLAUDE.md. These files are intended for the SOTER development team and AI/developer tooling.
  • Protected — all other Markdown files under docs/ are protected by default: visible to authenticated Portal users, but not public anonymous users, for example docs/01_guide/Quickstart.md, docs/01_guide/manuals/Manual.md, docs/02_spec/Architecture.md, docs/03_philosophy/Constitution.md.
  • Tenant-Scoped — not implemented yet. The target future convention is docs/tenants/{tenant}/. No tenant-level documentation access is assumed in the current implementation.

A page/document must not be assembled from multiple Markdown files with different visibility levels. Visibility belongs to the whole Markdown file. Portal should eventually resolve documentation visibility per file.

Examples

element u-4f2e1c8a()

docs/protected/2_spec/TechnicalArchitectureSpec.md   -> protected
README.md                                            -> public
AGENTS_GUARDRAILS.md                                 -> private

Validation

  • The Stylistic Linter (pre-commit hook) checks attribute order (type → name → functional → metadata) on every .model / .view / .fact / .interaction file.
  • The Strict Mode Business Logic Linter audits the compiled graph for Pure Waste, Silent Edit, Circular Loop, and related rule violations; see ManualAnalyst.md § Level 2 Compilation.
  • soter-fmt automatically sorts attributes upon saving and should be run before commit.

Compatibility

  • The current implementation (Milestone 1) covers about 15% of the system's intended potential; the Expansion Strategy above lists the planned technical directions.
  • .api is treated as a mirror image of .interaction until a dedicated M2M membrane specification supersedes this assumption.
  • The documentation access policy is an interim convention. The full public, protected, private, and tenants/{tenant} model (compatible with the target SEOS documentation model) will be implemented later; tenant-scoped documentation does not exist yet.

Open Questions

  • The .view/.interaction vocabulary open question (the button / Command question) is tracked in LogosViewFileSpec.md and LogosInteractionFileSpec.md; not repeated here.
  • The tenant-scoped documentation model (docs/tenants/{tenant}/) is not implemented; scope and access rules remain to be defined.

Related Documents

SOTER v1.12.0-beta