Architecture overview¶

Who this is for

This page is for architects and system designers who need a concise overview of how Semantiva fits into a wider system.

It assumes you are comfortable with pipelines and components (Pipeline users, Framework developers & component authors) and have skimmed Inspection Payload & CLI.

Execution core¶

Semantiva executes directed graphs of nodes built from YAML configuration. Nodes wrap processors that handle either the data channel or the context channel:

The data channel carries the primary payload data.
The context channel (payload.context) carries metadata and intermediate values, validated via observers.
Nodes are instantiated by factories; processors remain stateless and reference types via input_data_type / output_data_type declarations.

The execution engine compiles YAML into a Graph (GraphV1), assigns stable semantic identifiers, and drives each node while keeping data/context separated for traceability. In production, these graphs are built from YAML pipeline configurations validated and versioned as configuration artefacts of record (see Pipelines - YAML & CLI). For development and R&D purposes, the same execution engine can also be driven from Python (see Pipelines in Python), but those programmatic pipelines are treated as internal tooling, not as governed configuration.

Inspection & trace stack¶

Semantiva treats inspection and tracing as first-class citizens:

Inspection Payload & CLI builds a configuration-only, deterministic payload for CLI and UI consumers.
Semantic Execution Record (SER) v1 describes the Semantic Execution Record (SER); the full schema is in SER v1 JSON Schema.
Runtime emits a JSONL Trace Stream v1 with SERs and lifecycle records; Trace Aggregator v1 provides aggregation and completeness checks.
Graph alignment guidance lives in Trace ↔ Graph Alignment.
Run-space orchestration surfaces in Run Space (v1): blocks that expand context and Run-Space Lifecycle.

Contracts & invariants¶

Contracts are machine-checkable architecture rules enforced by linting (Semantiva Contracts). They codify processor invariants (e.g., probes are read-only, context writes are declared) and trace identity expectations. The SVA catalog remains authoritative; this page is a map, not a substitute.

Extension & integration points¶

Semantiva is extensible through component families and registries:

Author processors following Creating Components (Authoring Guide); register them via extensions (Extending Semantiva (Registries & Extensions)).
The registry model and namespacing are covered in Registry System.
Context processing internals and observer wiring are detailed in Context Processing Architecture.
Pipeline schema and validation rules live in Pipeline Configuration Schema.
Execution wiring and transports are outlined in Execution.
Visual inspection and debugging are supported by Semantiva Studio Viewer.