How it all works.Part by part.

Turning vibration into numbers.

• 25 Hz motion sampling — accelerometer + gyroscope via CMDeviceMotion, each sample stamped with the most recent GPS fix (~1 Hz, BestForNavigation accuracy).
• Gyro-orientation cleaning — the attitude quaternion rotates device-frame acceleration into the world frame; only the vertical (z) component becomes the roughness signal. At rest, RMS ≈ 0.
• Raw cache — an in-memory buffer flushed to SQLite every 5 s (ts, GPS lat/lon/altitude/accuracy/speed, gyro, accelerometer, vertical, horizontal).
• 2 s RMS windows — Σv² per window → rms = √(Σv²/n), with the window midpoint, mean position and mean speed, written every 10 s.
• 60-minute retention — the database is a rolling cache, not an archive; older rows are pruned on every flush.
• No measurements below 7 km/h — the speed gate also invalidates the partial window, so a slow stretch can never bridge two windows. The UI shows “PAUSED < 7 KM/H”.
• Walk mode — a persisted toggle removes the speed gate entirely for pedestrian measurements.

The temporary SQLite file lives in the app's tmp directory (the OS may purge it); its path is shown in the UI.

Start, lock, forget.

• Start / Stop buttons with a live RMS display and a paused-state badge.
• The screen never locks while measuring — the idle timer is disabled during a session.
• Background collection — the location background mode keeps the process alive, so 25 Hz sampling continues off-screen (the blue iOS location indicator). When-In-Use permission is sufficient.
• Honest caveats, documented in-app docs: force-quitting stops collection; long GPS outages may let iOS suspend the app.

Your drive, colored as you go.

• OpenStreetMap basemap — OSM tiles replace Apple's (attribution shown; HTTPS per the OSM tile policy).
• RMS track lines — one polyline per consecutive pair of RMS windows, 5 px, colored green → red (hue 120° → 0°) by rms / maxRMS(last 10 min).
• Follows the current position — the map re-centers as you move.

ZIP it, send it, delete it.

• Export & Share — streams both tables into dobrovozim_<timestamp>.zip (deflate with a store fallback), shared through the system share sheet.
• Automatic upload every 5 minutes while measuring, one final attempt on Stop, plus a manual Send now button — 60 s timeout.
• Slim payload — rms_windows.csv in the 6-column ts_epoch,lat,lon,rms_ms2,samples,speed_mps layout + client_id.txt: −39 % after deflate, all information preserved. Raw 25 Hz rows are never uploaded.
• Delete-on-success — any 2xx deletes exactly the sent rows; rows flushed during the upload stay for the next cycle; failures retry on the next cycle. No data loss.
• Map continuity — uploaded rows stay visible on the 10-minute track via an in-memory buffer.
• Plain HTTP allowed (ATS exception) so LAN backends like http://192.168.1.10:8080 work; the URL must be the full upload endpoint.

One ID, for the device's whole life.

• A fixed, non-editable Device ID is generated once and stored in the iOS Keychain — it survives restarts, app updates and even uninstall/reinstall. Only a device erase purges it.
• The ID goes into client_id.txt and the X-Client-Id header of every upload.
• Shown in Settings with a Copy button, ready for the registration form.

Your session, behind your face.

• Login screen — username-or-email + password; the token goes to the Keychain, the user snapshot to UserDefaults; distinct errors for every account failure code.
• Signup screen — creates a data_supplier account and auto-logs-in with the same credentials.
• Face ID session unlock — at launch the stored token loads only after a successful biometric prompt; no biometry means no prompt and a direct load.
• Session freshness — GET /auth/me re-syncs role and ban state after each unlock; a stale token is dropped locally before it can be unlocked.
• Role gating client-side — registration and uploads are offered only to supplier/admin/superuser roles; analysts and guests get a friendly message naming their role.
• Ban state — banned users can still log in and read; a persistent red banner explains that sending is disabled. Read-only mode shows an orange banner.
• Logout — revokes server-side (best effort) and deletes the keychain token and cached identity.

No browser required.

