Ring interaction architecture decision record and full implementation specification
This document formalizes the technical architecture for ring gesture input, touch input, and haptic feedback across the Gestura stack. It intentionally excludes business-case arguments and focuses on durable technical decisions, transport contracts, safety, validation, and a blocker-first delivery plan that avoids future architectural rework.
Decision
Gestura will adopt a transport-agnostic device protocol as the semantic core for ring interactions. The host application remains the trusted orchestration surface and talks to hardware or simulators through adapters rather than transport-specific business logic.
BLE support will use a hybrid approach: standard Bluetooth services where they fit, plus one versioned Gestura custom service for gesture, touch, haptics, capability discovery, control, and device state. Simulator and MCP integrations will use the same semantic model with transport-specific encodings.
Scope, non-goals, and guardrails
Goals
- • Define one durable contract for ring gesture input, touch input, and haptic output.
- • Keep simulator, host app, BLE hardware, and MCP integrations behaviorally aligned.
- • Support future wearable classes without reopening the protocol core.
Non-goals
- • This document does not justify market demand, pricing, or business positioning.
- • This document does not lock firmware implementation details beyond externally visible contracts.
- • This document does not require HID-first behavior except as an optional future companion mode.
Guardrails
- • The app remains the trusted orchestration surface for device access and policy.
- • Standard BLE services are used where they fit; Gestura-specific semantics stay in a versioned custom service.
- • Feature completion means shipping protocol, transport, tests, observability, docs, and operational readiness together.
Usage model and actors
Direct interaction
A user performs a gesture or touch pattern that should produce immediate host-side action with bounded latency and deterministic semantics.
Haptic feedback loop
The host responds with semantic or parametric haptics for confirmation, warning, mode changes, or guided workflows.
Simulator-first development
Engineers and designers must be able to exercise the exact same protocol using a simulator over local transports before hardware is present.
Third-party automation
External systems consume device state and invoke actions through MCP without reimplementing BLE or internal transport logic.
Trusted input mode
Only explicitly enrolled devices may trigger privileged or sensitive actions, with clear identity, lifecycle, and policy enforcement.
Future wearable expansion
The contract must generalize beyond a single ring model to adjacent wearable devices without a breaking redesign.
Target architecture
Layered model
- • Shared device protocol crate as the single semantic source of truth.
- • Host application transport abstraction that hides BLE, simulator local transport, and future adapters.
- • BLE surface composed of BAS + DIS + one custom Gestura service for device semantics.
- • Simulator domain core with BLE, local socket/WebSocket, and MCP adapters on top of one behavior model.
- • Host-side MCP bridge that exposes tools, resources, and notifications using the same protocol semantics.
Canonical domain requirements
- • Gesture and touch events must be semantic first, with raw streams optional and clearly separated.
- • Haptics must support both semantic intents and parametric control.
- • Capability discovery and state snapshots must be first-class, not inferred from traffic.
- • Every command and event must be versioned, correlated, and safe to replay or resynchronize where needed.
| Transport | Encoding | Primary role |
|---|---|---|
| BLE GATT | Compact binary payloads using a versioned envelope and fragmentation strategy when required. | Real ring parity, interoperability, low-latency event streaming, trusted device lifecycle. |
| Local socket or WebSocket | JSON payloads using the same semantic schema as BLE. | Fast local development path for simulator use, deterministic testing, and debugging. |
| MCP bridge | JSON-compatible resources, tools, and notifications mapped from the shared protocol. | External automation, agent orchestration, observability-friendly integrations. |
Canonical domain model
The protocol core must describe the device in semantic terms that survive transport changes, simulator substitution, and future hardware evolution. If a concept cannot be represented in the shared domain model, it is not ready to be treated as a platform feature.
Identity and capability surface
- • Stable device identifier, model family, hardware revision, firmware revision, and protocol version.
- • Capability flags for gestures, touch modes, haptic channels, enrollment features, diagnostics, and optional raw streams.
- • Support for future wearable profiles through extensible capability negotiation rather than hard-coded ring-only assumptions.
Semantic input model
- • Gesture and touch are semantic event types first, not raw sensor streams disguised as app logic.
- • Each event carries timing, sequence, confidence, source mode, and optional metadata for interpretation and debugging.
- • Raw sensor streams are optional adjunct channels with explicit opt-in and separate lifecycle rules.
Haptic output model
- • Semantic haptics cover intent-level outcomes such as confirm, warn, error, guide, and notify.
- • Parametric haptics cover intensity, duration, repetition, waveform or pattern selection, and channel or zone if supported.
- • Completion, rejection, and degraded-execution results must be observable to the host.
Command, result, and state model
- • All commands and events live inside a versioned envelope with request correlation, timestamps, and sequencing.
- • State snapshots include battery, health, calibration, connection mode, streaming mode, and trust state.
- • Errors must be typed at the semantic layer so transport failures and business-policy denials are distinguishable.
BLE contract
Required standard services
Battery Service and Device Information Service are mandatory baseline services. Device Information should include manufacturer, model, firmware revision, hardware revision, and a stable device identifier when policy permits exposure.
Custom Gestura service
- • Capability characteristic: read device class, protocol version, supported gestures, touch modes, haptic features, and trust features.
- • State characteristic: read and notify for mode, health, calibration state, session state, and any non-BAS runtime data.
- • Command ingress characteristic: write-with-response for haptic requests, configuration changes, enrollment actions, and transport control.
- • Event egress characteristic: notify gesture events, touch events, state transitions, acknowledgements, warnings, and failures.
- • Optional diagnostics characteristic: development-only logs and protocol traces.
Reliability requirements
- • Use notifications for event streaming and write-with-response for commands.
- • Include sequence numbers and timestamps so the host can detect gaps and recover state.
- • Define fragmentation and reassembly rules for payloads that exceed practical MTU limits.
- • Require reconnect resubscription and snapshot resync behavior after interruptions.
- • Apply host-side filtering in addition to advertisement filtering when platform BLE stacks are inconsistent.
Connection, session, and recovery lifecycle
A complete feature requires a full lifecycle contract, not just a successful connection. The system must define how sessions begin, become operational, degrade, recover, and end.
Discover
The host scans, locally filters, inspects advertised capabilities, and decides whether a device is eligible for connection or enrollment workflows.
Connect and inspect
The transport adapter connects, reads capabilities and baseline state, verifies protocol compatibility, and establishes a session context.
Subscribe and activate
The host subscribes to event streams, confirms snapshot synchronization, and enables the required gesture, touch, or haptic operating mode.
Operate
Commands, haptic requests, semantic events, and state transitions flow with correlation identifiers, timestamps, and clear failure semantics.
Interrupt and recover
Connection loss, missed notifications, degraded sensors, and incompatible firmware trigger explicit recovery, re-sync, or fail-closed behavior.
Disconnect and revoke
The host tears down subscriptions, persists or clears trust state as policy requires, and records enough diagnostics for supportability.
Simulator, local transport, and MCP
Simulator model
The simulator is a device-core emulator, not a BLE-specific application. All behavior, timing, deterministic scenarios, and fault injection live in the emulator core; BLE, local socket/WebSocket, and MCP-facing adapters are thin transport layers.
MCP model
MCP is a host-side bridge. Resources expose device catalog, capabilities, state, and event history. Tools invoke actions such as scanning, connecting, pairing, sending haptics, calibrating, and triggering simulator scenarios. Notifications carry live events and operational logs.
Trust, safety, privacy, and degraded behavior
Trust lifecycle
Discovered
Device is visible and inspectable but may not trigger privileged actions.
Bonded
BLE secure pairing completed; device may exchange operational traffic subject to app policy.
Enrolled
User or administrator explicitly approves the device for trusted interaction flows.
Attested (future)
Hardware-backed identity or signed challenge flow strengthens long-term trust and fleet scenarios.
Safety and privacy requirements
- • Untrusted or degraded devices must never silently trigger privileged actions.
- • Sensor confidence, calibration quality, and capability mismatches must be observable to the host and operator.
- • Sensitive telemetry exposure through MCP must be intentional and policy-gated.
- • Unsupported firmware or incompatible protocol versions must fail closed with actionable diagnostics.
Platform realities and implementation constraints
Cross-platform behavior is part of the architecture, not a later QA concern. The delivery plan must recognize transport and permission differences across host environments from the start.
macOS
Document and validate Bluetooth permission handling, entitlement behavior, reconnect semantics, and production signing implications for the host application.
Linux
Assume BlueZ-specific filtering quirks and require host-side post-filtering plus explicit parity testing for simulator peripheral implementations.
Windows / future host targets
Treat Windows as a first-class future target in the abstraction design even if early parity coverage is weaker than macOS and Linux.
Cross-platform simulator strategy
The simulator must always offer a transport that works reliably without BLE peripheral support so development and validation never depend on one host stack.
Validation and operational readiness
Required test layers
- • Contract fixtures and schema validation for protocol compatibility.
- • Simulator parity tests across BLE and local transports.
- • Host integration tests for discovery, pairing, reconnection, subscriptions, and haptic round-trips.
- • Interoperability tests with virtual peripherals and periodic real-device smoke coverage.
Operational requirements
- • Structured logs and protocol event traces that support user reports and CI triage.
- • Clear runbooks for connection failures, trust failures, firmware mismatch, and degraded sensors.
- • Documentation updates must ship with the feature set, not in a later cleanup pass.
- • Platform quirks for macOS, Linux, and future Windows support must be tracked explicitly.
Blocker-first implementation program
The architecture is only considered complete if implementation is executed in dependency order. The workstreams below are intentionally written as blockers and blocked work so the team can reach full feature completeness without reopening foundational design later.
Required specification artifact set
- • ADR with technical decision, scope, and invariants.
- • Shared protocol schema package with message fixtures and compatibility policy.
- • BLE service contract with characteristics, advertisement policy, and recovery rules.
- • Host transport interface definition and lifecycle ownership notes.
- • Simulator parity matrix across BLE and local transports.
- • Trust-policy specification, degraded-mode behavior, and operator runbooks.
BLOCKER: Shared device protocol contract
Blocks: All transport work, simulator convergence, MCP stabilization, and trust policy implementation.
Required outputs
- • Canonical types for identity, capabilities, state snapshots, commands, results, events, gesture/touch semantics, and haptic semantics.
- • Versioning policy, compatibility rules, request correlation, sequence numbering, and timing semantics.
- • Golden fixtures and machine-readable schema output for downstream consumers.
Exit gate
- • All transports can map to the same semantic model without ad hoc translation tables.
- • Representative fixtures exist for discovery, gesture stream, touch stream, haptic command, errors, and reconnect state recovery.
BLOCKER: BLE device contract
Blocks: Real device parity, scan filtering, host/device interoperability, and production connection behavior.
Required outputs
- • Battery Service and Device Information Service requirements with mandatory fields and conformance notes.
- • Custom Gestura service with capability, state, command ingress, event egress, and optional diagnostics characteristics.
- • Advertisement strategy, MTU handling, fragmentation, reliability, reconnect, and local filtering policy.
Exit gate
- • A simulator peripheral and a real ring can both satisfy the same host-side contract.
- • BLE edge cases are defined for duplicate events, reconnect resync, missing notifications, and degraded transport conditions.
BLOCKER: Host transport abstraction in gestura-app
Blocks: Replacement of mock-first ring logic and any reliable multi-transport rollout.
Required outputs
- • Stable app-side interface for scan, connect, pair, subscribe, send haptics, and retrieve snapshots.
- • Lifecycle ownership for discovery, session management, retries, resubscription, and teardown.
- • Compatibility layer that preserves existing app command surfaces while internals are replaced.
Exit gate
- • Current app API commands remain stable while simulator local transport and BLE central adapters both conform.
- • Transport-specific behavior is isolated from UI and business workflows.
BLOCKED BY P0: Simulator convergence
Blocks: High-confidence testing, demos, and developer productivity.
Required outputs
- • Single emulator core that owns state transitions, scenarios, timing, and event production.
- • BLE peripheral adapter, local socket/WebSocket adapter, and MCP-facing adapter over the same core.
- • Deterministic scenario playback for gestures, touch sequences, disconnections, and haptic acknowledgements.
Exit gate
- • The same scenario yields equivalent semantic outputs across all simulator transports.
- • Developers can validate behavior without hardware while still preserving hardware parity expectations.
BLOCKED BY P0: Trusted device and safety model
Blocks: Privileged input workflows and production-grade enrollment UX.
Required outputs
- • Enrollment and trust-state transitions with explicit permissions and revocation behavior.
- • Policy layer for what actions require discovery only, bonding, enrollment, or future attestation.
- • Safety behavior for stale identity, unsupported firmware, degraded sensors, and partial capability mismatches.
Exit gate
- • Privileged actions cannot be reached by untrusted devices.
- • Operators have clear diagnostics for why a device is blocked, degraded, or denied.
BLOCKED BY all core contracts: Validation, operations, and release readiness
Blocks: Sustainable rollout, supportability, and confidence in future changes.
Required outputs
- • Contract, parity, interoperability, regression, and failure-recovery tests.
- • Structured diagnostics, event tracing, support bundles, and CI coverage for key platform paths.
- • Developer-facing operational documentation covering quirks, failure modes, and rollout checklists.
Exit gate
- • Release readiness is measured by explicit acceptance gates rather than best-effort confidence.
- • A future device or firmware revision can be onboarded without architecture rediscovery.
P0 blocker artifacts
These are the three implementation-critical specifications that must exist before the rest of the delivery program can move safely. They are kept inside the main ADR route so they are guaranteed to be published in the current site build.
BLE device contract
- • Mandatory BAS and DIS support aligned with the shared protocol identity and health surface.
- • One custom Gestura service with capability, state, command ingress, event egress, and optional diagnostics characteristics.
- • Advertisement requirements for service UUIDs, protocol major version, device family, and simulator markers when relevant.
- • Reliability rules for write-with-response commands, notification streams, fragmentation, reconnect, resubscription, and snapshot resync.
Host transport abstraction
- • One app-facing transport boundary for scan, connect, pair, snapshot retrieval, event subscription, command dispatch, and disconnect.
- • Explicit lifecycle ownership for retries, resubscription, reconnect, teardown, and degraded-state transitions.
- • Compatibility commitment that preserves current app command surfaces while removing mock-first internals.
- • Typed host-side error classes that distinguish transport failure, compatibility failure, policy denial, and degraded device state.
Execution workstream artifacts
The following artifacts define the remaining execution streams after the P0 specifications. They do not claim the engineering work is complete; they define what must be true before those streams can be considered implemented and closed.
Simulator convergence
- • One emulator core owns state transitions, timing, scenario playback, fault injection, and semantic event production.
- • BLE peripheral, local socket or WebSocket, and MCP-facing adapters remain thin projections over the same emulator core.
- • Deterministic scenarios cover gesture flows, touch flows, disconnects, reconnects, haptic acknowledgements, and degraded sensor states.
- • Parity is measured at the semantic protocol level, not by transport-specific byte-for-byte equivalence.
Trusted device and safety model
- • Trust state transitions must be explicit across discovered, bonded, enrolled, revoked, and future attested states.
- • Privileged actions require policy gating tied to stable device identity, compatible firmware, and current degraded-state checks.
- • Revocation, stale identity, unsupported firmware, and degraded sensors must fail closed with operator-visible reasons.
- • MCP and host-app surfaces must enforce the same trust outcomes rather than maintaining separate security interpretations.
Validation and release readiness
- • Contract tests validate schemas, fixtures, compatibility policy, and envelope handling across transports.
- • Parity tests prove simulator BLE and simulator local transports emit equivalent semantic outcomes for equivalent scenarios.
- • Interoperability and host-integration tests cover discovery, pairing, reconnect, subscription restoration, and haptic round-trips.
- • Operational readiness includes structured diagnostics, CI gates, support runbooks, and release checklists with explicit pass criteria.
Definition of complete implementation
The program is not complete when the ring merely connects or when gestures and haptics work in one happy-path demo. It is complete only when the architecture, transports, policies, validation layers, and operator guidance all meet the same contract.
- • The shared protocol crate is the only place where gesture, touch, haptic, and state semantics are defined.
- • Real hardware, simulator local transport, and simulator BLE transport all produce equivalent semantic events for equivalent scenarios.
- • The app can recover from disconnects, re-establish subscriptions, and resynchronize state without undefined behavior.
- • Trusted-device policy is enforced consistently across the app and MCP bridge.
- • Schemas, diagnostics, and operator documentation are published with the code, not deferred.
- • Validation gates exist for contract fixtures, BLE interoperability, simulator parity, and host integration regressions.