@shyntech-proximity/sensor-app 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/QA.md +195 -0
- package/docs/SRS.md +498 -0
- package/docs/openapi.yaml +226 -0
- package/package.json +6 -2
package/docs/QA.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# Proximity Sensor/Scanner – QA Matrix (Per Signal Type)
|
|
2
|
+
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
## 1. Wi-Fi Proximity QA Matrix
|
|
6
|
+
|
|
7
|
+
### 1.1 Connection & Scan Trigger
|
|
8
|
+
|
|
9
|
+
| Test ID | Scenario | Preconditions | Action | Expected Result |
|
|
10
|
+
| ------- | ------------------------ | ------------------------ | ------------------------------ | ------------------------ |
|
|
11
|
+
| WIFI-01 | Native device connects | Socket server running | Connect to `/proximity/native` | Connection accepted |
|
|
12
|
+
| WIFI-02 | Scan trigger emitted | Device connected | Wait 4s | `start_scanning` emitted |
|
|
13
|
+
| WIFI-03 | Continuous scanning | Device remains connected | Observe 3 cycles | Event emitted every 4s |
|
|
14
|
+
| WIFI-04 | Scan stops on disconnect | Device disconnects | Observe | Scan interval cleared |
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
### 1.2 Wi-Fi Scan Payload Validation
|
|
19
|
+
|
|
20
|
+
| Test ID | Scenario | Input | Expected Result |
|
|
21
|
+
| ------- | ----------------------- | ------------------------- | -------------------------- |
|
|
22
|
+
| WIFI-05 | Valid scan payload | Valid `wifi::scan_result` | ACK `{ status: "ok" }` |
|
|
23
|
+
| WIFI-06 | Missing `detected_wifi` | Payload without array | Handled gracefully |
|
|
24
|
+
| WIFI-07 | Empty Wi-Fi list | `detected_wifi: []` | ACK with `stores_count: 0` |
|
|
25
|
+
| WIFI-08 | Missing timestamp | No timestamp | Scan still stored |
|
|
26
|
+
| WIFI-09 | Invalid payload format | Malformed object | ACK `{ status: "error" }` |
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
### 1.3 Vendor Matching (Wi-Fi)
|
|
31
|
+
|
|
32
|
+
| Test ID | Scenario | Preconditions | Expected Result |
|
|
33
|
+
| ------- | -------------------- | ------------------ | ------------------------- |
|
|
34
|
+
| WIFI-10 | SSID matches vendor | Vendor SSID exists | Vendor returned |
|
|
35
|
+
| WIFI-11 | Multiple SSIDs match | Multiple vendors | All vendors returned |
|
|
36
|
+
| WIFI-12 | No SSID match | Unknown SSIDs | Empty result |
|
|
37
|
+
| WIFI-13 | Duplicate SSIDs | Repeated SSIDs | No duplication |
|
|
38
|
+
| WIFI-14 | Case mismatch SSID | Different casing | Match behavior consistent |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
### 1.4 Persistence
|
|
43
|
+
|
|
44
|
+
| Test ID | Scenario | Expected Result |
|
|
45
|
+
| ------- | ------------------- | ----------------------------- |
|
|
46
|
+
| WIFI-15 | Scan persisted | `DeviceScan` document created |
|
|
47
|
+
| WIFI-16 | Public IP stored | `public_ip` saved |
|
|
48
|
+
| WIFI-17 | Device ID stored | `device_id` saved |
|
|
49
|
+
| WIFI-18 | Scan metadata saved | `scan_meta` saved |
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 2. Wi-Fi P2P (Wi-Fi Direct) QA Matrix
|
|
56
|
+
|
|
57
|
+
### 2.1 Event Handling
|
|
58
|
+
|
|
59
|
+
| Test ID | Scenario | Action | Expected Result |
|
|
60
|
+
| ------- | ---------------- | --------------------------- | ---------------------- |
|
|
61
|
+
| P2P-01 | Receive P2P scan | Emit `wifip2p::scan_result` | Event handled |
|
|
62
|
+
| P2P-02 | ACK response | Valid payload | ACK `{ status: "ok" }` |
|
|
63
|
+
| P2P-03 | Missing payload | Empty payload | Error handled |
|
|
64
|
+
| P2P-04 | Scan logging | Payload sent | Logged correctly |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
### 2.2 P2P Scan Payload
|
|
69
|
+
|
|
70
|
+
| Test ID | Scenario | Input | Expected Result |
|
|
71
|
+
| ------- | ------------------- | ------------------- | ------------------- |
|
|
72
|
+
| P2P-05 | Valid P2P scan | Proper payload | Stored successfully |
|
|
73
|
+
| P2P-06 | Missing `device_id` | No ID | Uses fallback |
|
|
74
|
+
| P2P-07 | Missing SSIDs | Empty detected_wifi | Zero matches |
|
|
75
|
+
| P2P-08 | Invalid SSID | Null / undefined | Filtered out |
|
|
76
|
+
| P2P-09 | Timestamp missing | No timestamp | Defaults accepted |
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
### 2.3 Proximity Cache
|
|
81
|
+
|
|
82
|
+
| Test ID | Scenario | Expected Result |
|
|
83
|
+
| ------- | -------------------- | -------------------------------- |
|
|
84
|
+
| P2P-10 | Cache entry created | Entry exists in `proximityCache` |
|
|
85
|
+
| P2P-11 | Cache keyed by IP | Uses `public_ip` |
|
|
86
|
+
| P2P-12 | Cache fallback key | Uses `deviceSignature` |
|
|
87
|
+
| P2P-13 | Cache timestamp | Timestamp updated |
|
|
88
|
+
| P2P-14 | Cache socket binding | Correct `socketId` stored |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
### 2.4 Vendor Resolution
|
|
93
|
+
|
|
94
|
+
| Test ID | Scenario | Expected Result |
|
|
95
|
+
| ------- | --------------------- | -------------------- |
|
|
96
|
+
| P2P-15 | SSID matches vendor | Vendor returned |
|
|
97
|
+
| P2P-16 | Multiple vendor match | All vendors returned |
|
|
98
|
+
| P2P-17 | No vendor match | Empty response |
|
|
99
|
+
| P2P-18 | Duplicate SSIDs | No duplicate vendors |
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 3. BLE Proximity QA Matrix (Planned)
|
|
106
|
+
|
|
107
|
+
> These tests define **acceptance criteria** for BLE implementation.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
### 3.1 BLE Scan Ingestion
|
|
112
|
+
|
|
113
|
+
| Test ID | Scenario | Input | Expected Result |
|
|
114
|
+
| ------- | -------------------- | ------------------ | ------------------- |
|
|
115
|
+
| BLE-01 | BLE scan event | `ble::scan_result` | Event accepted |
|
|
116
|
+
| BLE-02 | Valid beacon payload | UUID present | Stored successfully |
|
|
117
|
+
| BLE-03 | Missing UUID | No UUID | Scan rejected |
|
|
118
|
+
| BLE-04 | Empty beacon list | No beacons | Zero matches |
|
|
119
|
+
| BLE-05 | Invalid RSSI | Out of range | Handled gracefully |
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
### 3.2 BLE Vendor Matching
|
|
124
|
+
|
|
125
|
+
| Test ID | Scenario | Preconditions | Expected Result |
|
|
126
|
+
| ------- | ------------------- | -------------------- | -------------------- |
|
|
127
|
+
| BLE-06 | UUID matches vendor | Vendor beacon mapped | Vendor returned |
|
|
128
|
+
| BLE-07 | Major/minor match | Defined mapping | Vendor resolved |
|
|
129
|
+
| BLE-08 | No mapping | Unknown beacon | Empty result |
|
|
130
|
+
| BLE-09 | Multiple beacons | Multiple vendors | All vendors returned |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
### 3.3 BLE Proximity Accuracy
|
|
135
|
+
|
|
136
|
+
| Test ID | Scenario | Expected Result |
|
|
137
|
+
| ------- | ----------------- | --------------- |
|
|
138
|
+
| BLE-10 | Strong signal | High confidence |
|
|
139
|
+
| BLE-11 | Weak signal | Low confidence |
|
|
140
|
+
| BLE-12 | Fluctuating RSSI | Smoothed result |
|
|
141
|
+
| BLE-13 | Beacon disappears | Vendor removed |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 4. Web Client QA Matrix
|
|
148
|
+
|
|
149
|
+
### 4.1 Web Trigger Flow
|
|
150
|
+
|
|
151
|
+
| Test ID | Scenario | Action | Expected Result |
|
|
152
|
+
| ------- | ----------------- | ------------------------------- | ------------------------ |
|
|
153
|
+
| WEB-01 | Web connects | Connect to `/proximity/web` | Connected |
|
|
154
|
+
| WEB-02 | Trigger scan | Emit `PROXIMITY_SCAN::RUN_SCAN` | Request sent |
|
|
155
|
+
| WEB-03 | Vendors found | Data exists | `PROXIMITY_SCAN` emitted |
|
|
156
|
+
| WEB-04 | No vendors | Empty result | No crash |
|
|
157
|
+
| WEB-05 | Missing device ID | No persistentId | Fallback works |
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## 5. Failure & Resilience QA Matrix
|
|
164
|
+
|
|
165
|
+
| Test ID | Scenario | Expected Result |
|
|
166
|
+
| ------- | -------------------------- | --------------- |
|
|
167
|
+
| ERR-01 | MongoDB down | Error logged |
|
|
168
|
+
| ERR-02 | Vendor query fails | ACK error |
|
|
169
|
+
| ERR-03 | Socket disconnect mid-scan | Scan loop stops |
|
|
170
|
+
| ERR-04 | High scan frequency | No memory leak |
|
|
171
|
+
| ERR-05 | Duplicate scan events | No corruption |
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## 6. Performance & Load (Cross-Signal)
|
|
176
|
+
|
|
177
|
+
| Test ID | Scenario | Expected Result |
|
|
178
|
+
| ------- | -------------------- | ------------------- |
|
|
179
|
+
| PERF-01 | 100 devices scanning | Stable |
|
|
180
|
+
| PERF-02 | 1k SSIDs per scan | Processed |
|
|
181
|
+
| PERF-03 | Rapid reconnects | No orphan intervals |
|
|
182
|
+
| PERF-04 | Cache growth | Eviction needed |
|
|
183
|
+
| PERF-05 | Long uptime | No memory leak |
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## 7. Traceability Matrix
|
|
188
|
+
|
|
189
|
+
| Feature | Wi-Fi | P2P | BLE |
|
|
190
|
+
| --------------- | ----- | --- | --- |
|
|
191
|
+
| Scan ingestion | ✅ | ✅ | 🟡 |
|
|
192
|
+
| Vendor matching | ✅ | ✅ | 🟡 |
|
|
193
|
+
| Persistence | ✅ | ✅ | 🟡 |
|
|
194
|
+
| Cache | ❌ | ✅ | 🟡 |
|
|
195
|
+
| Web relay | ✅ | ✅ | 🟡 |
|
package/docs/SRS.md
ADDED
|
@@ -0,0 +1,498 @@
|
|
|
1
|
+
# 📘 Software Requirements Specification (SRS)
|
|
2
|
+
|
|
3
|
+
## Proximity Sensor & Signal Ingestion Service
|
|
4
|
+
|
|
5
|
+
**Product:** Proximity
|
|
6
|
+
**Audience:** Stakeholders, Product, Backend Engineers
|
|
7
|
+
**Signals Covered:** Wi-Fi, Wi-Fi P2P, BLE
|
|
8
|
+
**Transport:** Socket.IO (Real-time) + REST (Read-only inventory)
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. Introduction
|
|
13
|
+
|
|
14
|
+
### 1.1 Purpose
|
|
15
|
+
|
|
16
|
+
This document specifies the functional and non-functional requirements for the **Proximity Sensor subsystem**, responsible for ingesting, processing, and correlating **nearby device signals** (Wi-Fi, Wi-Fi Direct / P2P, and BLE) with **registered identities** in real time.
|
|
17
|
+
|
|
18
|
+
It serves as:
|
|
19
|
+
|
|
20
|
+
* A **shared understanding** for stakeholders
|
|
21
|
+
* A **build reference** for backend engineers
|
|
22
|
+
* A **validation baseline** for QA and integration teams
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
### 1.2 Scope
|
|
27
|
+
|
|
28
|
+
The Proximity Sensor subsystem enables:
|
|
29
|
+
|
|
30
|
+
* Continuous signal scanning by edge devices
|
|
31
|
+
* Real-time ingestion of scan results
|
|
32
|
+
* Matching detected signals to registered identities
|
|
33
|
+
* Caching of proximity context for fast lookups
|
|
34
|
+
* Streaming results to web clients on demand
|
|
35
|
+
|
|
36
|
+
Out of scope:
|
|
37
|
+
|
|
38
|
+
* UI/UX rendering
|
|
39
|
+
* Identity onboarding flows
|
|
40
|
+
* Payments, offers, or campaign logic
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
### 1.3 Stakeholders
|
|
45
|
+
|
|
46
|
+
| Role | Responsibility |
|
|
47
|
+
| --------------------- | -------------------------------------- |
|
|
48
|
+
| Product Owners | Define proximity use cases |
|
|
49
|
+
| Identitys | Register identifiable signals |
|
|
50
|
+
| Backend Engineers | Implement ingestion, storage, matching |
|
|
51
|
+
| Mobile / Edge Devices | Perform scans |
|
|
52
|
+
| Web Clients | Request and consume proximity results |
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 2. System Overview
|
|
57
|
+
|
|
58
|
+
### 2.1 High-Level Flow
|
|
59
|
+
|
|
60
|
+
1. **Edge device connects** to `/proximity/native`
|
|
61
|
+
2. Server emits `start_scanning` periodically
|
|
62
|
+
3. Device returns scan results (Wi-Fi / P2P / BLE)
|
|
63
|
+
4. Backend:
|
|
64
|
+
|
|
65
|
+
* Persists scan data
|
|
66
|
+
* Matches signals against identities
|
|
67
|
+
* Caches proximity state
|
|
68
|
+
5. **Web client requests scan** via `/proximity/web`
|
|
69
|
+
6. Server responds with matched identity inventory
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
### 2.2 Supported Signal Types
|
|
74
|
+
|
|
75
|
+
| Signal | Purpose | Typical Range | Primary Use |
|
|
76
|
+
| --------- | -------------------------- | ------------- | ---------------------- |
|
|
77
|
+
| Wi-Fi | SSID-based discovery | Medium–Long | Venue identification |
|
|
78
|
+
| Wi-Fi P2P | Device-to-device proximity | Short–Medium | Dense local presence |
|
|
79
|
+
| BLE | Beacon-level accuracy | Short | Fine-grained proximity |
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 3. Functional Requirements
|
|
84
|
+
|
|
85
|
+
### 3.1 Device Connection & Identity
|
|
86
|
+
|
|
87
|
+
| ID | Requirement |
|
|
88
|
+
| ---- | ----------------------------------------------------------------------------------------- |
|
|
89
|
+
| FR-1 | System SHALL accept socket connections from native devices |
|
|
90
|
+
| FR-2 | Device identity SHALL be resolved using `public_ip`, `deviceSignature`, or `persistentId` |
|
|
91
|
+
| FR-3 | Identity resolution SHALL be deterministic per session |
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
### 3.2 Scan Orchestration
|
|
96
|
+
|
|
97
|
+
| ID | Requirement |
|
|
98
|
+
| ---- | -------------------------------------------------------------- |
|
|
99
|
+
| FR-4 | Server SHALL periodically request scans from connected devices |
|
|
100
|
+
| FR-5 | Scan interval SHALL be configurable (default: 4 seconds) |
|
|
101
|
+
| FR-6 | Multiple signal types MAY be reported in parallel |
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
### 3.3 Signal Ingestion (All Signal Types)
|
|
106
|
+
|
|
107
|
+
| ID | Requirement |
|
|
108
|
+
| ----- | ----------------------------------------------------- |
|
|
109
|
+
| FR-7 | System SHALL accept scan results via socket events |
|
|
110
|
+
| FR-8 | Each scan payload SHALL include timestamp metadata |
|
|
111
|
+
| FR-9 | Invalid or partial payloads SHALL NOT crash ingestion |
|
|
112
|
+
| FR-10 | Each scan SHALL be persisted for analytics and replay |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
### 3.4 Wi-Fi Signal Handling
|
|
117
|
+
|
|
118
|
+
| ID | Requirement |
|
|
119
|
+
| ----- | ---------------------------------------------- |
|
|
120
|
+
| FR-11 | Wi-Fi scans SHALL include detected SSIDs |
|
|
121
|
+
| FR-12 | System SHALL extract SSIDs for identity matching |
|
|
122
|
+
| FR-13 | Hidden or null SSIDs SHALL be ignored |
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
### 3.5 Wi-Fi P2P Signal Handling
|
|
127
|
+
|
|
128
|
+
| ID | Requirement |
|
|
129
|
+
| ----- | ------------------------------------------------------ |
|
|
130
|
+
| FR-14 | System SHALL ingest Wi-Fi P2P scan results |
|
|
131
|
+
| FR-15 | Wi-Fi P2P results SHALL be cached per device |
|
|
132
|
+
| FR-16 | Cached data SHALL include socket and timestamp context |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
### 3.6 BLE Signal Handling
|
|
137
|
+
|
|
138
|
+
| ID | Requirement |
|
|
139
|
+
| ----- | --------------------------------------------------- |
|
|
140
|
+
| FR-17 | System SHALL ingest BLE scan results |
|
|
141
|
+
| FR-18 | BLE identifiers MAY include UUID, MAC, or beacon ID |
|
|
142
|
+
| FR-19 | BLE results SHALL be normalized for identity lookup |
|
|
143
|
+
|
|
144
|
+
> **Note:** BLE ingestion is required even if identity matching is deferred to later versions.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
### 3.7 Identity Matching
|
|
149
|
+
|
|
150
|
+
| ID | Requirement |
|
|
151
|
+
| ----- | --------------------------------------------------------- |
|
|
152
|
+
| FR-20 | System SHALL match detected signals to registered identities |
|
|
153
|
+
| FR-21 | Matching SHALL be based on registered SSIDs / identifiers |
|
|
154
|
+
| FR-22 | Multiple identities MAY match a single scan |
|
|
155
|
+
| FR-23 | Matching SHALL NOT mutate identity data |
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
### 3.8 Web Client Interaction
|
|
160
|
+
|
|
161
|
+
| ID | Requirement |
|
|
162
|
+
| ----- | ------------------------------------------------ |
|
|
163
|
+
| FR-24 | Web clients SHALL trigger scans on demand |
|
|
164
|
+
| FR-25 | Results SHALL be streamed back via socket events |
|
|
165
|
+
| FR-26 | Empty results SHALL be handled gracefully |
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
### 3.9 Acknowledgements & Error Handling
|
|
170
|
+
|
|
171
|
+
| ID | Requirement |
|
|
172
|
+
| ----- | --------------------------------------------- |
|
|
173
|
+
| FR-27 | Each scan event SHALL support ACK responses |
|
|
174
|
+
| FR-28 | Errors SHALL return structured error payloads |
|
|
175
|
+
| FR-29 | Failures SHALL be logged with context |
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## 4. Data Requirements
|
|
180
|
+
|
|
181
|
+
### 4.1 DeviceScan Entity
|
|
182
|
+
|
|
183
|
+
| Field | Type | Description |
|
|
184
|
+
| ------------- | ------ | -------------------------- |
|
|
185
|
+
| device_id | String | Hardware or OS identifier |
|
|
186
|
+
| public_ip | String | Optional network identity |
|
|
187
|
+
| detected_wifi | Array | List of detected signals |
|
|
188
|
+
| timestamp | Date | Scan time |
|
|
189
|
+
| scan_meta | Object | RSSI, channel, signal type |
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
### 4.2 Identity Entity (Relevant Fields)
|
|
194
|
+
|
|
195
|
+
| Field | Type | Description |
|
|
196
|
+
| --------- | ------ | ------------------------------------ |
|
|
197
|
+
| ssid | String | Registered Wi-Fi / beacon identifier |
|
|
198
|
+
| identity_id | String | Unique identity identity |
|
|
199
|
+
| metadata | Object | Optional descriptive info |
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 5. Non-Functional Requirements
|
|
204
|
+
|
|
205
|
+
### 5.1 Performance
|
|
206
|
+
|
|
207
|
+
| Requirement |
|
|
208
|
+
| ---------------------------------- |
|
|
209
|
+
| Ingestion latency < 200ms per scan |
|
|
210
|
+
| Supports 1,000+ concurrent devices |
|
|
211
|
+
| Web scan response < 500ms |
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
### 5.2 Reliability
|
|
216
|
+
|
|
217
|
+
| Requirement |
|
|
218
|
+
| ----------------------------------------- |
|
|
219
|
+
| Device disconnect SHALL not corrupt cache |
|
|
220
|
+
| Partial scans SHALL still be persisted |
|
|
221
|
+
| Cache eviction SHALL be time-based |
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
### 5.3 Scalability
|
|
226
|
+
|
|
227
|
+
| Requirement |
|
|
228
|
+
| --------------------------------------- |
|
|
229
|
+
| Horizontal scaling of socket namespaces |
|
|
230
|
+
| Stateless web clients |
|
|
231
|
+
| Cache layer replaceable (Redis-ready) |
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
### 5.4 Security
|
|
236
|
+
|
|
237
|
+
| Requirement |
|
|
238
|
+
| ---------------------------------------------- |
|
|
239
|
+
| Device signatures SHALL NOT be trusted blindly |
|
|
240
|
+
| No raw PII exposed to web clients |
|
|
241
|
+
| Signal data SHALL be read-only for clients |
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## 6. Assumptions & Constraints
|
|
246
|
+
|
|
247
|
+
| Item | Description |
|
|
248
|
+
| ---------- | ----------------------------------- |
|
|
249
|
+
| Assumption | Edge devices can perform scans |
|
|
250
|
+
| Assumption | Identitys register stable identifiers |
|
|
251
|
+
| Constraint | Real-time over best-effort networks |
|
|
252
|
+
| Constraint | Mobile OS scanning limitations |
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 7. Future Enhancements (Non-Blocking)
|
|
257
|
+
|
|
258
|
+
| Feature |
|
|
259
|
+
| --------------------------- |
|
|
260
|
+
| Signal confidence scoring |
|
|
261
|
+
| BLE triangulation |
|
|
262
|
+
| Identity density analytics |
|
|
263
|
+
| Fraud / spoofing detection |
|
|
264
|
+
| Historical proximity replay |
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## 8. Success Metrics
|
|
269
|
+
|
|
270
|
+
| Metric | Target |
|
|
271
|
+
| ---------------------------- | ------- |
|
|
272
|
+
| Scan success rate | > 98% |
|
|
273
|
+
| Identity match accuracy | > 95% |
|
|
274
|
+
| Average response latency | < 500ms |
|
|
275
|
+
| Device reconnection recovery | < 2s |
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
### ✅ Summary for Stakeholders
|
|
280
|
+
|
|
281
|
+
* This system **turns physical presence into digital context**
|
|
282
|
+
* It works **in real time**
|
|
283
|
+
* It is **signal-agnostic** (Wi-Fi, P2P, BLE)
|
|
284
|
+
* It is **scalable, secure, and extensible**
|
|
285
|
+
|
|
286
|
+
### 🛠️ Summary for Backend Engineers
|
|
287
|
+
|
|
288
|
+
* Socket-driven ingestion
|
|
289
|
+
* Stateless matching
|
|
290
|
+
* Cache-backed proximity context
|
|
291
|
+
* Clear extension points for BLE, scoring, analytics
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
# 🔄 Proximity Sensor – Sequence Diagrams
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## 1️⃣ Native Device Connection & Scan Orchestration
|
|
305
|
+
|
|
306
|
+
**(Wi-Fi / Wi-Fi P2P / BLE – shared control flow)**
|
|
307
|
+
|
|
308
|
+
```mermaid
|
|
309
|
+
sequenceDiagram
|
|
310
|
+
participant Device as Native Proximity Device
|
|
311
|
+
participant Socket as Socket.IO Server
|
|
312
|
+
participant Cache as Proximity Cache
|
|
313
|
+
|
|
314
|
+
Device->>Socket: Connect (/proximity/native)
|
|
315
|
+
Socket->>Socket: Resolve persistentId
|
|
316
|
+
Socket-->>Device: Connection ACK
|
|
317
|
+
|
|
318
|
+
loop Every 4 seconds
|
|
319
|
+
Socket-->>Device: start_scanning
|
|
320
|
+
end
|
|
321
|
+
|
|
322
|
+
Device->>Socket: disconnect
|
|
323
|
+
Socket->>Socket: Clear scan interval
|
|
324
|
+
Socket->>Cache: Evict device context
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
📌 **Key Points**
|
|
328
|
+
|
|
329
|
+
* Server is the **scan orchestrator**
|
|
330
|
+
* Device identity is resolved **once per session**
|
|
331
|
+
* Signal type does **not** affect orchestration
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## 2️⃣ Wi-Fi Scan Ingestion & Vendor Matching
|
|
336
|
+
|
|
337
|
+
```mermaid
|
|
338
|
+
sequenceDiagram
|
|
339
|
+
participant Device as Native Device
|
|
340
|
+
participant Socket as Proximity Server
|
|
341
|
+
participant DB as Database
|
|
342
|
+
participant Vendor as Vendor Store
|
|
343
|
+
|
|
344
|
+
Device->>Socket: wifi::scan_result(payload)
|
|
345
|
+
Socket->>Socket: Validate payload
|
|
346
|
+
Socket->>DB: Save DeviceScan
|
|
347
|
+
Socket->>Vendor: Find vendors by SSID
|
|
348
|
+
Vendor-->>Socket: Matching vendors
|
|
349
|
+
Socket-->>Device: ACK {status, stores_count}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
📌 **Key Points**
|
|
353
|
+
|
|
354
|
+
* SSID list is the **matching key**
|
|
355
|
+
* Multiple vendors may match
|
|
356
|
+
* Scan is persisted **before** matching response
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## 3️⃣ Wi-Fi P2P Scan Ingestion with Proximity Caching
|
|
361
|
+
|
|
362
|
+
```mermaid
|
|
363
|
+
sequenceDiagram
|
|
364
|
+
participant Device as Native Device
|
|
365
|
+
participant Socket as Proximity Server
|
|
366
|
+
participant DB as Database
|
|
367
|
+
participant Vendor as Vendor Store
|
|
368
|
+
participant Cache as Proximity Cache
|
|
369
|
+
|
|
370
|
+
Device->>Socket: wifip2p::scan_result(payload)
|
|
371
|
+
Socket->>Socket: Resolve device key
|
|
372
|
+
Socket->>DB: Save DeviceScan
|
|
373
|
+
Socket->>Vendor: Find vendors by SSID
|
|
374
|
+
Vendor-->>Socket: Matching vendors
|
|
375
|
+
Socket->>Cache: Store proximity context
|
|
376
|
+
Socket-->>Device: ACK {status, stores_count}
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
📌 **Key Points**
|
|
380
|
+
|
|
381
|
+
* Adds **stateful caching**
|
|
382
|
+
* Enables fast follow-up lookups
|
|
383
|
+
* Cache key = `public_ip | deviceSignature | persistentId`
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## 4️⃣ BLE Scan Ingestion (Vendor Matching Optional)
|
|
388
|
+
|
|
389
|
+
```mermaid
|
|
390
|
+
sequenceDiagram
|
|
391
|
+
participant Device as Native Device
|
|
392
|
+
participant Socket as Proximity Server
|
|
393
|
+
participant DB as Database
|
|
394
|
+
participant Vendor as Vendor Store
|
|
395
|
+
|
|
396
|
+
Device->>Socket: ble::scan_result(payload)
|
|
397
|
+
Socket->>Socket: Normalize BLE identifiers
|
|
398
|
+
Socket->>DB: Save DeviceScan
|
|
399
|
+
|
|
400
|
+
alt Vendor BLE matching enabled
|
|
401
|
+
Socket->>Vendor: Match BLE identifiers
|
|
402
|
+
Vendor-->>Socket: Matching vendors
|
|
403
|
+
end
|
|
404
|
+
|
|
405
|
+
Socket-->>Device: ACK {status, stores_count}
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
📌 **Key Points**
|
|
409
|
+
|
|
410
|
+
* BLE ingestion is **mandatory**
|
|
411
|
+
* Vendor matching is **feature-flag ready**
|
|
412
|
+
* Precision > range (short-distance signal)
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## 5️⃣ Web Client Triggered Proximity Scan
|
|
417
|
+
|
|
418
|
+
```mermaid
|
|
419
|
+
sequenceDiagram
|
|
420
|
+
participant Web as Web Client
|
|
421
|
+
participant Socket as Web Namespace
|
|
422
|
+
participant API as Proximity REST API
|
|
423
|
+
participant DB as Database
|
|
424
|
+
|
|
425
|
+
Web->>Socket: PROXIMITY_SCAN::RUN_SCAN
|
|
426
|
+
Socket->>API: GET /api/proximity/inventory
|
|
427
|
+
API->>DB: Query recent proximity scans
|
|
428
|
+
DB-->>API: Scan results
|
|
429
|
+
API-->>Socket: Inventory response
|
|
430
|
+
Socket-->>Web: PROXIMITY_SCAN {data}
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
📌 **Key Points**
|
|
434
|
+
|
|
435
|
+
* Web clients are **read-only**
|
|
436
|
+
* No direct access to native sockets
|
|
437
|
+
* REST used for **aggregation + filtering**
|
|
438
|
+
|
|
439
|
+
---
|
|
440
|
+
|
|
441
|
+
## 6️⃣ Error Handling & ACK Flow (All Signal Types)
|
|
442
|
+
|
|
443
|
+
```mermaid
|
|
444
|
+
sequenceDiagram
|
|
445
|
+
participant Device as Native Device
|
|
446
|
+
participant Socket as Proximity Server
|
|
447
|
+
|
|
448
|
+
Device->>Socket: scan_result(payload)
|
|
449
|
+
Socket->>Socket: Validate payload
|
|
450
|
+
|
|
451
|
+
alt Validation error
|
|
452
|
+
Socket-->>Device: ACK {status: "error", message}
|
|
453
|
+
else Success
|
|
454
|
+
Socket-->>Device: ACK {status: "ok"}
|
|
455
|
+
end
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
📌 **Key Points**
|
|
459
|
+
|
|
460
|
+
* ACKs are **mandatory**
|
|
461
|
+
* Devices never block on server failures
|
|
462
|
+
* Errors are structured and loggable
|
|
463
|
+
|
|
464
|
+
---
|
|
465
|
+
|
|
466
|
+
## 7️⃣ Device Disconnect & Cleanup
|
|
467
|
+
|
|
468
|
+
```mermaid
|
|
469
|
+
sequenceDiagram
|
|
470
|
+
participant Device as Native Device
|
|
471
|
+
participant Socket as Proximity Server
|
|
472
|
+
participant Cache as Proximity Cache
|
|
473
|
+
|
|
474
|
+
Device->>Socket: disconnect
|
|
475
|
+
Socket->>Socket: Stop scan interval
|
|
476
|
+
Socket->>Cache: Remove device entry
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
📌 **Key Points**
|
|
480
|
+
|
|
481
|
+
* Prevents memory leaks
|
|
482
|
+
* Ensures stale proximity data is removed
|
|
483
|
+
* Safe for flaky mobile networks
|
|
484
|
+
|
|
485
|
+
---
|
|
486
|
+
|
|
487
|
+
# ✅ Diagram Coverage Summary
|
|
488
|
+
|
|
489
|
+
| Area | Covered |
|
|
490
|
+
| ------------------------- | ------- |
|
|
491
|
+
| Native scanning lifecycle | ✅ |
|
|
492
|
+
| Wi-Fi ingestion | ✅ |
|
|
493
|
+
| Wi-Fi P2P + caching | ✅ |
|
|
494
|
+
| BLE ingestion | ✅ |
|
|
495
|
+
| Web client flow | ✅ |
|
|
496
|
+
| Error handling | ✅ |
|
|
497
|
+
| Disconnect cleanup | ✅ |
|
|
498
|
+
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
openapi: 3.0.3
|
|
2
|
+
|
|
3
|
+
info:
|
|
4
|
+
title: Proximity Sensor API
|
|
5
|
+
version: 1.0.0
|
|
6
|
+
description: |
|
|
7
|
+
Proximity Sensor API responsible for:
|
|
8
|
+
- Receiving Wi-Fi and Wi-Fi Direct scan results from proximity devices
|
|
9
|
+
- Persisting DeviceScan data
|
|
10
|
+
- Resolving nearby vendors via SSID matching
|
|
11
|
+
- Serving proximity-based inventory discovery for web clients
|
|
12
|
+
|
|
13
|
+
servers:
|
|
14
|
+
- url: https://www.proximityapp.ai/api
|
|
15
|
+
description: Production
|
|
16
|
+
- url: https://beta.proximityapp.ai/api
|
|
17
|
+
description: Beta
|
|
18
|
+
- url: https://sandbox.proximityapp.ai/api
|
|
19
|
+
description: Sandbox
|
|
20
|
+
- url: http://localhost:5000/api
|
|
21
|
+
description: Local Development
|
|
22
|
+
|
|
23
|
+
tags:
|
|
24
|
+
- name: Sensor
|
|
25
|
+
description: Proximity sensor ingestion endpoints
|
|
26
|
+
- name: Proximity
|
|
27
|
+
description: Proximity-based discovery endpoints
|
|
28
|
+
|
|
29
|
+
paths:
|
|
30
|
+
|
|
31
|
+
/proximity/sensor/wifi/scan:
|
|
32
|
+
post:
|
|
33
|
+
tags: [Sensor]
|
|
34
|
+
summary: Submit Wi-Fi scan results from proximity sensor
|
|
35
|
+
description: |
|
|
36
|
+
Receives Wi-Fi scan results from a proximity device.
|
|
37
|
+
Saves scan data and resolves nearby vendors by SSID match.
|
|
38
|
+
requestBody:
|
|
39
|
+
required: true
|
|
40
|
+
content:
|
|
41
|
+
application/json:
|
|
42
|
+
schema:
|
|
43
|
+
$ref: "#/components/schemas/WifiScanPayload"
|
|
44
|
+
responses:
|
|
45
|
+
"200":
|
|
46
|
+
description: Scan processed successfully
|
|
47
|
+
content:
|
|
48
|
+
application/json:
|
|
49
|
+
schema:
|
|
50
|
+
$ref: "#/components/schemas/ScanAck"
|
|
51
|
+
"400":
|
|
52
|
+
description: Invalid payload
|
|
53
|
+
"500":
|
|
54
|
+
description: Internal server error
|
|
55
|
+
|
|
56
|
+
/proximity/sensor/wifip2p/scan:
|
|
57
|
+
post:
|
|
58
|
+
tags: [Sensor]
|
|
59
|
+
summary: Submit Wi-Fi Direct scan results
|
|
60
|
+
description: |
|
|
61
|
+
Receives Wi-Fi Direct (P2P) scan results from nearby devices.
|
|
62
|
+
Persists scan data and caches proximity metadata.
|
|
63
|
+
requestBody:
|
|
64
|
+
required: true
|
|
65
|
+
content:
|
|
66
|
+
application/json:
|
|
67
|
+
schema:
|
|
68
|
+
$ref: "#/components/schemas/WifiScanPayload"
|
|
69
|
+
responses:
|
|
70
|
+
"200":
|
|
71
|
+
description: Scan processed successfully
|
|
72
|
+
content:
|
|
73
|
+
application/json:
|
|
74
|
+
schema:
|
|
75
|
+
$ref: "#/components/schemas/ScanAck"
|
|
76
|
+
"400":
|
|
77
|
+
description: Invalid payload
|
|
78
|
+
"500":
|
|
79
|
+
description: Internal server error
|
|
80
|
+
|
|
81
|
+
/proximity/inventory:
|
|
82
|
+
get:
|
|
83
|
+
tags: [Proximity]
|
|
84
|
+
summary: Get nearby vendor inventories
|
|
85
|
+
description: |
|
|
86
|
+
Resolves nearby vendors and inventories using the latest
|
|
87
|
+
proximity scan associated with a device.
|
|
88
|
+
parameters:
|
|
89
|
+
- name: x-device-sig
|
|
90
|
+
in: header
|
|
91
|
+
description: Persistent device signature
|
|
92
|
+
required: false
|
|
93
|
+
schema:
|
|
94
|
+
type: string
|
|
95
|
+
- name: public_ip
|
|
96
|
+
in: header
|
|
97
|
+
description: Public IP address of device
|
|
98
|
+
required: false
|
|
99
|
+
schema:
|
|
100
|
+
type: string
|
|
101
|
+
- name: x-ws-token
|
|
102
|
+
in: header
|
|
103
|
+
description: Optional WebSocket token
|
|
104
|
+
required: false
|
|
105
|
+
schema:
|
|
106
|
+
type: string
|
|
107
|
+
responses:
|
|
108
|
+
"200":
|
|
109
|
+
description: Nearby vendors found
|
|
110
|
+
content:
|
|
111
|
+
application/json:
|
|
112
|
+
schema:
|
|
113
|
+
type: array
|
|
114
|
+
items:
|
|
115
|
+
$ref: "#/components/schemas/VendorSnapshot"
|
|
116
|
+
"404":
|
|
117
|
+
description: No proximity data found
|
|
118
|
+
"500":
|
|
119
|
+
description: Internal server error
|
|
120
|
+
|
|
121
|
+
components:
|
|
122
|
+
|
|
123
|
+
schemas:
|
|
124
|
+
|
|
125
|
+
WifiScanPayload:
|
|
126
|
+
type: object
|
|
127
|
+
required:
|
|
128
|
+
- detected_wifi
|
|
129
|
+
- timestamp
|
|
130
|
+
properties:
|
|
131
|
+
device_id:
|
|
132
|
+
type: string
|
|
133
|
+
description: Device hardware or OS identifier
|
|
134
|
+
deviceSignature:
|
|
135
|
+
type: string
|
|
136
|
+
description: Persistent software-generated device signature
|
|
137
|
+
public_ip:
|
|
138
|
+
type: string
|
|
139
|
+
description: Public IP address of the device
|
|
140
|
+
timestamp:
|
|
141
|
+
type: string
|
|
142
|
+
format: date-time
|
|
143
|
+
scan_meta:
|
|
144
|
+
type: object
|
|
145
|
+
description: Scan metadata (RSSI stats, scan type, etc.)
|
|
146
|
+
additionalProperties: true
|
|
147
|
+
detected_wifi:
|
|
148
|
+
type: array
|
|
149
|
+
description: List of detected Wi-Fi networks
|
|
150
|
+
items:
|
|
151
|
+
$ref: "#/components/schemas/WifiNetwork"
|
|
152
|
+
|
|
153
|
+
WifiNetwork:
|
|
154
|
+
type: object
|
|
155
|
+
required: [ssid]
|
|
156
|
+
properties:
|
|
157
|
+
ssid:
|
|
158
|
+
type: string
|
|
159
|
+
description: Wi-Fi network SSID
|
|
160
|
+
bssid:
|
|
161
|
+
type: string
|
|
162
|
+
description: Access point MAC address
|
|
163
|
+
rssi:
|
|
164
|
+
type: number
|
|
165
|
+
description: Signal strength
|
|
166
|
+
frequency:
|
|
167
|
+
type: number
|
|
168
|
+
description: Frequency band
|
|
169
|
+
|
|
170
|
+
ScanAck:
|
|
171
|
+
type: object
|
|
172
|
+
properties:
|
|
173
|
+
status:
|
|
174
|
+
type: string
|
|
175
|
+
enum: [ok, error]
|
|
176
|
+
stores_count:
|
|
177
|
+
type: integer
|
|
178
|
+
description: Number of matched vendors
|
|
179
|
+
error:
|
|
180
|
+
type: string
|
|
181
|
+
description: Error message if status is error
|
|
182
|
+
|
|
183
|
+
VendorSnapshot:
|
|
184
|
+
type: object
|
|
185
|
+
description: Minimal vendor snapshot returned from proximity resolution
|
|
186
|
+
properties:
|
|
187
|
+
vendor_info:
|
|
188
|
+
$ref: "#/components/schemas/VendorInfo"
|
|
189
|
+
inventory:
|
|
190
|
+
type: array
|
|
191
|
+
items:
|
|
192
|
+
$ref: "#/components/schemas/InventoryItem"
|
|
193
|
+
|
|
194
|
+
VendorInfo:
|
|
195
|
+
type: object
|
|
196
|
+
properties:
|
|
197
|
+
vendor_id:
|
|
198
|
+
type: string
|
|
199
|
+
name:
|
|
200
|
+
type: string
|
|
201
|
+
address:
|
|
202
|
+
type: string
|
|
203
|
+
phoneNumber:
|
|
204
|
+
type: string
|
|
205
|
+
gps_location:
|
|
206
|
+
type: string
|
|
207
|
+
opening_hours:
|
|
208
|
+
type: string
|
|
209
|
+
|
|
210
|
+
InventoryItem:
|
|
211
|
+
type: object
|
|
212
|
+
properties:
|
|
213
|
+
item_id:
|
|
214
|
+
type: string
|
|
215
|
+
name:
|
|
216
|
+
type: string
|
|
217
|
+
category:
|
|
218
|
+
type: string
|
|
219
|
+
tags:
|
|
220
|
+
type: array
|
|
221
|
+
items:
|
|
222
|
+
type: string
|
|
223
|
+
price:
|
|
224
|
+
type: number
|
|
225
|
+
quantity_available:
|
|
226
|
+
type: number
|
package/package.json
CHANGED