Project Map

"/home/yossef/notes/git/projects/maplibra/Project Map.md"

path: maplibra/Project Map.md

- **fileName**: Project Map
- **Created on**: 2026-06-16 00:48:42

Project Map

Purpose: Directory-level map of important files and folders.

Related: ./Home.md, ./Architecture.md

Root Structure

src/                    → App source code
  app/                  → Core app services (floor data, assets, caching, Android bridge)
  bootstrap/            → Startup orchestration (shell, map, data, routing, search, debug)
  controllers/          → Sub-controllers (location, navigation, routing)
  layers/               → Layer rendering, visibility, debug overlays
  pathfinding/          → All pathfinding and routing modules
  path-renderer/        → Route line animation and rendering
  outdoor/              → Outdoor routing integration
  positioning/          → GPS/positioning WASM
  ui/                   → UI components (SearchBox, ThemeController, ErrorToast)
  utils/                → Shared utilities (distance, easing, constants, geometry)
  workers/              → Web Workers (MVF, geo, path, derived-asset)
scripts/                → Offline build tools and data sync
native/routing/         → C source for WASM kernel
tests/                  → Vitest test suite (95+ test files)
assets/                 → Built routing data, MVF bundles, debug GeoJSON
docs/                   → Operator guides (routing rollout, perf baseline, offline packaging)
analysis_map/           → Node data documentation and rendering flow
obs_vaults/             → This developer documentation vault

Key Source Files by Area

App Core (src/app/)

File	Lines	Responsibility
`floor-data.js`	560	Floor loading, caching, memory pressure, fast render
`asset-provider.js`	293	ZIP, network, overlay, hybrid asset providers
`derived-asset-cache.js`	590	IndexedDB cache, meta index, hash keys, serialization
`android-bridge.js`	78	WebView communication, floor sync, native controls
`derived-asset-builder.js`	—	Build routing graphs from MVF data
`startup-task-queue.js`	—	Deferred startup task scheduling
`geo-prep.js`	—	Precompute style layers, doors, labels per floor
`offline-config.js`	—	Offline tile prefetch, network routing flags
`cached-mvf-loader.js`	—	Restore MVF from IndexedDB cache

MVF Loading (src/)

File	Lines	Responsibility
`mvf-loader.js`	671	ZIP parsing, Web Worker, manifest/floor/geometry loading
`startup-task-queue.js`	—	Deferred startup task scheduling
`geo-prep.js`	—	Precompute style layers, doors, labels per floor
`offline-config.js`	—	Offline tile prefetch, network routing flags
`cached-mvf-loader.js`	—	Restore MVF from IndexedDB cache

Bootstrap (src/bootstrap/)

File	Lines	Responsibility
`bootstrap-shell.js`	109	Theme, error handler, toast, service worker, viewport
`bootstrap-map.js`	21	Map, LayerManager, UIManager creation
`bootstrap-data.js`	17	App handle storage, attachDerivedAssets, primeMapExperience
`bootstrap-routing.js`	33	Lazy routing controller loading
`bootstrap-search.js`	—	Lazy search box initialization
`bootstrap-debug.js`	—	Lazy debug layer loading
`create-app-context.js`	34	Shared context: perf, telemetry, rollout, services, flags
`startup-perf.js`	—	Performance marks, measures, long task observation
`runtime-flags.js`	—	URL query routing config parsing
`rollout-telemetry.js`	—	Fire-and-forget telemetry delivery

Pathfinding (src/pathfinding/)

File	Lines	Responsibility
`route-compute.js`	849	Full route computation orchestration
`snapping.js`	177	Snap user clicks to graph nodes
`route-smoothing.js`	922	Shortcut smoothing + Bezier curves
`route-smoothing-enhanced.js`	987	Chaikin/Catmull-Rom human-like smoothing
`doors.js`	56	Door feature extraction + room intersection
`rooms.js`	64	Room polygon resolution + containment
`walkable-areas.js`	78	Walkability point/segment checks
`wasm/route-kernel-bridge.js`	313	JS-to-WASM bridge
`routing-cost.js`	81	Edge cost functions + accessibility
`campus-routing.js`	—	Campus-scale multi-building routing
`navigation.js`	—	Navigation UI panel, route summary
`gps-tracking.js`	—	Live GPS tracking, rerouting
`follow-camera.js`	—	Camera follow during navigation
`accessibility.js`	—	Accessibility routing options
`drop-ui.js`	—	Drop-mode UI for selecting target
`markers.js`	—	Start/target marker management
`events.js`	—	Map click, marker, floor change events
`points.js`	—	Point selection, annotation bridging
`selection-bridge.js`	—	Bridge selection between UI and routing
`route-features.js`	—	Route feature generation per floor
`route-trace.js`	—	Route trace diagnostics
`route-cache.js`	—	Route result caching
`binary-graph-loader.js`	—	Binary graph loading
`binary-graph-schema.js`	—	Binary graph format schema
`binary-graph-serializer.js`	—	Binary graph serialization
`binary-graph-views.js`	—	Binary graph view accessors
`binary-graph-parity.js`	—	JS/WASM parity verification
`graph-slice-loader.js`	—	Graph slice loading
`graph-slice-cache.js`	—	Graph slice LRU cache
`graph-slice-schema.js`	—	Graph slice format schema
`graph-slice-serializer.js`	—	Graph slice serialization
`unified-graph.js`	—	Unified graph for outdoor+indoor
`portal/`	—	Portal (door/elevator/stair) graph building
`services/`	—	Graph data service, routing engine service

