1.2 Architecture Overview

Architecture Overview

corpus-ipc is the schema and transport layer for Limen-Neural SNN runtimes (spike and neuromodulator wire protocol plus IPC transports; README / src/lib.rs as of 08d2f28). Application code talks to IpcBackend; BackendFactory selects RustBackend or (feature zmq) ZmqIpcBackend. Optional feature server builds corpus_ipc_server, a thin Axum 0.8 binary over corpus_ipc::server::router. Structured messages use IpcMessage with fail-closed wire-version gating via decode_ipc_message_json / encode_canonical_ipc_message. Feature zmq also exposes structured PUB/SUB (zmq_message) and ZmqHybridFlowBackend (#55).

Sources: src/lib.rs, README.md

Request path: REST to backend to ZMQ readout

Real flow in the tree: HTTP client → Axum router → AppState → IpcBackend::process_batch → (when ZMQ is selected) bounded SUB drain → parse_readout_packet.

flowchart LR
  Client["HTTP client"] -->|"POST /process JSON"| Router["corpus_ipc::server::router"]
  Router --> AppState["AppState Mutex + AtomicBool"]
  AppState -->|"process_batch"| Trait["IpcBackend"]
  Trait --> Rust["RustBackend"]
  Trait --> Zmq["ZmqIpcBackend"]
  Zmq -->|"DONTWAIT drain up to 64 msgs / 5 ms"| Sub["zmq::Socket SUB"]
  Pub["External PUB"] -->|"i64 tick + N x f32 LE"| Sub
  Sub --> Parse["parse_readout_packet"]
  Parse --> Cache["last_readout cache"]
  Cache --> Trait

Loading

Sources: src/server.rs, src/bin/corpus_ipc_server.rs, src/zmq_backend.rs, src/zmq_readout.rs

Structured IpcMessage transport (feature zmq, #55)

Separate from binary readout and from REST. Publisher binds; subscriber connects; hybrid adapter maps spikes/embeddings out and gradients/traces in.

flowchart LR
  Caller["HybridFlowBackend caller"] --> HF["ZmqHybridFlowBackend"]
  HF -->|"Spikes / Embeddings"| Pub["ZmqMessagePublisher"]
  Pub -->|"canonical WireEnvelope JSON"| PeerIn["Peer SUB"]
  PeerOut["Peer PUB"] -->|"canonical WireEnvelope JSON"| Sub["ZmqMessageSubscriber"]
  Sub -->|"GradientUpdate / EligibilityTraces"| HF
  HF --> Caller

Loading

Sources: src/zmq_message/, 3.4

Module map

Layer	Modules	Feature
Traits / factory	trait_def	always
Native backend	rust_backend	always
ZMQ binary readout + parser	zmq_backend, zmq_readout	zmq
Structured ZMQ IpcMessage	zmq_message	zmq
Wire models	models	always
Validation	validation	always
Envelope + canonical encode	compatibility, canonical_ser	always
REST router	server	server
Binary	bin/corpus_ipc_server	server

Wire vs float-vector paths

• Structured hybrid-flow JSON: IpcMessage envelopes (WireCompatibility::CURRENT = 1). Encode with encode_canonical_ipc_message; decode with decode_ipc_message_json. Over ZeroMQ: 3.4. Spec: docs/wire-encoding.md.
• ZMQ binary readout: ZmqIpcBackend is a SUB consumer of i64 tick + N×f32 LE frames. It does not implement HybridFlowBackend and does not auto-split 88-byte frames into neuromodulator scores.
• REST: wraps IpcBackend only; does not speak IpcMessage JSON or binary readout frames.

Child pages

• 1.1 Getting Started
• 1.3 Crate Exports and Module Map
• 3.2 ZmqIpcBackend
• 3.4 Structured ZeroMQ IpcMessage Transport
• 5.4 Canonical Wire-v1 Encoding
• 6.1 REST API Endpoints