• A device registration card mirrors the web portal: car make/model/year/country, a mandatory format-checked email (the administrator's contact point), optional name/surname.
• Device model auto-detected from the hardware identifier — e.g. iPhone15,3 becomes “iPhone 14 Pro Max”.
• device_id is the app's fixed Device ID, so an approval whitelists exactly the id the app uploads with.
• Send → poll → notify — the app polls the request on launch, on upload rejections, and via Check now; when the decision flips, a local notification fires (banner even while backgrounded).
• Session-aware — a 401 prompts password login first (form fields persist); denied requests can simply be sent again.

A home page that knows who you are.

• Role-gated cards — every card carries data-roles; pseudo-roles * (everyone), anon (no valid session) and auth (any signed-in user) decide visibility next to the five real roles.
• Every page stays reachable by direct URL — cards are only links, never gates.
• Session awareness — on load the hub validates the stored token against GET /auth/me; a dead token is dropped (obsolete pre-accounts keys are swept too) and the anonymous card set returns.
• Signed-in users see a session box — “Logged in as … (role)”, analysts additionally their assigned layers — and a Log out button that revokes the session server-side.

Sign in, sign up, register the car.

• Login page — email-or-username + password; the token and user snapshot land in localStorage["dobrovozim.session"]; invalid credentials surface a visible error and store nothing; banned users are flagged.
• Registration page, two-stage — account signup (auto-login) then the device-request form; an existing supplier session skips straight to the device form.
• Exact field errors for every contract code; a valid form POSTs the trimmed payload — car year as an integer, optional fields dropped.

Open to everyone, no account needed.

• Status page — public request-status lookup by reference id; renders approved / not-found / network-failure states and shows the assigned Device ID once approved. No PII ever. Auto-refreshes every 10 s while pending.
• Public map — the anonymous RMS layer on OpenStreetMap with the color-scale combo, aggregation-statistic selector, speed-bucket filter and the desktop's opacity and background controls; collapsible controls panel; no auth at all.
• Colors are anchored to the database-wide RMS p95 from the response's stats block, so colors stay comparable across views and zooms.

Three consoles for the people in charge.

• Admin approvals — the approval queue and user management for administrator | superuser: approve, deny or delete registrations with the session bearer; a wrong role answers “Insufficient role”; a mid-session 401 drops the panel and offers the login link.
• Directory — devices & accounts overview: registrations with full details and Approve/Deny; devices with owner_username; administrators ban and edit layers; the superuser additionally changes roles, resets passwords and deletes.
• Superuser console — the server-wide read-only switch loads and toggles here; administrator account creation; delete is refused for self.

Two small files carry the whole portal.

• app.js — the api() wrapper: JSON encode/parse, bearer-token injection, the backend error envelope turned into an Error carrying .status/.code/.message, a friendly network-failure path, plus DOM helpers ($, el, setText, escapeHtml, fmtDate, notices…).
• colormap.js — the five color scales with adaptive yellow placement, kept byte-identical to the desktop implementation and tested against it.

And the page you are reading.

• features.html — a self-contained documentation page in the landing page's visual language: same palette, same typographic voice, zero dependencies.
• It documents every component of the project and can be opened straight from disk or served alongside the portal at /web/features.html.

The same account, on the desktop.

• A modal login dialog at startup (username-or-email + password) with a hint linking to the web portal for account creation; a register dialog signs up and auto-logs-in.
• Session persistence — token + user snapshot in QSettings, so a restart resumes the 30-day session; any 401 clears it and re-prompts; “Log out” revokes server-side.
• Role gating — administrator | superuser get everything; suppliers and guests see the public layer and minimal UI; an analyst sees exactly the layers assigned to their account.
• The desktop-only “Live squares (admin)” layer entry is visible to every session but disabled with a hint for roles without access — an unauthorized fetch is never even sent.

Cells that adapt to the data.

• Grid-cell layer over OSM — the backend's aggregated cells drawn as a colored canvas-rendered Leaflet layer over OpenStreetMap tiles.
• Data-adaptive green-yellow-red scale — yellow sits exactly at the 75th percentile of the displayed values (the top-25 % boundary) and red at the maximum; stop positions are recomputed from the data on every fetch.
• Statistic selector — Median / Mean / Min / Max; changing it (or the scale or opacity) only restyles the layer, no refetch.
• Minimum cell size — a spinbox (1–10 000 m, default 100) floors the requested grid width: zooming in never yields bins smaller than this.
• Viewport-matched cells — the page reports a viewport-derived cell size with every bounds change, so requested cells line up with the view; zooming changes the level of detail.
• Basemap dimming — 0–100 %, and 0 % hides the tiles completely so the cells carry the screen; the setting persists.
• Tooltips & details — hover shows cell size, statistic and counts; clicking opens every feature property plus the polygon center and cell indices.
• Filters & reloads — client filter and speed-bucket checkboxes; auto-load on start with saved filters; failures land in the status bar, never in modal dialogs; manual bbox entry with a graceful fallback to the map view.

Python and the page, talking both ways.

• Python → JS via runJavaScript calling page globals: addGeoJSON, clearFeatures, applyStyle.
• JS → Python over QWebChannel (vendored): the page emits map_ready, bounds_changed (with the derived cell size and steps) and feature_clicked.
• Resilient fallbacks — missing vendor files fall back to public CDNs automatically; if even the channel shim cannot load, the bridge degrades to console-message decoding with the same public API.
• A WebEngine quirk is fixed in-app: local content may access remote URLs, so a file:// page can still fetch OSM tiles.

Every knob in one dialog, remembered.

• One modal Settings dialog (File → Settings…, Ctrl+,) holds everything: the signed-in account group, backend URL with a live Check and health label, area source, client & bucket filters, style group and the admin group.
• Persists every change immediately into QSettings keys — backend URL, filters, opacities, scale, statistic, min cell, map center and zoom; compound values are JSON-encoded, every value is coerced and validated on load, unknown keys are silently dropped.
• The last map center and zoom are restored on start; the backend status is one click away.

Approval work, three tabs wide.

• Devices tab — every registered device stays visible (pending, declined and approved) with a Show filter, attempt counters and first/last-seen; Approve / Decline sit behind confirmation dialogs and auto-refresh follows every decision.
• Users tab — the accounts list with a role filter and search; Ban / Unban behind confirmation; reads keep working for banned users while data operations are blocked.
• Directory tab — two sub-tabs: Registrations (full details + Approve/Deny — approving also links the device to the requesting account) and Devices (whitelist entries with owners).
• Rebuild public layer — forces an immediate rebuild and shows the compact outcome (“rebuilt: 1 234 bins · 56 789 pts · 3.2 s”) or the exact failure; disabled while a rebuild is in flight.
• Read-only mode — a superuser-only checkbox with confirmation; administrators see the same state as a badge.
• Bulk dumps ingestion is exposed among the session-guarded admin calls.

Fifteen workers, one rule each.

• 15 one-shot worker types — Health, FetchSquares, Layers, RebuildPublicLayer, ClientRequests, ClientDecision, Login, Register, Logout, Me, ReadOnly, Users, BanUser, Directory, RegistrationDecision.
• Each runs a single HTTP call on a QThread and emits one terminal signal — the GUI never blocks on the network.
• Token-carrying workers emit unauthorized on a 401 (instead of a generic failure) so the main window re-prompts login.
• A Qt 6.11 interruption quirk is worked around with a mirrored Python flag.

Double-click to map.

• DOBROVOZIM Map.command — a double-clickable macOS launcher that bootstraps the virtualenv + PySide6 on first run and keeps the Terminal open on errors.
• run.sh — venv resolution with an older-Python fallback and a system-python warning; arguments pass through.
• Headless mode — --offscreen for CI, with the matching Qt flags.
• tools/validate.py — a staged gate: compile, structure, contract markers, a real headless main-window instantiation, and a live-API check with polite SKIPs.
• Accounts smoke & probes — a self-contained offscreen accounts test against a local mock backend, plus a probe for a running local backend.

A fake DOM for real logic.

• Node's built-in runner with zero npm dependencies; browser IIFEs load via node:vm behind a small fake-DOM harness.
• Covers the api() wrapper and helpers, colormap parity, the register and status flows, and the full accounts flows — login, the role-gated hub, directory, admin and superuser pages.

Hermetic tables, real database when needed.

• A standalone Go module of hermetic table-driven tests for the pure logic: speed buckets, geo/EWKB math, the config matrix, CSV parsing (including mid-stream I/O errors), registration validation and public-layer grid math.
• In-package integration tests beside the code cover uploads, web registrations, the public layer, the grid, rate limiting, the auth flow and hardening — with a real-DB flow via TEST_DATABASE_URL.

Qt forced offscreen, thoroughly exercised.

• pytest with Qt forced offscreen before import.
• The colormap is cross-checked against the JavaScript implementation — the parity guarantee from Part 01, enforced.
• Settings defaults, coercion and round-trips on a temp backend; session-store round trips with corrupt-snapshot resilience; client request-building and error mapping; worker auth routing and one-shot semantics.

XCTest, wired into the app's project.

• An XCTest target inside the Xcode project, run on the iOS Simulator via xcodebuild test.
• Covers the device-model mapping, ZIP writer CRC and archive round-trip, measurement-store RMS math, flush, prune and CSV+ZIP export, the speed-gate constant and walk-mode persistence, registration payload encoding, and the uploader's no-data skip.

Tests that protect the tests.

• A static migration guard bans destructive SQL unless a line is explicitly tagged as reviewed.
• The desktop ships a staged validation gate (compile → structure → contract → headless GUI → live API) and an offscreen accounts smoke test against a mock backend.
• The web suite asserts the colormap stop tables stay byte-identical across languages.