Skip to content

Commit 447e748

Browse files
MrAlders0nMrAlders0n
committed
Add detailed flow diagram for MESHMAPPER API queue system
1 parent 84b9fa2 commit 447e748

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎docs/FLOW_WARDRIVE_API_QUEUE_DIAGRAM.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
┌─────────────────────────────────────────────────────────────────────────────────────────┐
2+
│ MESHMAPPER API QUEUE SYSTEM │
3+
└─────────────────────────────────────────────────────────────────────────────────────────┘
4+
5+
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
6+
│ TX WARDRIVE │ │ RX WARDRIVE │
7+
└─────────────┬────────---────────┘ └─────────────┬────────---────────┘
8+
│ │
9+
▼ ▼
10+
┌─────────────────┐ ┌─────────────────┐
11+
│ sendPing() │ │ RX Listener │
12+
│ (BLE ping) │ │ (always on) │
13+
└────────┬────────┘ └────────┬────────┘
14+
│ │
15+
▼ │
16+
┌─────────────────┐ │
17+
│ Ping sent │ │
18+
│ + GPS coords │ │
19+
└────────┬────────┘ │
20+
│ │
21+
▼ ▼
22+
┌─────────────────┐ ┌─────────────────┐
23+
│ queueApiMessage │ │ queueApiMessage │
24+
│ (type: "TX") │ │ (type: "RX") │
25+
│ │ │ │
26+
│ • lat/lon │ │ • lat/lon │
27+
│ • who │ │ • who │
28+
│ • power │ │ • power │
29+
│ • heard │ │ • heard │
30+
│ • session_id │ │ • session_id │
31+
└────────┬────────┘ └────────┬────────┘
32+
│ │
33+
│ ┌──────────────────────────────────┘
34+
│ │
35+
▼ ▼
36+
┌───────────────────────────────────────────────────────────────────────────────────────┐
37+
│ │
38+
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
39+
│ │ API QUEUE (apiQueue. messages) │ │
40+
│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │
41+
│ │ │ TX │ │ RX │ │ RX │ │ TX │ │ RX │ ... │ ?? │ max: 50 │ │
42+
│ │ │ msg1 │ │ msg2 │ │ msg3 │ │ msg4 │ │ msg5 │ │msg50 │ │ │
43+
│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │
44+
│ └─────────────────────────────────────────────────────────────────────────────┘ │
45+
│ │
46+
│ QUEUE STATE: │
47+
│ • messages: [] ─── Array of pending payloads │
48+
│ • flushTimerId: null ─── 30s periodic timer │
49+
│ • txFlushTimerId: null ─── 3s TX flush timer │
50+
│ • isProcessing: false ─── Lock to prevent concurrent flushes │
51+
│ │
52+
└───────────────────────────────────────────────────────────────────────────────────────┘
53+
│
54+
│
55+
┌─────────────────────────────┼─────────────────────────────┐
56+
│ │ │
57+
│ FLUSH TRIGGERS │ │
58+
│ │ │
59+
│ ┌──────────────────────────┴────────────────────────┐ │
60+
│ │ │ │
61+
▼ ▼ ▼ ▼
62+
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
63+
│ │ │ │ │ │ │ │
64+
│ TX PING QUEUED │ │ 30s PERIODIC │ │ QUEUE SIZE = 50 │ │ disconnect() │
65+
│ │ │ │ │ │ │ │
66+
│ ┌───────────────┐ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │
67+
│ │ Start/Reset │ │ │ │ setInterval │ │ │ │ Immediate │ │ │ │ Flush before │ │
68+
│ │ 3s timer │ │ │ │ (30000ms) │ │ │ │ flush │ │ │ │ capacity │ │
69+
│ └───────────────┘ │ │ └───────────────┘ │ │ └───────────────┘ │ │ │ release │ │
70+
│ │ │ │ │ │ │ └───────────────┘ │
71+
│ Real-time map │ │ Catches RX msgs │ │ Batch limit │ │ │
72+
│ updates for your │ │ when no TX pings │ │ protection │ │ Clean shutdown │
73+
│ ping locations │ │ happening │ │ │ │ │
74+
│ │ │ │ │ │ │ │
75+
└──────────┬──────────┘ └──────────┬──────────┘ └──────────┬──────────┘ └──────────┬──────────┘
76+
│ │ │ │
77+
└───────────────────────┴───────────────────────┴───────────────────────┘
78+
│
79+
▼
80+
┌─────────────────────────┐
81+
│ flushApiQueue() │
82+
│ │
83+
│ 1. Check isProcessing │
84+
│ 2. Set isProcessing │
85+
│ 3. Grab & clear queue │
86+
│ 4. POST batch to API │
87+
│ 5. Handle response │
88+
│ 6. Clear isProcessing │
89+
└────────────┬────────────┘
90+
│
91+
▼
92+
┌─────────────────────────┐
93+
│ MESHMAPPER API │
94+
│ │
95+
│ POST [ │
96+
│ {TX, lat, lon... }, │
97+
│ {RX, lat, lon...}, │
98+
│ {RX, lat, lon...}, │
99+
│ ... │
100+
│ ] │
101+
│ │
102+
│ Max: 50 per request │
103+
└────────────┬────────────┘
104+
│
105+
┌─────────────────┴─────────────────┐
106+
▼ ▼
107+
┌─────────────────────┐ ┌─────────────────────┐
108+
│ allowed: true │ │ allowed: false │
109+
│ │ │ │
110+
│ ✓ Success │ │ ✗ Slot Revoked │
111+
│ ✓ Continue │ │ ✗ Stop timers │
112+
│ │ │ ✗ Disconnect │
113+
└─────────────────────┘ └─────────────────────┘
114+
115+
┌─────────────────────────────────────────────────────────────────────────────────────────┐
116+
│ TIMING EXAMPLES │
117+
└─────────────────────────────────────────────────────────────────────────────────────────┘
118+
119+
Example 1: TX triggers fast flush, nearby RX messages ride along
120+
────────────────────────────────────────────────────────────────
121+
0s 1s 2s 3s 4s
122+
│ │ │ │ │
123+
│ RX │ │ │ │
124+
│ (heard) │ │ │
125+
│ │ TX │ │ │
126+
│ │ (ping) │ │ │
127+
│ │ │ │ │ │
128+
│ │ └────┼─────────┼─►FLUSH │
129+
│ │ │ │(TX+RX) │
130+
└─────────┴─────────┴─────────┴─────────┘
131+
3 second delay from TX
132+
133+
134+
Example 2: RX only (no pings) - 30s periodic flush
135+
──────────────────────────────────────────────────
136+
0s 10s 20s 30s
137+
│ │ │ │
138+
RX────────┼─────────┼─────────┼─►FLUSH
139+
│ RX │ RX │ │ (3x RX)
140+
│ │ RX │ │
141+
│ │ │ │
142+
└─────────┴─────────┴─────────┘
143+
(listening continuously, no TX pings sent)
144+
145+
146+
Example 3: Busy session - multiple TX pings with RX traffic
147+
───────────────────────────────────────────────────────────
148+
0s 3s 6s 9s 12s
149+
│ │ │ │ │
150+
TX────────┼─►FLUSH │ │ │
151+
│ RX │ (TX+RX) │ │ │
152+
│ │ TX────────┼─►FLUSH │
153+
│ │ │ RX │ (TX+RX) │
154+
│ │ │ RX │ │
155+
└─────────┴─────────┴─────────┴─────────┘
156+
157+
158+
Example 4: Disconnect flushes everything
159+
────────────────────────────────────────
160+
0s 1s 2s
161+
│ │ │
162+
TX────────┼─────────┤
163+
│ RX │ RX │
164+
│ │ disconnect()
165+
│ │ │
166+
│ │ ▼
167+
│ │ FLUSH (TX + 2x RX) ◄── session_id still valid
168+
│ │ │
169+
│ │ ▼
170+
│ │ checkCapacity("disconnect") ◄── releases slot
171+
│ │ │
172+
│ │ ▼
173+
│ │ BLE cleanup
174+
└─────────┴─────────┘
175+
176+
177+
┌─────────────────────────────────────────────────────────────────────────────────────────┐
178+
│ DISCONNECT SEQUENCE │
179+
└─────────────────────────────────────────────────────────────────────────────────────────┘
180+
181+
┌──────────────────┐
182+
│ disconnect() │
183+
│ called │
184+
└────────┬─────────┘
185+
│
186+
▼
187+
┌──────────────────┐ ┌─────────────────────────────────────┐
188+
│ Queue empty? │─NO─►│ flushApiQueue() │
189+
└────────┬─────────┘ │ • session_id still valid ✓ │
190+
│ │ • POST all pending TX + RX │
191+
YES └──────────────────┬──────────────────┘
192+
│ │
193+
◄──────────────────────────────────┘
194+
│
195+
▼
196+
┌──────────────────┐
197+
│ stopFlushTimers()│
198+
│ • Clear 30s timer│
199+
│ • Clear TX timer │
200+
└────────┬─────────┘
201+
│
202+
▼
203+
┌──────────────────┐
204+
│ checkCapacity │
205+
│ ("disconnect") │◄─── Releases session_id / slot
206+
└────────┬─────────┘
207+
│
208+
▼
209+
┌──────────────────┐
210+
│ BLE disconnect │
211+
│ State cleanup │
212+
│ UI updates │
213+
└──────────────────┘

0 commit comments

Comments
 (0)