"/home/yossef/notes/git/projects/maplibra/flows/Startup Sequence.md"

path: maplibra/flows/Startup Sequence.md

- **fileName**: Startup Sequence
- **Created on**: 2026-06-16 00:48:42

Startup Sequence

Purpose: Full app initialization from URL parameter, file upload, cache, or asset root.

Related: ../Home.md, ../Architecture.md, ../modules/Bootstrap System.md, ../modules/MVF Loading.md, ../modules/Asset System.md

Startup Modes

The app can start from four sources, resolved by src/app/startup-source.js:

1. URL (?mvf=...) — Load MVF from a URL
2. File Upload — User drops a ZIP file
3. Cache — Restore last used map from IndexedDB
4. Asset Root (/assets) — Load pre-bundled server assets
5. Offline Package — Prepackaged offline map

Startup Flow

Phase 1: Shell (immediate)

• bootstrapShell() — theme, error handler, toast, viewport, service worker
• App context created with createAppContext()
• script.js sets up the drop screen, settings menu, event listeners

Phase 2: MVF Load (blocking)

• Parse URL parameters, resolve startup source
• Load MVF bundle (ZIP parse in Web Worker or cache restore)
• Extract manifest, floors, styles, locations, connections
• Build asset provider (ZIP, network, or hybrid)

Phase 3: Derived Assets (async, can defer)

• Check IndexedDB cache for pre-built routing graphs
• If missing, build derived assets after map shell is ready
• resolveInitialDerivedAssets() chooses cached vs bundled
• prepareStartupRoutingAssets() builds missing graphs

Phase 4: Map Creation (blocking)

• bootstrapMap() creates Mapbox GL instance
• LayerManager created with theme colors
• Map jumps to building center
• bootstrapData() runs initApp()

Phase 5: First Floor Render (blocking)

• floorDataManager.prepareFloor(initialFloorId)
• loadAndRenderFloor() with fast render
• LayerManager.addBuildingShell()
• Loading overlay removed

Phase 6: UI Initialization (post-render)

• UIManager.init() — floor controls, zoom listener, locate me
• SearchBox initialized lazily
• PathfindingController initialized lazily (deferred)
• Debug layers initialized lazily (if ?debug=1)

Phase 7: Post-Render Tasks (idle)

• scheduleStartupTask() queues low-priority work:
  • Annotation loading for current floor
  • Connector landmark loading
  • Address lookup
  • Floor cache prewarm
  • Adjacent floor prefetch
  • Building floor warm (all floors)

Phase 8: Performance Reporting

• time-to-first-render and time-to-first-idle measured
• Startup perf summary logged and sent to telemetry

Performance Timing

Key performance marks:

• mvf-load-start → mvf-load-ready — ZIP parsing time
• map-created → map-style-ready — Map style load time
• floor-render-start → floor-rendered — First floor render time
• mvf-load-start → floor-rendered — Total time-to-first-render
• floor-rendered → map-idle-first — Time to first idle

Important Files

• script.js — Main startup orchestrator
• src/bootstrap/bootstrap-shell.js
• src/bootstrap/bootstrap-map.js
• src/bootstrap/bootstrap-data.js
• src/app/startup-source.js — Resolve startup mode from URL
• src/app/startup-task-queue.js — Deferred task scheduling
• src/app/startup-routing-assets.js — Build missing routing assets
• src/app/startup-derived-assets.js — Select cached vs bundled assets

How It Connects

• script.js is the single entry point; everything else is imported from it

• Bootstrap stages are sequential but some are async (MVF load, map idle)

• Deferred features (routing, search, debug) are only loaded when needed or after idle

• appContext is the shared state container passed between stages

• window.InGuide is the global debug API exposed after all stages complete

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