# cafanasyev/py-sapient-sdk architecture

> Architecture diagram of the GitHub repository cafanasyev/py-sapient-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cafanasyev/py-sapient-sdk
- Repository: https://github.com/cafanasyev/py-sapient-sdk

## Overview

py-sapient-sdk is a Python SDK for SAPIENT sensor and effector interoperability. An application implements the Node contract, configures a dispatcher and TCP client, then registers nodes; the dispatcher manages registration, status reports, and message routing while the transport exchanges typed messages with a fusion node. Major capabilities include lifecycle jitter, connection monitoring and reconnection, and optional TLS/mTLS. The graph follows documented behavior and shown calls; unsampled implementation details are omitted.

Main entry points: [`src/sapient_sdk/transmission/dispatcher.py`](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/dispatcher.py) (Node dispatcher), [`src/sapient_sdk/transmission/node_wrapper.py`](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/node_wrapper.py) (Node lifecycle), [`src/sapient_sdk/transport/socket_client.py`](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/socket_client.py) (Socket client), [`src/sapient_sdk/transport/client.py`](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/client.py) (Client interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Node lifecycle"]
  node_node["Node contract<br/>[node.py]"]
  node_wrapper["Node lifecycle<br/>[node_wrapper.py]"]
  node_config["Dispatcher config"]
  node_jitter["Lifecycle jitter<br/>[jitter.py]"]
  node_taskutils["Task utilities<br/>[_task_utils.py]"]
end

subgraph group_dispatch["Message dispatch"]
  node_dispatcher["Node dispatcher<br/>[dispatcher.py]"]
end

subgraph group_transport["TCP transport"]
  node_client["Client interface<br/>[client.py]"]
  node_socketclient["Socket client<br/>[socket_client.py]"]
  node_state["Connection state"]
  node_framing["Message framing<br/>[framing.py]"]
  node_provider["Socket provider<br/>[socket_provider.py]"]
end

node_app(("Application"))
node_fusion(("Fusion node"))

node_app -->|"registers nodes"| node_dispatcher
node_app -->|"implements"| node_node
node_dispatcher -->|"creates"| node_wrapper
node_wrapper -->|"polls and calls"| node_node
node_wrapper -->|"publishes lifecycle messages"| node_dispatcher
node_wrapper -->|"uses settings"| node_config
node_wrapper -->|"gets delays"| node_jitter
node_dispatcher -->|"uses settings"| node_config
node_dispatcher -->|"starts and publishes"| node_client
node_dispatcher -->|"routes callbacks"| node_node
node_dispatcher -->|"monitors connection"| node_state
node_dispatcher -->|"cancels tasks"| node_taskutils
node_wrapper -->|"cancels tasks"| node_taskutils
node_client -->|"exposes state"| node_state
node_socketclient -->|"implements"| node_client
node_socketclient -->|"opens connection"| node_provider
node_socketclient -->|"reads and writes frames"| node_framing
node_socketclient -->|"updates state"| node_state
node_fusion -->|"sends TCP messages"| node_socketclient
node_socketclient -->|"sends TCP messages"| node_fusion
node_app -.->|"configures TLS optionally"| node_provider

click node_node "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/node.py"
click node_dispatcher "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/dispatcher.py"
click node_wrapper "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/node_wrapper.py"
click node_config "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/dispatcher_config.py"
click node_jitter "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/jitter.py"
click node_taskutils "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/_task_utils.py"
click node_client "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/client.py"
click node_socketclient "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/socket_client.py"
click node_state "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/connection_state.py"
click node_framing "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/framing.py"
click node_provider "https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/socket_provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node,node_wrapper,node_config,node_jitter,node_taskutils toneBlue
class node_dispatcher toneAmber
class node_client,node_socketclient,node_state,node_framing,node_provider toneMint
class node_app,node_fusion toneIndigo
```

## Components

### Node lifecycle

- [Node contract](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/node.py): `src/sapient_sdk/transmission/node.py`
- [Node lifecycle](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/node_wrapper.py): `src/sapient_sdk/transmission/node_wrapper.py`
- [Dispatcher config](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/dispatcher_config.py): `src/sapient_sdk/transmission/dispatcher_config.py`
- [Lifecycle jitter](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/jitter.py): `src/sapient_sdk/transmission/jitter.py`
- [Task utilities](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/_task_utils.py): `src/sapient_sdk/_task_utils.py`

### Message dispatch

- [Node dispatcher](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transmission/dispatcher.py): `src/sapient_sdk/transmission/dispatcher.py`

### TCP transport

- [Client interface](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/client.py): `src/sapient_sdk/transport/client.py`
- [Socket client](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/socket_client.py): `src/sapient_sdk/transport/socket_client.py`
- [Connection state](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/connection_state.py): `src/sapient_sdk/transport/connection_state.py`
- [Message framing](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/framing.py): `src/sapient_sdk/transport/framing.py`
- [Socket provider](https://github.com/cafanasyev/py-sapient-sdk/blob/master/src/sapient_sdk/transport/socket_provider.py): `src/sapient_sdk/transport/socket_provider.py`

### Other components

- **Application**
- **Fusion node**

## Connections

- Application → Node dispatcher: registers nodes (evidence: `README.md`)
- Application → Node contract: implements (evidence: `README.md`)
- Node dispatcher → Node lifecycle: creates (evidence: `src/sapient_sdk/transmission/dispatcher.py`)
- Node lifecycle → Node contract: polls and calls (evidence: `src/sapient_sdk/transmission/node_wrapper.py`)
- Node lifecycle → Node dispatcher: publishes lifecycle messages (evidence: `src/sapient_sdk/transmission/node_wrapper.py`)
- Node lifecycle → Dispatcher config: uses settings (evidence: `src/sapient_sdk/transmission/node_wrapper.py`)
- Node lifecycle → Lifecycle jitter: gets delays (evidence: `src/sapient_sdk/transmission/node_wrapper.py`)
- Node dispatcher → Dispatcher config: uses settings (evidence: `src/sapient_sdk/transmission/dispatcher.py`)
- Node dispatcher → Client interface: starts and publishes (evidence: `src/sapient_sdk/transmission/dispatcher.py`)
- Node dispatcher → Node contract: routes callbacks (evidence: `README.md`)
- Node dispatcher → Connection state: monitors connection (evidence: `src/sapient_sdk/transmission/dispatcher.py`)
- Node dispatcher → Task utilities: cancels tasks (evidence: `src/sapient_sdk/transmission/dispatcher.py`)
- Node lifecycle → Task utilities: cancels tasks (evidence: `src/sapient_sdk/transmission/node_wrapper.py`)
- Client interface → Connection state: exposes state (evidence: `src/sapient_sdk/transport/client.py`)
- Socket client → Client interface: implements (evidence: `src/sapient_sdk/transport/socket_client.py`)
- Socket client → Socket provider: opens connection (evidence: `src/sapient_sdk/transport/socket_client.py`)
- Socket client → Message framing: reads and writes frames (evidence: `src/sapient_sdk/transport/socket_client.py`)
- Socket client → Connection state: updates state (evidence: `src/sapient_sdk/transport/socket_client.py`)
- Fusion node → Socket client: sends TCP messages (evidence: `README.md`)
- Socket client → Fusion node: sends TCP messages (evidence: `README.md`)
- Application → Socket provider: configures TLS optionally (evidence: `README.md`)
