Maps SDK - Overview & Architecture

@bloomsparkagency/core is a private, commercial React/TypeScript indoor + outdoor mapping library. Distributed via GitHub Packages (scope @bloomsparkagency), it is built on MapLibre GL JS, PMTiles, deck.gl, Terra Draw, and Zustand.

The SDK is engineered to be the most ergonomic, performant, and vendor-agnostic building digital twin library on the market—competing directly with Smplrspace, Mappedin JS v6, Cisco Spaces, and Apple Indoor Maps.

---

🎯 Target Verticals

The library includes pre-tuned, high-performance profiles specifically for:

1. Smart Office / Corporate Campus: Hot-desking mapping, live meeting room occupancy, popular-times charts, and employee locators.
2. Smart Hospital / Healthcare: Live asset tracking (IV pumps, wheelchairs), patient-flow heatmaps, ICU/ward occupancy statuses, and visual Code Blue alarms.
3. Smart Factory / Warehouse: Forklift motion trails, safe zone geofencing, conveyor-line metrics (OEE), and machine-down alerts.
4. Smart Campus (University/Retail): Building footprint overlays, class/store directories, parking availability indicators, and accessible wayfinding.

---

✨ Distinctive Capabilities

• Self-Hosted Tiles via PMTiles: High-performance base mapping with no managed-cloud provider lock-in. A complete global basemap can be hosted on Cloudflare R2 or AWS S3 for less than $2/month.
• Complete IMDF 1.0.0 Support: In-browser IMDF loading, deep schema validation, and exporting mapped buildings directly to Microsoft Places and Apple Indoor Maps.
• Homography Blueprints Georeferencing: Warps photographed or scanned PDF/PNG blueprints using least-squares WebGL homography shaders, preserving complete 3D z-order and rendering instantly during MapLibre camera ease passes.
• 14+ RTLS Adapters: First-class, Web Worker-driven adapters for Sewio, Quuppa, Pozyx, Kontakt.io, Cisco Spaces, CenTrak, Stanley/AeroScout, Zebra, and generic WebSocket/SSE/MQTT/REST streams.
• Context-Shared Rendering: deck.gl and MapLibre GL JS share a single WebGL context using MapboxOverlay. This prevents double-buffering, keeps the frame rate locked at 60 FPS, and effortlessly tracks 5,000+ real-time assets.
• Temporal Undo/Redo Editor: Includes a drop-in <SpatialEditor /> with drawing snapping, custom Wall/Door modes, cross-floor copying, and patch-based transaction histories (Zundo) to keep browser memory usage sub-megabyte.

---

🏗️ Architectural Core Principles

To ensure extreme performance (Time to Interactive ≤ 2.5 s, first paint ≤ 1.5 s, constant 60 FPS under load), the SDK enforces three absolute engineering rules:

1. Stable MapLibre Source/Layer Keying

Never recreate a MapLibre source or layer on React re-render. Sources and layers are keyed by stable IDs; all live runtime updates (sensor values, selections, filters) MUST go through imperative calls:

• source.setData(geojson)
• map.setPaintProperty()
• map.setLayoutProperty()
• map.setFeatureState() (hover and real-time state styling).

2. React Rendering Decoupling for High-Frequency Updates

RTLS positions are NOT stored in Zustand. High-frequency stream frames bypass React state completely. They are processed inside a Web Worker, piped via a shared buffer to a ref-based PositionMap (Map<assetId, PositionUpdate>), and read in a requestAnimationFrame loop. Only visible-floor asset positions are rendered via setFeatureState(). Off-floor assets are buffered but culled.

3. Web Worker Offloading (Comlink RPC)

All computationally heavy tasks run in dedicated background threads:

• IMDF ZIP parsing & decompressive parsing (fflate).
• Wayfinding graph calculations (A* node searching & vertical floor connection inferences).
• High-frequency Kalman filtering (KalmanFilter2D utility).
• RTLS and telemetry stream polling/connections.
• PMTiles range-request batching.