Docs /architecture/ Sinapsis Architecture
architecture / system

Sinapsis Architecture

How computation, data, UDT wire representation and transports fit together.

architectureoverviewsystemsDocumentation latest

Sinapsis separates computation, semantic data, representation and exchange, and physical transport. These concerns meet at the DataContainer boundary without having to share an implementation.

The architecture at a glance

◇ DiagramMermaid diagram
flowchart TD
    subgraph EXEC[Computation]
      AG[Agent: declarative graph] --> TE[Template nodes]
    end
    subgraph DATA[Semantic data]
      TE --> DC[DataContainer]
      DC --> DP[Typed DataPackets and payloads]
    end
    subgraph EXCH[At a system boundary]
      DC -. encode if crossing boundary .-> UDT[UDT representation / exchange]
      UDT --> W[Versioned wire format]
      W --> TR[Transport: HTTP / queue / TCP / storage]
    end

This Mermaid syntax uses the standard renderer; draggable nodes are available for supported flowcharts.

View Mermaid source
mermaid
flowchart TD
    subgraph EXEC[Computation]
      AG[Agent: declarative graph] --> TE[Template nodes]
    end
    subgraph DATA[Semantic data]
      TE --> DC[DataContainer]
      DC --> DP[Typed DataPackets and payloads]
    end
    subgraph EXCH[At a system boundary]
      DC -. encode if crossing boundary .-> UDT[UDT representation / exchange]
      UDT --> W[Versioned wire format]
      W --> TR[Transport: HTTP / queue / TCP / storage]
    end

The main building blocks are:

LayerResponsibilityDetailed specification
AgentDeclares the graph and its dependenciesAgent Model
TemplateTransforms data, with explicit split/merge exceptionsTemplate Model
DataContainerCommon semantic input/output boundary for TemplatesDataContainers
UDTRepresents and exchanges containers across boundariesUDT Architecture
TransportMoves bytes through a selected mechanismWire Format

Start with the concepts if this is new terminology; the pages in architecture/ contain the detailed technical contracts.

Local versus remote data flow

Locally, Templates may pass Python DataContainer objects directly; wire serialization is not automatically required on every graph edge.

◇ DiagramMermaid diagram
flowchart LR
    subgraph LOCAL[Single execution environment]
      A[Template A] -->|Python DataContainer| B[Template B]
      B -->|Python DataContainer| C[Template C]
    end

This Mermaid syntax uses the standard renderer; draggable nodes are available for supported flowcharts.

View Mermaid source
mermaid
flowchart LR
    subgraph LOCAL[Single execution environment]
      A[Template A] -->|Python DataContainer| B[Template B]
      B -->|Python DataContainer| C[Template C]
    end

When a boundary is crossed, UDT supplies a representation. The physical transport carries the resulting bytes, and the destination reconstructs the semantic container.

◇ DiagramMermaid diagram
flowchart LR
    subgraph P1[Process A]
      TA[Template A] --> EN[UDT encode]
    end
    EN --> WF[Wire bytes]
    WF -->|Transport| DE[UDT decode]
    subgraph P2[Process B]
      DE --> TB[Template B]
    end

This Mermaid syntax uses the standard renderer; draggable nodes are available for supported flowcharts.

View Mermaid source
mermaid
flowchart LR
    subgraph P1[Process A]
      TA[Template A] --> EN[UDT encode]
    end
    EN --> WF[Wire bytes]
    WF -->|Transport| DE[UDT decode]
    subgraph P2[Process B]
      DE --> TB[Template B]
    end

An exchange boundary could mean process-to-process, service-to-service, machine-to-machine, or an application writing to storage. Serialization is introduced where exchange requires it, not as a compulsory internal operation.

Ownership, enrichment and representation

Templates may enrich an existing packet with annotations or derived data rather than replace it at each step. Branching is more subtle: because mutable Python objects can be shared by reference, DataSplit establishes explicit shallow-copy or deep-copy semantics. DataMerge makes fan-in explicit. See Template Model.

UDT standardizes the outer container and wire contract while allowing each payload to use an efficient representation: arrays may use binary data, dataframes Arrow, custom schemas Protobuf, and large payloads artifact references. See Payload Codecs.

Independent evolution

The architecture separates three independent decisions:

  1. Execution: local, concurrent, queued, remote or distributed scheduling of a declared Agent graph.

  2. Representation: in-memory DataContainer objects or a versioned UDT wire representation.

  3. Movement: selected transport such as HTTP, TCP, queue or storage.

A different scheduler or transport must not redefine the meaning of the Template graph or its DataContainer contract.

Where to go next

Agents define computation. Templates perform computation. DataContainers carry semantic data. UDT represents and exchanges that data. Transports move the representation.

Published from Git revision 7b7ba25d627b