CAMDOM -- System Design: Delivered vs Conceptual

An honest post-mortem of what was designed, what was built, what shipped, and what was quietly buried in commented-out code.

1. Conceptual Architecture vs Delivered Product

What Was Designed (Full Vision)

The original CAMDOM vision included a proximity-based alarm system that would automatically detect when devices moved apart and fire the alarm without requiring any manual action. The core idea: use BLE RSSI (Received Signal Strength Indicator) as a proxy for physical distance, and when the signal weakens past a configurable threshold, trigger the alarm.

The designed proximity system had these components:

Client-side RSSI reader (configureClientRSSITimeout): A 15ms tick loop that called connectedDevice.readRSSI() and sent the value to the server as a packet: a:u|rssi|{rssi}|{sense}. This ran at approximately 45fps.
Server-side RSSI aggregator (configureServerRSSITimeout): A 30fps loop that collected RSSI values from all connected clients, computed a rolling window average (last 5 readings per client), and compared the mean against a threshold.
The n:rssi|1 notification packet: A broadcast to all clients announcing that proximity sensors were active, accompanied by a "Proximity Sensors Enabled" snackbar and a ping sound.
The hasAnyoneHigherSensibility negotiation protocol: When a client sent its RSSI packet, it included its local sensitivity setting. The server compared all clients' sensitivity values and used the highest sensitivity (lowest numeric value = most sensitive) as the threshold. This ensured that if one partner wanted tighter proximity detection, their preference would win.
The rssiSense storage key: A configurable sensitivity value (default 60) stored in MMKV, accessible via the Options screen.
Automatic disconnect on distance: If the server-side average RSSI exceeded the threshold for 1000ms, the server would broadcast d:a|a1 (disconnect all), clear the advertising value, and set state to disconnected.
Automatic alarm on distance: If the mean RSSI exceeded the threshold, the server would broadcast a:f|1 (fire alarm) and set distanceAlarmFired = true.

Reconstructed data flow:

Client (phone A)                    Server (phone B - the GATT peripheral)
     |                                        |
     |  readRSSI() every 15ms                 |
     |  ---a:u|rssi|-72|60-->                 |
     |                                        |  store in rssiUpdatesFromClients Map
     |                                        |  maintain rolling window [5 values]
     |                                        |
     |                                        |  every 15ms: compute mean of all clients
     |                                        |  if mean >= threshold (hasAnyoneHigherSensibility ?? rssiSense):
     |                                        |    broadcast a:f|1 --> ALARM
     |                                        |  else after 1000ms:
     |                                        |    broadcast d:a|a1 --> DISCONNECT

What Was Actually Shipped

The proximity system is completely commented out in the production codebase. The commit 2f701d2 ("Disable proximity sensors", Sep 3, 2024) systematically commented out every piece of the proximity pipeline while leaving the infrastructure (timers, storage keys, handler stubs) intact.

What actually shipped as alarm triggers:

App backgrounding while synced (lines 257-276 in BleManager.ts): When the OS moves the app to background, if state is synced, the server plays alarm and broadcasts a:f|1|u. Client reports back a:u|i.
Android blur event while synced (lines 279-300): Android-specific duplicate of the backgrounding logic.
Disconnect attempt by any device (lines 1120-1130): When onDisconnectPressFinish fires and hasAnyoneRequestedToFireWhenDisconnect or the fireAlarmOnDisconnect storage flag is true, the alarm broadcasts a:f|1|a.
Manual alarm via UI button: The onStopAlarmPressStart flow, which is a press-and-hold mechanism requiring all devices to agree before silencing.
Server-side disconnect with fireOnDisconnect=true: When a client sends s:r|1 (meaning it has fire-on-disconnect enabled), the server sets hasAnyoneRequestedToFireWhenDisconnect = true.

The sensitivity slider in Options.tsx exists but does nothing. The original Options page (commit 749d1c8) had sign-out and delete-account buttons plus a privacy policy link. In the current codebase, the sign-out and account-deletion buttons are commented out (lines 117-144 of Options.tsx), and there is no sensitivity slider at all in the current UI. The rssiSense storage key still exists in StorageKeys.ts with its hashed name, and the constructor still initializes it to 60, but nothing reads or writes it from any user-facing interface.

Why It Was Disabled

The git history tells the story. The feature was introduced in commit 749d1c8 (v2.33.0, Aug 20, 2024) titled "Disconnection by distance" and disabled 14 days later in commit 2f701d2 (Sep 3, 2024). The speed of the disable suggests the problems were encountered immediately in testing.

RSSI noise and device-specific behavior:

BLE RSSI values are notoriously unreliable as distance proxies. The raw signal fluctuates wildly based on:

