Gear architecture

Gears are the atomic logic units of the fluxrig ecosystem. They function as pluggable, high-resolution signal processors, similar to functional modules in a professional patchbay, that can be chained together to form complex, low-latency processing pipelines.

---

Implementation models

The architecture categorizes Gears based on their performance profile, security boundary, and deployment lifecycle.

Native gear (Static / High-performance)

• Role: Hardware Interfacing & System Access.
• Use Case: Low-level I/O (TCP/UDP sockets, Serial, File system) and logic requiring native CPU instructions for ultra-low latency.
• Implementation: Written in Go and compiled directly into the Rack binary.
• Stability: Offers the lowest possible overhead and absolute memory safety.

Wasm gear (Pluggable / Agile)

NOTE

[Planned feature]

• Role: Business Logic & Signal Transformation.
• Use Case: Risk scoring, data normalization, protocol validation, and dynamic routing.
• Implementation: Designed to execute WebAssembly (Wasm) via an embedded runtime.
• Capabilities: Sandboxed execution and "hot-reloadable" logic without process reboots.

Virtual gear (Remote / Centralized)

• Role: Global Orchestration.
• Use Case: Logic that runs within the Mixer but is patched into an edge pipeline via the Snake Tunnel.
• Strategy: Ideal for global registry lookups, long-running business workflows, or cross-cluster state synchronization.

---

The port model

Communication between Gears is strictly governed by Ports, standardized entry and exit points that enforce signal integrity.

Port anatomy

Every Gear defines its interaction boundary via named ports:

1. Name: Unique identifier (e.g., in, out, err).
2. Direction: Input (Sink) or Output (Source).
3. Contract: Defines the expected state of the signal (e.g., raw_bytes, parsed_payload).

Dynamic ports

Ports can be allocated at Configuration Time to support complex routing topologies.

• Array Mapping: A configuration specifying outputs: 3 will dynamically generate out_0, out_1, and out_2.
• Keyed Mapping: A definition specifying routes: [visa, amex] will generate out_visa and out_amex.

TIP

Port Aliasing: To improve architectural clarity, you can rename standard ports in your Scenario YAML (e.g., mapping out to to_settlement_hub).

---

Functional categories

Gears are primarily classified by their role in the signal path (I/O, Codec, or Logic).

NOTE

For the complete library of available Gears, their configuration schemas, and sector-specific implementations (e.g., ISO8583, Modbus), see the Operations & Logic: Gear Catalog.

---

Gear lifecycle

To ensure deterministic behavior and simplified troubleshooting, Gears adhere to a standard high-fidelity lifecycle contract managed by the Rack supervisor:

Hook	Description
Init	Loads configuration, establishes internal service bindings via the GearContext, and registers observability metrics.
Start	Signals the gear to begin active operations (e.g., opening listener sockets or initializing Wasm sandboxes).
Process	The high-speed hot-path for processing incoming signals, performing validation, and executing business logic.
Drain	Instructs the gear to complete pending transactions without accepting new input to prevent data loss.
Stop	Final graceful resource recovery, closing physical sockets and flushing remaining buffers.

---

High-resolution observability

Gears are observable by default, with telemetry tapped directly from the execution path:

• Non-Intrusive Tracing: Every logic execution is automatically wrapped in an OpenTelemetry span without manual instrumentation.
• Performance Metrics: Throughput (mps) and processing latency (μs) are exposed via the Rack's embedded exporter.
• Error Correlation: Gear-level failures are captured and linked to the active traceID for rapid root-cause analysis.