Skip to content

elite-dangerous-surface-map

Audience: Agent

Workspace checkout note

The edos/elite-dangerous-surface-map/ folder in this meta-repo may contain only part of ui/src/ (for example stellar-forge components without composables/useJournalReader.ts). That does not mean the app is absent — clone or populate the full elite-dangerous-surface-map repository before changing journal/IPC code. See REPOS.md.

Purpose

3D surface map for Elite Dangerous bodies using OpenGlobus, with commander state, journal-driven galaxy/body updates (via popup journal reader), and external data (SPANSH, EDSM, etc.) through the shared API cache proxy.

Tech stack

  • UI: Quasar 2, Vue 3, TypeScript (ui/)
  • Scripts: npm run dev / npm run build in elite-dangerous-surface-map/ui/
  • Docker: repository root has docker-compose.yaml (see DEPLOYMENT.md).

Deploy

Item Value
Production host https://edam.howfe.org
Compose service edam
Desktop installer name edam.exe (via build-service)

Slug registry: HOSTNAMES.md.

Key dependencies

Package Role
@howfe/elite-dangerous-event-types Journal/status typing and guards
@howfe/inter-frame-messenger Listen for events from journal reader popup
@openglobus/og Globe / map
axios HTTP (some loaders)

Integration points

Concern Location (under ui/src/)
Open journal popup + subscribe composables/useJournalReader.ts — https://edjr.howfe.org
Feed journal into map / stores logic/readGalaxyDataFromEvents.ts — onEliteEvent
Commander / status composables/useCommanderState.ts — onStatus
Cached third-party APIs logic/externalDataLoaders/fetchWithCache.ts — https://api-cache.howfe.org (required pattern for community APIs — do not call SPANSH/EDSM/etc. directly; see ARCHITECTURE.md)
Map UI entry pages/MapPage.vue, components/surface-map/

useJournalReader is a singleton (module-level ifm + callback arrays). Multiple imports share the same instance.

Bootstrap and embedding (hosted app contract)

  • Normative contract: HOSTED_APP_CONTRACT.md (distinct from IPC.md journal messaging).
  • Embedded mode: edosEmbedded with values 1 or true, read from pre-hash location.search or from the hash query string (Vue hash router). Implementation: ui/src/composables/useEdosEmbeddedMode.ts. When set, journal-feed and desktop-install affordances align with the embedded shell story (see components/surface-map/InteractionButtons.vue, composables/useEdosDesktopBuildDownload.ts).
  • Desktop download button: ui/src/components/DesktopDownloadButton.vue calls useEdosDesktopBuildDownload.ts (POST/GET /build on https://app.edos.howfe.org). When improving the save name, use the blob + download pattern in elite-dangerous-local-journal-reader.md § Download filename (recommended product file name: edam.exe).
  • Manifest: /.well-known/edos-integration.json on the deployment origin is not published yet — tracked in TODO.md.

Extension points

  • New journal-driven behavior: register in readGalaxyDataFromEvents() with is* guards from event-types.
  • New API sources: add loaders under logic/externalDataLoaders/; use fetchWithCache for consistent caching.
  • Settings: App.vue + useSettings — keys like feed-elite-events, journal-path (URL params) may interact with features.

Pitfalls / checks

  • Hardcoded URLs in useJournalReader.ts and fetchWithCache.ts — break when self-hosting.
  • Popup blockers — window.open may be blocked; user must allow popups.
  • CORS / mixed content — map and APIs must load in a browser context compatible with your deployment.

Visual identity

Normative tokens and layout: DESIGN_GUIDANCE.md. This legacy app maps them in ui/src/css/quasar.variables.scss; new EDOS apps should follow the doc, not this Quasar stack.