Device orientation (phone held differently in hand vs pocket)
Body proximity (human tissue absorbs 2.4GHz signals)
Environmental reflections (multipath fading)
Device hardware differences (antenna quality varies dramatically between a $100 Android and a$ 1000 iPhone)
Advertising power settings (the code uses ADVERTISE_TX_POWER_HIGH on Android, which maximizes range but also maximizes noise)

A rolling window of 5 samples at 30fps means each sample covers ~16.6ms. RSSI readings at this timescale can vary by 10-15 dBm between consecutive reads, making the "mean" computation meaningless for distance estimation without much heavier filtering.

False positives from signal fluctuation:

The design had the server firing an alarm when the mean RSSI exceeded the threshold. In practice, a momentary signal dip (someone turned their body, or a metal object briefly interfered) would trigger a false alarm. With the sensitivity default set to 60, and typical BLE RSSI values ranging from -30 (very close) to -90 (very far), the threshold mapping was unclear and likely produced false positives in normal usage.

The sensitivity negotiation was broken at a protocol level:

The hasAnyoneHigherSensibility comparison logic (lines 1720-1732) has a subtle bug. When localSensibility < userSense (server is more sensitive than client) AND localSensibility < this.hasAnyoneHigherSensibility, it sets hasAnyoneHigherSensibility = undefined. This means if the server is the most sensitive device, the comparison falls back to sense (the raw storage value), but undefined is not the same as "use local." The negotiation protocol was designed for a world where every device agrees on what "sensitive" means, but RSSI is device-relative, making the whole comparison meaningless.

Battery and performance concerns:

The client-side RSSI reader ran at 15ms intervals (approximately 66fps). readRSSI() is a synchronous BLE operation that blocks the radio. Running it this frequently on both devices simultaneously would:

Double the BLE radio traffic (each device polling the other)
Prevent the radio from handling other BLE operations during the read
Drain battery significantly during extended sessions
Potentially interfere with the GATT indication channel (the indication packets carrying the actual protocol data)

Multi-device averaging complexity:

The server was designed to aggregate RSSI from all connected clients simultaneously. But BLE is a shared medium -- when the server is reading RSSI from Client A, it cannot simultaneously receive packets from Client B. The 30fps tick rate for server-side averaging meant the server was spending most of its time in RSSI reading loops rather than handling the actual protocol.

2. The Shared State Dilemma

The Two State Systems

CAMDOM uses two parallel state management systems because of a fundamental architectural tension in React Native with Reanimated.

React state (useState hooks in app/index.tsx):

appCurrentState -- mirrors appState SharedValue for use in React effects
shouldStartScan -- triggers the scan lifecycle from React effects

Reanimated state (SharedValues):

appState -- the canonical connection state (disconnected, scanning, connecting, connected, synced, alarm, migrating)
ballRadius -- animation target for the ball's size
ballPosition -- where the ball renders (center only now, was left/right/center)
isPeripheralServer -- whether this device is the GATT server
hasConnectionError -- controls error UI visibility
alarmButtonPosition -- position of the alarm button (currently always center)

The Bridge Problem

Reanimated SharedValues live on the UI thread. React state lives on the JS thread. BLE callbacks fire on the native thread. This creates a three-thread coordination problem.

The useAnimatedReaction bridge (lines 421-427):

useAnimatedReaction(
  () => appState.value,
  (prep, previous) => {
    runOnJS(setAppCurrentState)(prep);
  },
  [appState.value],
);

This watches the SharedValue appState and, whenever it changes on the UI thread, posts a message to the JS thread to update appCurrentState. This is necessary because React effects (like the one at line 429 that manages the UI state transitions) can only run on the JS thread.

The reverse bridge (lines 388-399):

useAnimatedReaction(
  () => showRedBall.value,
  (prep, previous) => {
    if (!previous && prep) {
      runOnJS(setShouldStartScan)(false);
    }
    if (previous && !prep) {
      runOnJS(setShouldStartScan)(true);
    }
  },
  [showRedBall.value],
);

The gesture handler sets showRedBall on the UI thread. The bridge translates this to shouldStartScan on the JS thread, which triggers the scan lifecycle effect.

Race Conditions

Race condition: Scan starts while already connecting.

The scan callback (line 569) checks if (this.isConnecting) return; and if (this.connectedDevice) return;. But these checks happen on the native BLE thread, while isConnecting is set on the JS thread (line 638). There is a window where the scan callback fires, sees isConnecting = false, and starts a connection attempt, while a previous connection is still in progress. The try/catch at line 650 catches this, but the error path (line 655-673) resets state to disconnected, potentially interrupting the already-in-progress connection.

Race condition: Alarm fires during disconnect negotiation.

When the server is in the disconnect flow (onDisconnectPressStart polls askedDisconnectionDevices every 500ms), and simultaneously receives an alarm trigger (e.g., the client backgrounded), both paths modify appState and both paths call broadcastPacket. The server could broadcast d:a|a (disconnect accepted) and a:f|1|a (alarm) in the wrong order. The code partially handles this: onDisconnectPressFinish (line 1121-1130) checks hasAnyoneRequestedToFireWhenDisconnect and fires alarm instead of disconnect. But if the alarm fires after disconnect has already been accepted, the state machine can end up in an inconsistent state.

