Proximity Sensor Service

The Proximity Sensor Service is a real-time physical–digital bridge that ingests radio proximity signals (Wi-Fi, Wi-Fi Direct, BLE) from nearby devices and resolves nearby vendors and inventories using SSID / identifier matching.

It enables hyperlocal discovery, foot-traffic monetization, and ambient commerce without user interaction.

1. Scope & Responsibilities

What this service does

| Area | Responsibility | | -------------------- | -------------------------------------------- | | Signal ingestion | Receive Wi-Fi / Wi-Fi P2P / BLE scan data | | Persistence | Store scan events for analytics & replay | | Proximity resolution | Match detected identifiers to vendors | | Caching | Maintain fast, short-lived proximity state | | Web relay | Serve nearby vendor inventory to web clients |

What this service does NOT do

| Excluded | Reason | | ------------------ | ------------------------------------ | | Vendor CRUD | Handled by Vendor service | | Inventory mutation | Read-only from proximity perspective | | Authentication | Sensors are assumed trusted | | Payments | Out of scope |

2. Supported Proximity Technologies

| Technology | Status | Purpose | Matching Key | | ---------------------- | ------------- | ------------------------ | ---------------- | | Wi-Fi | ✅ Implemented | Primary proximity signal | SSID | | Wi-Fi Direct (P2P) | ✅ Implemented | Peer discovery, mesh | SSID / Device ID | | BLE | 🟡 Planned | Ultra-low power beacons | UUID / MAC |

3. High-Level Architecture

| Component | Role | | ----------------------- | --------------------------- | | Native proximity device | Scans radio environment | | Socket server | Real-time ingestion | | DeviceScan store | Historical scan persistence | | Vendor store | Known physical endpoints | | Proximity cache | Low-latency resolution | | Web socket namespace | Frontend notifications |

4. Socket Namespaces

Namespace Overview

| Namespace | Client Type | Purpose | | ------------------- | ------------------ | -------------------------------- | | /proximity/native | IoT / Edge devices | Send scan results | | /proximity/web | Browser clients | Trigger & receive proximity data |

5. Socket Event Matrix

Server → Device

| Event | Frequency | Description | | ---------------- | --------- | ----------------------- | | start_scanning | Every 4s | Requests new scan cycle |

Device → Server (Wi-Fi)

| Event | Payload | Description | | ------------------- | ------------------ | ------------------- | | wifi::scan_result | Wi-Fi scan payload | Standard Wi-Fi scan |

Device → Server (Wi-Fi P2P)

| Event | Payload | Description | | ---------------------- | ---------------- | --------------------- | | wifip2p::scan_result | P2P scan payload | Mesh / peer discovery |

Web Client Events

| Event | Direction | Description | | -------------------------- | ------------ | ------------------------ | | PROXIMITY_SCAN::RUN_SCAN | Web → Server | Trigger proximity lookup | | PROXIMITY_SCAN | Server → Web | Return nearby vendors |

6. REST API Surface

Endpoint Summary

| Method | Endpoint | Purpose | | ------ | -------------------------- | ---------------------- | | GET | /api/proximity/inventory | Resolve nearby vendors |

Identification Headers

| Header | Optional | Purpose | | -------------- | -------- | --------------------------- | | x-device-sig | Yes | Persistent device signature | | public_ip | Yes | Network-level identity | | x-ws-token | Yes | WebSocket fallback |

The service automatically selects the best available key.

7. Proximity Resolution Flow

| Step | Action | | ---- | ------------------------------ | | 1 | Device performs scan | | 2 | Scan results sent via socket | | 3 | Scan persisted to database | | 4 | SSIDs / identifiers extracted | | 5 | Vendors matched by identifiers | | 6 | Result cached | | 7 | Web client requests inventory | | 8 | Cached vendors returned |

8. Data Models

8.1 Wi-Fi / Wi-Fi P2P Scan Payload

| Field | Type | Required | Description | | ----------------- | ---------- | -------- | -------------------- | | device_id | string | No | Device identifier | | deviceSignature | string | No | Persistent signature | | public_ip | string | No | Network IP | | timestamp | ISO string | Yes | Scan time | | scan_meta | object | No | Scan metadata | | detected_wifi | array | Yes | Detected networks |

8.2 Detected Network

| Field | Type | Description | | ----------- | ------ | ----------------- | | ssid | string | Network name | | rssi | number | Signal strength | | frequency | number | Channel frequency |

8.3 BLE Scan Payload (Planned)

| Field | Type | Description | | ----------- | ------ | -------------------- | | device_id | string | BLE scanner | | beacons | array | Detected BLE beacons | | uuid | string | Beacon UUID | | major | number | Beacon major | | minor | number | Beacon minor | | rssi | number | Signal strength |

9. Proximity Cache Structure

| Key | Description | | -------------- | ------------------------- | | ssids | Last detected identifiers | | timestamp | Last scan time | | socketId | Active connection | | persistentId | Device identity |

10. Vendor Matching Logic

| Signal Type | Matching Strategy | | ----------- | -------------------------------------- | | Wi-Fi | SSID ∈ Vendor.SSID | | Wi-Fi P2P | SSID ∈ Vendor.SSID | | BLE | UUID ↔ Vendor beacon mapping (planned) |

11. Error Handling Matrix

| Scenario | Response | | ----------------- | ------------------ | | Invalid payload | Error ACK | | Empty scan | stores_count = 0 | | No vendor match | Valid empty result | | DB failure | Error + logged | | Socket disconnect | Scan loop stopped |

12. Security Model

| Aspect | Current State | | ----------------- | --------------- | | Authentication | None | | Authorization | None | | Trust model | Device-based | | Replay protection | Timestamp-based | | Rate limiting | Not implemented |

Designed for trusted edge devices. Hardenable later.

13. Local Development

Requirements

| Dependency | Version | | ---------- | ------- | | Node.js | ≥ 18 | | MongoDB | ≥ 5 | | Socket.IO | v4 |

Run Locally

npm install
npm run dev

14. Future Enhancements

| Feature | Status | | ------------------------ | ------- | | BLE beacon ingestion | Planned | | Movement delta detection | Planned | | Confidence scoring | Planned | | Multi-sensor fusion | Planned | | Edge mesh propagation | Planned |

15. Related Docs

| Document | Purpose | | -------------- | ----------------------------- | | openapi.yaml | REST API spec | | Vendor API | Vendor & inventory management | | QA Matrix | Test coverage | | SRS | Functional requirements |

16. Ownership

Proximity Platform – Sensor Layer Built for ambient, real-world intelligence.