> > > SpecModelDrivenHexagonalArchitectureDiagram

Model-Driven Hexagonal Architecture Diagram

Purpose

This document defines a Model-Driven Development (MDD) view of SOTER using the Hexagonal Architecture pattern. It shows how Logos source artifacts drive the domain core, which then communicates with projection, ledger, persistence, UI, and integration adapters through explicit ports.

Scope

This document covers:

the MDD artifact flow from text source to semantic model, graph, projections, ledgers, and UI surfaces;
the hexagonal boundary between the SOTER core and its adapters;
the primary driving adapters that invoke the core;
the driven adapters that materialize output, audit facts, and communicate with external systems;
the governance and verification loop around the model.

Non-Goals

This document does not redefine the Logos grammar; see LogosLanguageSpec.md.
This document does not define projection schemas in detail; see ProjectionOverview.md.
This document does not define Akasha storage and fact envelopes in detail; see AkashaLedgerOverview.md.
This document does not replace the architecture specification; see TechnicalArchitectureSpec.md.

Terminology

Term	Meaning
MDD	Model-Driven Development: source models drive generated views, ledgers, UI surfaces, and read models.
Driving adapter	External adapter that invokes the core through an input port.
Driven adapter	External adapter called by the core through an output port.
Port	Abstract boundary between the pure core and infrastructure or presentation concerns.
Core hexagon	Parser, analyzer, ontology graph, linter, semantic model, and reconciliation rules that must not depend on concrete storage, rendering, or UI frameworks.
VGM / Visual Kernel	Core visual subsystem that turns the semantic model into a canonical visual phenotype model.
Akasha Protocol	Non-optional fact-ledger protocol and envelope format, analogous in role to HTTP plus a data format such as JSON or XML.
Akasha Ledger	Concrete ledger implementation that persists facts using the Akasha Protocol.

Model or Contract

Model-driven hexagonal architecture

Canonical SVG artifact: model_driven_hexagonal_architecture.svg.

The diagram uses four explicit rings: adapters, ports, application core, and domain core. Primary adapters drive the left side of the hexagon. Secondary adapters are driven from the right side. The dependency direction points toward the domain except where the core explicitly calls an output port.

VGM is shown inside the core, not as an external adapter. Text-only SOTER is sufficient for automation, CI, service operation, shell clients, and audit pipelines. Visual SOTER is the complete human-facing system for learning, design, diagnosis, simulation, and team collaboration. VGM is therefore a core visual subsystem: renderers, forms, widgets, browser UI, and drag-and-drop tools are adapters; the canonical visual phenotype model is not.

Rules

Logos artifacts drive the system. Generated views, read models, and UI surfaces are outputs, not sources of truth.
The core hexagon must not depend on concrete databases, renderers, HTTP frameworks, editor APIs, or browser UI libraries.
Ports express semantic needs: compile this model, render this graph, record this fact, materialize this read model, or expose this interaction state.
Adapters may be replaced without changing the core model semantics.
Reconciliation is a feedback loop: facts recorded through ledger adapters are compared against the semantic model and can produce dissonance, planning work, or model updates.
Akasha Protocol is fixed inside SOTER. Ledger engines may vary, but SOTER has one fact-ledger protocol boundary.
Akasha Ledger means a concrete ledger implementation, not the protocol itself.

Fact and Ledger Modes

SOTER supports three simplified operating modes for facts:

Analytical / design / minimal mode. No ledger is required. Facts are plain .fact files fed into the pipeline with an indicated .model for confrontation. The pipeline writes its result to a log file or to STDOUT / STDERR.
Default mode. SOTER uses Akasha Protocol plus Akasha Ledger. The default backend is expected to support at least two implementation profiles: filesystem directory tree storage with *-observed-envelope.fact / *-observed-payload.fact file pairs, and one selected database-backed ledger, likely a JSON-oriented NoSQL database.
Hybrid / third-party provider mode. SOTER still uses Akasha Protocol, because the protocol is fixed and non-extensible inside SOTER, but delegates persistence to a third-party ledger engine.

Examples

Analyst Authoring Loop

editor or Git -> model authoring port -> application services
application services -> parser -> analyzer -> semantic model
semantic model -> VGM / visual kernel -> projection port -> renderers

Fact Reconciliation Loop

.fact file or external event -> fact intake port -> reconciler -> semantic model
semantic model -> audit port -> Akasha Protocol -> ledger implementation
ledger implementation -> fact intake port -> reconciler -> dissonance

Server-Driven Interaction Loop

portal command -> interaction port -> application services
application services -> semantic model -> UI state port -> Hollow Client

Validation

This diagram should be checked whenever one of these documents changes:

Compatibility

The diagram is compatible with the current documentation state in which SOTER uses Logos as its canonical model source, VGM as its core visual subsystem, Akasha Protocol as the fixed fact-ledger protocol, optional ledger implementations as adapters, and the Hollow Client / Epiphany portal as the server-driven UI surface.

Open Questions

Which database-backed Akasha Ledger implementation should become the default: RavenDB or another JSON-oriented NoSQL engine?
Should filesystem-backed Akasha Ledger storage remain a first-class default backend or only a development/reference profile?