Race condition: Server migrates while client sends packets.

When the server sends m:d|{newServerValue} (migration packet), the client receives it and enters migrating state (line 1404). During this window, the client might still have pending packets queued for the old server. The disconnectFromServer(false) call at line 1409 cancels the connection, but any in-flight write operation on the old connection could throw. The sendPacketToServer method (line 817-866) checks isStillConnected before writing, but there is a TOCTOU (time-of-check-time-of-use) gap between the check and the actual write.

The isAmIClientAllowedToDisconnectEdgeCase flag:

This flag (introduced around commit 458183c, "allow disconnection on special case when server closes the app") solves a specific problem: when the server backgrounded and triggered alarm state, the client received a:f|1|u (fire alarm, type user). The client then set isAmIClientAllowedToDisconnectEdgeCase = true and sent discq:{sessionId} to confirm awareness. Later, when the client tries to stop the alarm, it needs to send a:r|ff (forced disconnect finish) instead of the normal a:r|f (normal alarm stop finish), because the connection is already broken from the server side. Without this flag, the client would try to negotiate a disconnect with a server that has already gone to alarm state.

The naming of this flag (isAmIClientAllowedToDisconnectEdgeCase) is itself a symptom of the complexity. It encodes: "Am I the client? Is this the edge case where the server triggered alarm first and I need to handle disconnect differently?"

The retries SharedValue as circuit breaker (line 307-324):

const retries = useSharedValue(7);

const retryConnect = async () => {
  await sleep(500);
  if (retries.value <= 5 && hasConnectionError.value) {
    retries.value += 1;
    // ... show retry snackbar, restart scanning
  }
};

retries starts at 7, decrements to 0 when scan starts, and allows up to 5 retries. This prevents infinite scan-reconnect loops when the server is unreachable. The use of a SharedValue (instead of a regular variable) suggests this was originally intended to be read from the UI thread for animation purposes, but the current code only reads it from JS via runOnJS.

3. GATT/BLE Device-Specific Issues

Android-Specific

API-level branching in permission requests (requestPermissions.ts):

The code branches on API level 31 (Android 12):

API < 31: Requests ACCESS_FINE_LOCATION (required for BLE scanning on older Android)
API >= 31: Requests the three new Android 12 BLE permissions: BLUETOOTH_SCAN, BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE

This is correct but leaves a gap: API 30 devices need ACCESS_FINE_LOCATION but the code only requests it, not ACCESS_COARSE_LOCATION. Some Android 10-11 devices require both.

The blur event listener (lines 279-300):

Android fires a blur event when the app loses focus (distinct from the background event). This is duplicated from the background handler because Android can blur the app without fully backgrounding it (e.g., when a dialog overlays the app). The duplicate code is a maintenance risk -- any change to the alarm logic must be applied in both places.

GATT server callback differences in BleManager.kt:

The Android native code (BleManager.kt) uses a classic BluetoothGattServer implementation with explicit characteristic subscription management via CCCD (Client Characteristic Configuration Descriptor). The gattServerCallback (line 550) handles onDescriptorWriteRequest and onDescriptorWrite manually, maintaining a subscribedDevices set. This is more explicit than the iOS implementation, which relies on CoreBluetooth's built-in subscription tracking.

Notable Android-specific issue: the gattCallback.onConnectionStateChange (line 318) has a TODO comment: "timeout timer: if this callback not called - disconnect(), wait 120ms, close()". This timeout was never implemented. On some Android devices, onConnectionStateChange is never called (the BLE stack hangs), leaving the app stuck in Connecting state indefinitely.

Android 6 (API 24) minimum support:

The commit c379064 ("android 6") explicitly adds pre-Marshmallow BLE scan settings (scanSettingsBeforeM at line 185). This fallback uses ScanSettings.Builder without setMatchMode or setNumOfMatches, which means the scan is less aggressive on older devices. The minimum API level 24 means the codebase must handle both the legacy BluetoothManager API and the modern permission model.

The advertisingLocalValue split (line 504-507):

this.advertisingLocalValue =
  Platform.OS === "ios"
    ? this.randomIntFromInterval(1, 124)
    : this.randomIntFromInterval(126, 249);

iOS devices advertise values 1-124, Android devices advertise 126-249. This is how the server election works: the higher number wins and becomes the GATT server. Since Android values are always higher, Android always becomes the server when paired with an iOS device. This is intentional -- iOS CoreBluetooth has limitations as a GATT server that Android does not.

iOS-Specific

400ms scan delay (line 716):

