Shared Logic

This layer ensures that the RTT‑App behaves consistently regardless of device, OS version, or implementation details.

Responsibilities of the Shared Layer#

The shared logic layer handles four core responsibilities:

• Classifying local signals into Stable or Unstable.
• Interpreting server‑declared Awareness from the cached endpoint.
• Merging local and server states into a single Awareness state.
• Providing a stable interface for the UI layer to observe state changes.

These responsibilities form the backbone of the RTT‑App v1 architecture.

Local Signal Classification#

Each platform collects its own local signals, but the shared layer performs the classification:

• Stable — network and device signals within expected bounds.
• Unstable — drift detected in timing, jitter, memory pressure, or protocol fallback.

The shared layer receives a simple boolean classification rather than raw metrics. This keeps the logic portable and predictable.

Server State Interpretation#

The shared layer parses and interprets the server‑declared Awareness document:

• Reads the cached JSON payload.
• Validates required fields.
• Applies fallback rules for missing or stale data.
• Reduces the server state to Stable, Unstable, or Unknown.

Unknown is treated as Stable for merge purposes to maintain predictable behavior during outages.

Awareness Merge Logic#

The merge logic is identical across platforms and follows the rules defined in the Awareness model:

• Local stable + Server stable → Clear
• Local unstable + Server stable → Local Drift
• Local stable + Server unstable → Global Drift
• Local unstable + Server unstable → Drift

This logic is implemented once in the shared layer and reused by both iOS and Android.

State Evaluation and Updates#

The shared layer exposes a simple interface for evaluating Awareness:

• Accepts local classification updates.
• Accepts server state updates.
• Computes the new Awareness state.
• Emits state changes to the UI layer.

The shared layer never triggers UI updates directly; it only publishes state changes.

Caching Integration#

The shared layer manages cache interpretation but not storage:

• Platforms handle reading/writing the cache.
• The shared layer validates freshness and expiration.
• Expired or missing data is treated as Unknown.
• The merge logic proceeds using the interpreted state.

This separation keeps the shared layer portable and platform‑agnostic.

Error Handling#

The shared layer applies consistent fallback behavior:

• Invalid server data → treat as Unknown.
• Missing local classification → assume Stable.
• Merge errors → default to Drift.
• No oscillation or intermediate states.

These rules ensure that the Awareness state remains stable even when inputs degrade.

Platform Integration#

Both iOS and Android integrate with the shared layer by:

• Providing local signal updates.
• Providing server state updates.
• Observing Awareness state changes.
• Triggering evaluations at lifecycle boundaries.

This architecture ensures that the RTT‑App behaves the same way on all devices.