Controllers

File	Responsibility
`src/controllers/routing-controller.js`	Graph loading, route computation, engine selection
`src/controllers/location-controller.js`	Markers, selection, drop mode, floor changes
`src/controllers/navigation-controller.js`	GPS tracking, follow camera, navigation UI

Entry Point

File	Lines	Responsibility
`script.js`	2609	Main app entry: MVF loading, map init, UI wiring, global API
`index.html`	471	Shell markup, drop screen, top bar, legend, settings
`style.css`	—	App styles, theme variables, animation
`theme.js`	—	Light/dark theme definitions, color maps

Path Renderer (src/path-renderer/)

File	Responsibility
`animation.js`	Route line animation, progress interpolation
`layers.js`	Route layer creation, source updates, style integration
`metrics.js`	Route distance, duration, step metrics
`route.js`	Route state management, segment handling
`utils.js`	Path renderer utilities

UI Components (src/ui/)

File	Responsibility
`SearchBox.js`	Search input, suggestions, location selection
`ThemeController.js`	Theme toggle, localStorage persistence
`ErrorToast.js`	Error/warning toast notifications
`navigation/`	Navigation-specific UI components
`poi-discovery.js`	POI discovery and enrichment

Layer Management (src/layers/)

File	Responsibility
`base-layers.js`	Building shell, base map layers
`base/`	Base layer definitions
`debug-node-layers-part1.js`	Wall, stairs, elevator, annotation layers
`debug-node-layers-part2.js`	Walkable, nonwalkable, kinds, entrance, location layers
`debug/`	Debug layer mixins (wall, stairs, walkable, etc.)
`visibility-manager.js`	Floor filtering, zoom rules, layer toggles

Workers (src/workers/)

File	Responsibility
`mvf-worker.js`	MVF ZIP parsing in Web Worker
`geo-worker.js`	Geometry preparation in Web Worker
`path-worker.js`	Pathfinding computation in Web Worker
`derived-asset-worker.js`	Derived asset building in Web Worker

Native (WASM) Files

File	Lines	Responsibility
`native/routing/route_kernel.c`	331	C A* core
`native/routing/route_smoothing.c`	242	Segment walkability + shortcut finding
`native/routing/route_geometry.c`	30	Point-in-polygon, point-segment distance
`native/routing/route_spatial.c`	145	Nearest-node brute scan
`native/routing/route_heap.c`	—	Min-heap for A*
`native/routing/route_options.h`	77	RoutingOptions struct (48 bytes)

Outdoor Routing (src/outdoor/)

File	Responsibility
`outdoor-routing.js`	Indoor/outdoor route stitching logic
`outdoor-router.js`	OSRM/nearest-road API calls, street route data

Tests

Area	Test Files
Routing	`route-smoothing.test.js`, `route-features.test.js`, `route-trace.test.js`, `routing-cost.test.js`
Graph	`pathfinding-graph-service.test.js`, `pathfinding-controller.test.js`, `binary-graph-.test.js`, `graph-slice-.test.js`
WASM	`route-kernel-*.test.js`, `path-worker-binary.test.js`, `benchmark-routing-wasm-fixtures.test.js`
Startup	`bootstrap-.test.js`, `startup-.test.js`, `cached-mvf-loader.test.js`
Outdoor	`outdoor-routing.test.js`, `unified-outdoor-route.test.js`, `outdoor-drop-route.test.js`
UI	`ui-manager-.test.js`, `search-box-.test.js`, `layer-manager-*.test.js`, `legend-toggle-manager.test.js`
Mobile	`native-controls-layout.test.js`, `mobile-route-sheet.test.js`, `theme-host-mode.test.js`
Integration	`integration-realmap.test.js`, `zip-node-builder.test.js`
Performance	`perf-budget.test.js`, `performance-routing.test.js`, `build-analysis.test.js`

Data Files

Path	Purpose
`assets/my_data.zip`	MVF bundle (runtime)
`assets/routing/graph.json`	Legacy routing graph
`assets/routing/graph.*.bin`	Binary graph slices
`assets/*_nodes.geojson`	Debug visualization nodes
`assets/walkable_areas.geojson`	Walkable polygon debug overlay
`temp_mvf/`	Source MVF data for build scripts

continue:[[]]
before:[[]]