setTimeout(async () => {
  await this.blePlxManager.startDeviceScan(...)
}, Platform.OS === "ios" ? 400 : 0);

iOS requires a delay before starting BLE scanning after advertising. CoreBluetooth's CBCentralManager needs time to initialize and transition to the poweredOn state. Without this delay, the scan starts before the BLE stack is ready, resulting in silent failure. This 400ms value was determined empirically (there is no official Apple documentation specifying the required delay).

CBPeripheralManager vs Central role:

The iOS implementation (BlePeripheralManager.swift) uses CBPeripheralManager (Peripheral role) for the server side. The react-native-ble-plx library handles the Central role (scanning, connecting). iOS limits the number of concurrent peripheral connections, and CBPeripheralManager and CBCentralManager share the same Bluetooth radio. Running both simultaneously on iOS can cause contention.

value: nil characteristic pattern (line 78-86 in BlePeripheralManager.swift):

let charForRead = CBMutableCharacteristic(type: uuidCharForRead,
                                          properties: .read,
                                          value: nil,    // <-- nil value
                                          permissions: .readable)

On iOS, creating a CBMutableCharacteristic with value: nil means the characteristic has no initial value. The server responds to read requests dynamically (line 186-194). This is the iOS way of creating a "dynamic" characteristic. Android handles this differently -- the onCharacteristicReadRequest callback always returns the current advertised name.

BLE state restoration (line 164-173 in BleManager.ts):

this.blePlxManager = new BlePlxManager({
  restoreStateIdentifier: "camdom-app",
  restoreStateFunction: (restoredState) => {
    if (restoredState) {
      this.connectedClients = restoredState.connectedPeripherals.map(
        (p) => p.id,
      );
    }
  },
});

iOS supports BLE state restoration, which allows the app to resume BLE operations after being terminated by the system. The restoreStateIdentifier tells CoreBluetooth to save the BLE state under this key. When the app relaunches, the restoreStateFunction receives the previously connected peripherals. The implementation only restores connectedClients -- it does not restore sessionId, isServer, or appState, meaning the restored connection is partially broken.

Cross-Platform Inconsistencies

MTU negotiation (line 909):

this.connectedDevice = await this.connectedDevice.requestMTU(53);

MTU 53 bytes is chosen because:

BLE 4.0 default MTU is 23 bytes (5 bytes header + 18 bytes payload)
Negotiating to 53 gives 48 bytes of usable payload
The base64-encoded protocol packets are typically under 48 bytes
Higher MTU values are not reliably supported on older Android devices
iOS ignores MTU requests entirely (CoreBluetooth negotiates automatically)

However, the code never checks if the negotiation succeeded. If the server rejects the MTU request, the default 23-byte MTU applies, and packets larger than 18 bytes (after base64 encoding overhead) will be silently truncated or cause write errors.

Legacy scan (line 562):

legacyScan: true,

This flag tells the scan to use Android's legacy scan format instead of the modern extended advertisement format. It is set to true for backwards compatibility with older Android devices, but it means the scan cannot detect advertisements larger than 31 bytes.

Advertising data format differences:

Android's advertiseData (line 525-528 in BleManager.kt) includes the service UUID but NOT the device name (setIncludeDeviceName(false)). The device name is set separately via bluetoothAdapter.setName(name). The scan response includes the device name (line 131-134 in BleManager.kt). iOS includes the device name in the advertisement itself (CBAdvertisementDataLocalNameKey).

This asymmetry means iOS devices are visible to scanners immediately, while Android devices only reveal their name after a scan response request. The code in BleManager.ts handles this by reading device.localName which react-native-ble-plx populates from either the advertisement or the scan response.

4. Error Handling & Recovery

What Is Handled

Error	Handling	Location
BLE state becomes PoweredOff/Unauthorized/Unsupported	Full state reset to disconnected, clear all arrays/maps	`onStateChange` (line 303-334)
Advertising failure	Snackbar error message, state reset, check iOS Bluetooth permission	`onStartAdvertising` (line 353-403)
Scan error	Snackbar, state reset to disconnected, stop scanning	Scan callback error (line 571-582)
Connection timeout	7500ms `scanningTimeout` + 5000ms additional wait, then disconnect+retry	`configureScanTimeout` (line 720-768)
Write failure (sendPacketToServer)	If state is already `connected`/`synced`/`alarm`/`disconnected`, silently return; otherwise disconnect + state reset	`sendPacketToServer` (line 817-866)
Permission denied	`requestPermissions` flow with callback	`requestPermissions.ts`
Device connection error (GATT status != SUCCESS)	Android: logs error but does NOT disconnect (line 346-351, commented-out disconnect code). iOS: handled by react-native-ble-plx	`gattCallback.onConnectionStateChange`
Scan timeout (7500ms with no server found)	If not connecting and not already synced: reset to disconnected, disconnect, stop scan/advertising, restart scan	`configureScanTimeout` (line 720-768)
Sound loading failure	`isSoundsLoaded` flag prevents attempts to play	`bindSoundEffects` (line 177-215)

