Sinapsis Architecture
How computation, data, UDT wire representation and transports fit together.
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
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
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:
| Layer | Responsibility | Detailed specification |
|---|---|---|
| Agent | Declares the graph and its dependencies | Agent Model |
| Template | Transforms data, with explicit split/merge exceptions | Template Model |
| DataContainer | Common semantic input/output boundary for Templates | DataContainers |
| UDT | Represents and exchanges containers across boundaries | UDT Architecture |
| Transport | Moves bytes through a selected mechanism | Wire 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.
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
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.
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
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:
Execution: local, concurrent, queued, remote or distributed scheduling of a declared Agent graph.
Representation: in-memory
DataContainerobjects or a versioned UDT wire representation.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
Agent Model — declarative computation topology, dependencies and branch behavior.
Template Model — transformations, mutations and split/merge ownership.
UDT Architecture — data model and exchange contract.
Wire Format — concrete Python 0.1.0 representation and exchange envelopes.
Protocol Implementation — supported scope and implementation layout.
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