npm package: @shyntech-proximity/sensor-app
Description: 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.
Latest version: 1.0.6

# 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

```bash
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**.