What Is NOT Handled

Missing Error	Consequence	Severity
GATT 133 (random error on Android)	App stuck in Connecting state indefinitely. The TODO at line 344 says "close() and try reconnect" but the code is commented out.	High
GATT server crash (gattServer becomes null)	No recovery mechanism. The server simply stops responding. Clients will timeout.	High
Concurrent connection attempts	Two devices could both try to connect to each other simultaneously. The number-based election (higher = server) prevents this in theory, but race conditions during the election window can cause both devices to connect as clients.	Medium
Memory pressure from sound loading	`Promise.all` loads 5 audio files simultaneously (line 178). On low-memory devices, this could cause OOM. No try/catch around `Promise.all`.	Medium
Font loading failure	`useFonts` returns a nullable `fontMgr`. The `paragraph` derived value checks for null (line 638: `if (!fontMgr
Skia canvas rendering errors	No error boundary around the Canvas component. A rendering error would crash the entire app.	Medium
MMKV storage corruption	No integrity check on MMKV storage. If `rssiSense` or `fireAlarmOnDisconnect` become corrupted, the app could behave unpredictably.	Low
`onCamdomLogoPressed` partial state reset	The method (line 1757-1787) resets state but does not clear `sessionId`, `connectionPacketSent`, or `hasReceivedDisconnectFromServer`. This could leave the BleManager in a partially reset state.	Medium
`disconnectFromServer` swallows errors	The `cancelConnection()` call (line 793) is wrapped in a try/catch that does nothing with the error. If cancellation fails, `connectedDevice` is still set to undefined, but the actual connection may still exist.	Medium

5. The Disconnect Protocol (State Machine)

The disconnect protocol is the most complex subsystem in CAMDOM. It uses a custom packet-based state machine with 7 distinct sub-states and 4 packet types.

Packet Types

Packet	Direction	Meaning
`d:r\|s`	Client -> Server	"I want to disconnect" (request start)
`d:r\|f`	Client -> Server	"I released the button" (request finish)
`d:r\|1`	Client -> Server	"I agree to disconnect" (consent)
`d:r\|ff`	Client -> Server	"Force disconnect" (edge case: server already in alarm)
`d:a\|r`	Server -> Client	"Disconnect rejected"
`d:a\|a`	Server -> Client	"All agreed, disconnect accepted"
`d:a\|a1`	Server -> Client	"Final disconnect confirmation"
`discq:{sessionId}`	Client -> Server	"Confirm disconnect queue"
`disca:1`	Server -> Client	"Disconnect queue confirmed"
`pong:{sessionId}`	Server -> Client	"Keepalive response"
`ping:{sessionId}`	Client -> Server	"Keepalive ping"

Complete Flow: Normal Disconnect

Phase 1: Initiation (Client holds disconnect button)
==========================================
Client: onPressIn -> onDisconnectPressStart()
  - isDisconnectButtonPressed = true
  - If server: start polling interval (500ms)
  - If client: sendPacketToServer("d:r|s")
  - Clear scanningTimeout

Server: receives "d:r|s"
  - Adds client to askedDisconnectionDevices[]

Phase 2: Polling (Server checks every 500ms)
==========================================
Server: serverDisconnectionTimeout fires
  - Checks: askedDisconnectionDevices.length === connectedClients.length
  - If ALL clients have requested disconnect:
    - Sets serverAlreadyShouldDisconnect = true
    - Broadcasts "d:a|a" to all clients in askedDisconnectionDevices
    - Clears interval

Client: receives "d:a|a"
  - Sends "d:r|1" back to server

Phase 3: Acceptance
==========================================
Server: receives "d:r|1" from client
  - Adds client to allowedClientsToDisconnect[]
  - If server button is still pressed AND all clients have agreed:
    - Broadcasts "d:a|a1" (final confirmation)
  - Otherwise:
    - Sends "d:a|a1" to the individual client

Client: receives "d:a|a1"
  - Sets hasReceivedDisconnectFromServer = true
  - Clears sessionId
  - Calls disconnectFromServer() -> plays unpair sound, resets state

Phase 4: Cleanup
==========================================
Server: onDisconnectPressFinish()
  - If no clients left or serverAlreadyShouldDisconnect:
    - Plays unpair sound
    - Resets state to disconnected
    - Calls stopAdvertising(true)
    - Clears all arrays, timers, and flags

Edge Case: Server Backgrounds During Sync

Server app goes to background while synced:
  - AppState listener fires (line 257-276)
  - Server: plays alarm, sets appState="alarm", broadcasts "a:f|1|u"

Client: receives "a:f|1|u"
  - Sets isAmIClientAllowedToDisconnectEdgeCase = true
  - Sends "discq:{sessionId}" to confirm awareness
  - Sets appState="alarm"

Later, client tries to stop alarm:
  - onPressIn: sends "a:r|s" (alarm request start)
  - If isAmIClientAllowedToDisconnectEdgeCase:
    - Also sends "a:r|ff" (force disconnect finish)
    - Starts 1500ms pingPongTimeout to force disconnect
  - onPressOut: sends "a:r|f" (alarm request finish)

Edge Case: Server Button vs Client Button Timing

When both the server and a client press their disconnect buttons simultaneously:

Server starts polling (500ms interval)
Client sends d:r|s
Server receives d:r|s, adds client to askedDisconnectionDevices
On next poll: askedDisconnectionDevices.length (1) === connectedClients.length (1) -> true
Server broadcasts d:a|a
Client receives d:a|a, sends d:r|1
Server receives d:r|1, but isDisconnectButtonPressed is still true and all clients have agreed
Server broadcasts d:a|a1
Both devices disconnect

This works correctly when the server has one client. With multiple clients, the server waits for ALL clients to agree before broadcasting d:a|a1. If one client refuses, the disconnect is stuck in limbo -- there is no timeout mechanism for the multi-device case.

6. The Alarm Trigger Paths

Every code path that leads to appState = "alarm":

#	Trigger	Who Fires	Code Location	Broadcast Packet
1	App backgrounded while synced	Server or Client	`bindListeners` AppState change (line 257-276)	Server: `a:f\|1\|u`, Client: `a:u\|i`
2	Android blur event while synced	Server or Client	`bindListeners` blur handler (line 279-300)	Server: `a:f\|1\|u`, Client: `a:u\|i`
3	Disconnect attempt with fireOnDisconnect=true	Server	`onDisconnectPressFinish` (line 1121-1130)	`a:f\|1\|a`
4	Client sends `d:r\|f` (release) and server has fireOnDisconnect	Server	`handlePacketFromClient` case `d`, `disconnectEventType === "f"` (line 1616-1623)	`a:f\|1\|a`
5	Client sends `d:r\|1` but was NOT in askedDisconnectionDevices	Server	`handlePacketFromClient` case `d`, `disconnectEventType === "1"` (line 1638-1649)	`a:f\|1\|a`
6	Server receives `a:u\|i` from client (backgrounding report)	Server	`handlePacketFromClient` case `a`, `alarmAction === "i"` (line 1700-1707)	`a:f\|1\|u`
7	Manual trigger via UI button	Client or Server	`onStopAlarmPressStart` (line 1227-1301)	Client: `a:r\|s`, Server: broadcasts when all agree
8	RSSI proximity (DESIGNED but COMMENTED OUT)	Server	`configureServerRSSITimeout` (line 1810-1851)	`a:f\|1`

The `fireAlarmOnDisconnect` Config

The StorageKeys.fireAlarmOnDisconnect flag is set via s:r|{0|1} packets. When a client connects (line 1340-1342):

const shouldFire = storage.getBoolean(StorageKeys.fireAlarmOnDisconnect) ?? false;
this.sendPacketToServer(`s:r|${shouldFire ? 1 : 0}`);

This tells the server whether this client wants the alarm to fire if any device disconnects. Once any client sends s:r|1, the server sets hasAnyoneRequestedToFireWhenDisconnect = true permanently (line 1554-1556). There is no way to unset this flag during the session -- it is an AND operation, not a toggle.

7. Feature Completeness Matrix

Feature	Designed	Implemented	Shipped	Notes
BLE mesh networking	Yes	Yes	Yes	Core feature, works cross-platform
Cross-platform (Android + iOS)	Yes	Yes	Yes	Android 6+ / iOS 13+
GATT server/client election	Yes	Yes	Yes	Higher advertised value wins
Connection migration	Yes	Yes	Yes	Server role handoff via `m:d\|{value}`
Manual disconnect with consent	Yes	Yes	Yes	5-sub-state protocol
Alarm on disconnect	Yes	Yes	Yes	Via manual/background triggers
Alarm sound sync	Yes	Yes	Yes	5 sounds, server-broadcast (`sound:1\|{id}`)
i18n	Yes	Yes	Yes	EN + DE
Onboarding	Yes	Yes	Yes	2-step flow
Privacy policy link	Yes	Yes	Yes	Options page
RSSI proximity alarm	Yes	Partial	No	Commented out in commit `2f701d2`
Sensitivity settings UI	Yes	Removed	No	Was in Options, now commented out
Sensitivity negotiation protocol	Yes	Partial	No	Server-side logic exists but is never invoked
`n:rssi\|1` activation broadcast	Yes	Partial	No	Code commented out
Automatic distance disconnect	Yes	Partial	No	Was in `configureServerRSSITimeout`, now commented
Sign-out button	Yes	Removed	No	Commented out in Options.tsx
Delete account button	Yes	Removed	No	Commented out in Options.tsx
Session replay analytics	Yes	Yes	Removed	Commit `be98dfc` removed it
NFC pairing	Yes	Partial	No	Commit `78e77f2` disabled it
iOS state restoration	Yes	Partial	Partial	Only restores connectedClients, not full state

The "Zombie Features"

Several features exist in a zombie state -- the storage keys are allocated, the handler logic exists in BleManager, but the UI that drives them has been removed or commented out:

rssiSense (StorageKeys.ts) -- initialized to 60, never written by user
fireAlarmOnDisconnect (StorageKeys.ts) -- initialized to false, but the server can set it from any client's s:r packet
hasAnyoneHigherSensibility (BleManager.ts) -- compared but never populated (the code that would populate it from client RSSI packets is commented out)
distanceAlarmFired (BleManager.ts) -- set to false on reset, never set to true
rssiUpdatesFromClients (BleManager.ts) -- cleared on every state transition, never populated

8. Lessons Learned

What Worked Well

The Skia rendering pipeline. Using @shopify/react-native-skia for the ball animations was the right call. The useDerivedValue chain that computes ball radius, position, and opacity from appState produces buttery 60fps animations without any frame drops. The ImageShader approach for the ball textures (red dot / black dot) is more performant than switching React components.

The custom BLE protocol. Building a custom GATT service with 4 characteristics (read, write, indicate, config) was the correct tradeoff. Standard BLE profiles (like GATT Battery Service or Heart Rate) do not support bidirectional packet exchange with multiple clients. The custom protocol allowed the server to broadcast to all clients and receive from any client without the overhead of standard GATT service discovery.

The server election algorithm. The number-based election (higher value = server) is simple, deterministic, and requires no coordination. iOS values are 1-124, Android values 126-249. This guarantees Android always wins when paired with iOS, avoiding the iOS-as-GATT-server limitations. The only edge case is two Android devices, where the first to start advertising wins.

The disconnect consent protocol. Despite its complexity, the protocol correctly implements mutual consent: both devices must agree to disconnect, and either can fire the alarm if the other tries to leave without agreement. The press-and-hold UI interaction prevents accidental disconnections.

The sound broadcast system. Broadcasting sound:1|{id} to all clients ensures all devices play the same sound at the same moment. The server-side playSound (line 247-249) only broadcasts non-alarm sounds, which is correct -- the alarm has its own broadcast path.

What Was Harder Than Expected

RSSI proximity was fundamentally flawed from the start. The decision to use BLE RSSI as a distance proxy was reasonable in theory but impractical in reality. RSSI is not calibrated, not normalized, and not comparable across devices. The 14-day lifespan (introduced Aug 20, disabled Sep 3) confirms that the problems were immediately apparent in real-world testing.

Cross-platform BLE state consistency. Keeping the JS-level state (SharedValues + React state) synchronized with the native BLE stack state (GATT server lifecycle, connection status, scan state) across three threads (UI, JS, native) proved to be the hardest engineering challenge. The useAnimatedReaction bridge pattern works but introduces latency that creates race conditions.

The disconnect protocol grew organically. The d:r|s -> d:a|a -> d:r|1 -> d:a|a1 flow was built incrementally, with each edge case adding a new packet type or flag. The discq/disca keepalive mechanism was added later (there is no discq in the original v2.33.0 commit). The isAmIClientAllowedToDisconnectEdgeCase flag was added even later to handle the server-backgrounding case. This organic growth produced a protocol that works but is difficult to reason about.

Sound loading on startup. Loading 5 audio files via Promise.all in the constructor (line 174) means the BleManager is not ready until all sounds are loaded. The isSoundsLoaded guard prevents crashes, but there is a window where the manager is constructed but not functional. This caused subtle bugs where the first sound played before loading completed.

What Would Be Done Differently

Backend for device tracking. The entire proximity system could have been replaced with a server-side solution. A lightweight server that tracks device locations (even approximately, via cell tower triangulation or WiFi BSSID) would have provided reliable distance estimation without the RSSI noise problem.

Standard BLE profiles for pairing. Using a standard BLE profile (like the Proximity Profile or Find Me Profile) would have provided RSSI reading and path loss estimation out of the box, with vendor-optimized implementations. The custom protocol was faster to build but lost access to these optimizations.

TypeScript strict mode from day one. The codebase has many implicit any types, particularly in the event handling ((event as any).value). Strict mode would have caught the type mismatches between the native event format and the TypeScript interfaces.

Separate the protocol layer from the manager. The BleManager class handles BLE lifecycle, protocol parsing, sound playback, haptic feedback, state management, and UI coordination in a single 1878-line file. Extracting the protocol layer (packet parsing, disconnect negotiation, alarm logic) into a separate class would make the system testable in isolation.

State machine library instead of ad-hoc flags. The disconnect protocol is a state machine but it is implemented as a collection of boolean flags (isDisconnectButtonPressed, serverAlreadyShouldDisconnect, hasAnyoneRequestedToFireWhenDisconnect, isAmIClientAllowedToDisconnectEdgeCase). A formal state machine (even a simple one) would make the transitions explicit and prevent invalid states.

What Surprised

The power of Skia for real-time UI. The ParagraphBuilder API that renders text inside the Skia canvas was surprisingly effective. Building paragraphs with inline font styles and dynamic content inside a canvas, at 60fps, without React re-renders, was the single best technical decision in the project.

The complexity of BLE state machines. What started as "two phones connect, one plays alarm" became a 1878-line state machine with 7 connection states, 12+ packet types, 5 disconnect sub-states, and a server election algorithm. BLE is not a simple protocol, and the cross-platform constraints multiply the complexity.

Android BLE quirks. The blur event being distinct from background, the GATT 133 error being random and unrecoverable, the need for legacyScan: true, the advertising name being set via bluetoothAdapter.setName() instead of the advertisement data -- none of these are documented in any BLE tutorial. They were all discovered through testing.

The 15ms RSSI polling rate was the minimum viable. Before disabling, the RSSI system attempted 66fps polling on the client and 30fps aggregation on the server. Even at this rate, the data was too noisy to be useful. The lesson: BLE RSSI is not a sensor. It is a signal strength indicator that happens to correlate (poorly) with distance.

Appendix A: Commit Archaeology

Key commits that shaped the current system:

Commit	Date	Significance
`749d1c8`	Aug 20, 2024	v2.33.0 -- Introduced proximity sensors, Options screen, fireAlarmOnDisconnect config
`2f701d2`	Sep 3, 2024	"Disable proximity sensors" -- Commented out all RSSI-based alarm and disconnect logic
`0e9ed31`	Before 2f701d2	"Final version - Animations, New Sounds, Alerts and better error handling"
`458183c`	After disable	"allow disconnection on special case when server closes the app" -- Added `isAmIClientAllowedToDisconnectEdgeCase`
`7b19e13`	After disable	"disable reconnection after alarm disconnect"
`964c74d`	After disable	"kill on alarm stop"
`78e77f2`	Later	"NFC Disable" -- Removed NFC pairing feature
`be98dfc`	Later	"remove session replay" -- Removed analytics
`82aefd5`	Later	"Alarm fixed on both devices" -- Major stability fix

Appendix B: The Commented-Out Code Map

Every commented-out section in the current BleManager.ts and what it was supposed to do:

Lines	Original Function	Status
1106-1113	`n:rssi\|1` broadcast + snackbar + ping sound (onDisconnectPressFinish)	Commented out
1198-1205	Same as above (onDisconnectLongPress)	Commented out
1268-1275	Same as above (onStopAlarmPressStart)	Commented out
1462-1469	"Proximity Sensors Enabled" snackbar on ping sound	Commented out
1481-1491	RSSI notification handler in n: packet type	Commented out
1577-1584	`n:rssi\|1` broadcast (handlePacketFromClient case s)	Commented out
1799-1803	`a:u	rssi\|{rssi}\|{sense}` packet send (configureClientRSSITimeout)
1804	Recursive `this.rssiTimeout = this.configureClientRSSITimeout()`	Commented out
1814-1835	Server-side RSSI aggregation and alarm firing	Commented out
1837-1846	Automatic disconnect after 1000ms of excessive RSSI	Commented out
1849	Recursive `this.rssiTimeout = this.configureServerRSSITimeout()`	Commented out
1869	RSSI timeout restart in `handleRssiUpdateFromClient`	Commented out

Total commented-out lines: ~80 lines of proximity system code, still present in the codebase but never executed.

CAMDOM -- System Design: Delivered vs Conceptual

1. Conceptual Architecture vs Delivered Product

What Was Designed (Full Vision)

What Was Actually Shipped

Why It Was Disabled

2. The Shared State Dilemma

The Two State Systems

The Bridge Problem

Race Conditions

3. GATT/BLE Device-Specific Issues

Android-Specific

iOS-Specific

Cross-Platform Inconsistencies

4. Error Handling & Recovery

What Is Handled

What Is NOT Handled

5. The Disconnect Protocol (State Machine)

Packet Types

Complete Flow: Normal Disconnect

Edge Case: Server Backgrounds During Sync

Edge Case: Server Button vs Client Button Timing

6. The Alarm Trigger Paths

The fireAlarmOnDisconnect Config

7. Feature Completeness Matrix

The "Zombie Features"

8. Lessons Learned

What Worked Well

What Was Harder Than Expected

What Would Be Done Differently

What Surprised

Appendix A: Commit Archaeology

Appendix B: The Commented-Out Code Map

The `fireAlarmOnDisconnect` Config