How sciencecorp/synapse-api works
Project Type and Purpose
• Project type: A protocol‐only repository providing gRPC/Protobuf definitions and UDP streaming interfaces for neural interface devices.
• Purpose: Standardize control‐plane operations via gRPC and high‐throughput data streaming via UDP across a variety of “nodes” (e.g., spike detector, optical stimulation).
File Structure
• Top‐level folders:
– .github/: CI checks (e.g., proto‐check).
– api/: All .proto files organized into a flat set plus a nodes/ subfolder.
• Key files:
– api/*.proto: Common messages (channel, time, status, etc.).
– api/nodes/*.proto: Definitions of each processing “node.”
– build.sh: Build or validate the proto files.
• No runtime code here—this repo is the canonical schema for clients and servers in multiple languages.
README for Insights
• Describes two main I/O planes:
– Control plane over gRPC (RPC calls for configuration, status, commands).
– Data plane over UDP (raw/time‐sensitive streaming).
• Encourages usage of client libraries (Python, C++, TS/Node) that wrap these proto definitions.
Main Components
a. Protobuf Schema Layer
– The api/ folder: shared message definitions and service contracts.
b. Control Plane (gRPC)
– gRPC server implementing the Synapse services.
– Client libraries (Python, C++, TS/Node) invoking RPC methods.
c. Data Plane (UDP)
– High‐throughput streaming endpoints (e.g., raw neural data, spikes).
– Packet receiver on server side and packet sender on device side.
d. Node Processing Units
– Each .proto in api/nodes/ describes a functional block (e.g., spike_detector, disk_writer).
– These can be standalone microservices, plugins, or threads in the server.
e. External Neural Interface Devices
– Actual hardware or simulators producing or consuming data.
Relationships & Architecture Patterns
• Clients ↔ gRPC Control Plane ↔ Node Config & Status
• Clients ↔ UDP Data Plane ↔ Node Data Streams
• Node Chaining
– Some nodes forward data to others (e.g., spike_source.proto → spike_detector.proto → spike_binner.proto).
• Layering
– Top layer: Client applications
– Middle layer: Synapse API services (control and data planes)
– Bottom layer: Hardware/Node implementations
Important Architectural Patterns
• Separation of Concerns: Control vs. Data plane.
• Pluggable Node Architecture: Each node proto defines a self‐contained processing unit.
• Language‐agnostic Interfaces: Proto contracts ensure every client—regardless of runtime—sees the same API.
• CI Gatekeeping: .github/workflows/proto-check.yaml enforces schema consistency.
Final Checklist
[ ] Node chaining illustrated where applicable
[ ] Call out the build/CI step (build.sh, proto‐check) as an ancillary process