Repository inventory (EDOS workspace)¶

Audience: Agent + operator

Paths are relative to the workspace root (edos/). This file is the Phase 1 map: what exists, how to run it, and how projects relate. For the doc index, see README.md. For production hostnames and ed* slugs, see HOSTNAMES.md. For behavior and data flow, see ARCHITECTURE.md and IPC.md. For hosted-web URL bootstrap and integration manifests, see HOSTED_APP_CONTRACT.md. For optional federated app discovery (composition hosts), see APP_DISCOVERY_REGISTRY.md. For conventions and scope, see DOC_CONVENTIONS.md and SCOPE.md.

Partial workspace checkouts¶

Your edos/ folder may contain only some projects, or only part of a project tree (sparse checkout, uninitialized submodule, meta-repo without every app cloned). Missing files locally are expected — they are not listed as gaps in TODO.md for that reason alone.

Deploy and CI (docker-compose.yaml, Dockerfile, .gitlab-ci.yml) live in each app repository when fully cloned. Docs may name production hosts (e.g. edpa.howfe.org) from project READMEs; confirm Traefik labels and images in that app’s compose file when you have the full repo.
Source paths cited in IPC.md or capsules may be absent in a thin checkout — clone or open the full app repo before grepping.
Git-only placeholders (folder contains mostly .git) — see Git-only placeholders below; clone the app to document stack and deploy.

Normative wording for agents: DOC_CONVENTIONS.md — Partial workspace checkouts.

Quick reference¶

Folder	Kind	Primary stack	Run / build (where known)
`elite-dangerous-event-types`	Shared library	TypeScript types	TODO: Verify — no build script in `package.json`; consumed as source / published package
`inter-frame-messenger`	Shared library	TypeScript (`tsup`)	`npm run build` in `inter-frame-messenger/`
`stellar-forge-helper`	Shared library	TypeScript (`tsup`) — id64 / boxel addressing	`npm run build` / `npm test` in `stellar-forge-helper/`
`api-cache-server`	HTTP service	Bun + Elysia	`bun run dev` / `bun run start` in `api-cache-server/api/`
`elite-dangerous-planet-analyser`	HTTP service	Bun + Elysia	`bun run dev` / `bun run start` / `bun test` in `elite-dangerous-planet-analyser/api/`; deploy `https://edpa.howfe.org` (Traefik — `README.md` + `docker-compose.yaml` in app repo). Capsule: apps/elite-dangerous-planet-analyser.md.
`elite-dangerous-surface-map`	Web UI	Quasar (Vue 3) + Vite	`npm run dev` / `npm run build` in `elite-dangerous-surface-map/ui/`; deploy `https://edam.howfe.org`. Capsule: apps/elite-dangerous-surface-map.md.
`elite-dangerous-remote-journal-reader`	Web UI	Quasar (Vue 3) + Vite	`npm run dev` / `npm run build` in `elite-dangerous-remote-journal-reader/ui/`
`elite-dangerous-local-journal-reader`	Desktop shell (Tauri) + embedded web	Rust (Tauri 2) + TypeScript (`src/`, `build-service/`)	`npm run tauri:dev` / `npm run tauri:build` in `elite-dangerous-local-journal-reader/`; `npm run build-service:dev` for the optional build helper
`elite-dangerous-journal-event-viewer`	Hosted journal / event viewer (EDJEV)	Vite + Solid + TypeScript (`src/`)	`npm run dev` / `npm run build` in `elite-dangerous-journal-event-viewer/`; deploy `https://edjev.howfe.org`. Desktop: URL-wired `.exe` from `elite-dangerous-local-journal-reader` `build-service/`, not a second Tauri app here. Capsule: apps/elite-dangerous-journal-event-viewer.md.
`elite-dangerous-stellar-scan`	Hosted stellar body table (Stellar Scan)	Vite + Solid + TypeScript in `src/`	`npm run dev` / `npm run build` in `elite-dangerous-stellar-scan/`; deploy `https://edss.howfe.org`. Capsule: apps/elite-dangerous-stellar-scan.md.
`elite-dangerous-credit-account`	Hosted credit ledger (Credit Account)	Vite + Solid + TypeScript in `src/`	`npm run dev` / `npm run build` / `npm test` in `elite-dangerous-credit-account/`; deploy `https://edca.howfe.org`. Capsule: apps/elite-dangerous-credit-account.md.
`elite-dangerous-interstellar-scan`	Hosted web app	TODO: Verify stack in a full clone	Deploy `https://edis.howfe.org`; folder may hold only `.git` until cloned — apps/elite-dangerous-interstellar-scan.md.
`elite-dangerous-systems-uninhabitet`	Hosted web app	Vite + Solid + TypeScript	`npm run dev` / `npm run build` in `elite-dangerous-systems-uninhabitet/`; deploy `https://edsu.howfe.org`. Capsule: apps/elite-dangerous-systems-uninhabitet.md.
`elite-dangerous-expedition-planner`	Hosted route-progress web app	Vite + Solid + TypeScript	`npm run dev` / `npm run build` in `elite-dangerous-expedition-planner/`; deploy `https://edep.howfe.org`. Capsule: apps/elite-dangerous-expedition-planner.md.
`elite-dangerous-universe-map`	Hosted web app (separate repo)	TODO: Verify	May be `.git` only in this workspace — apps/elite-dangerous-universe-map.md.
`elite-dangerous-orrery-map`	Hosted web app (separate repo)	TODO: Verify	May be `.git` only — apps/elite-dangerous-orrery-map.md.
`elite-dangerous-living-interior`	Hosted web app (separate repo)	TODO: Verify	May be `.git` only — apps/elite-dangerous-living-interior.md.
`elite-dangerous-planet-scan`	Hosted web app (separate repo)	TODO: Verify	May be `.git` only — apps/elite-dangerous-planet-scan.md.
`elite-dangerous-app-composition`	Hosted web app (separate repo)	TODO: Verify	May be `.git` only — apps/elite-dangerous-app-composition.md.
`docs`	Documentation	Markdown	N/A
`docs-deploy`	Static docs site pipeline	MkDocs Material + nginx + Docker	Local preview from workspace root: `mkdocs serve -f docs-deploy/mkdocs.yml` (see `docs-deploy/README.md`); production host `docs.edos.howfe.org` — DEPLOYMENT.md, capsule apps/docs-deploy.md
`journalFilesSamples`	Local fixtures (optional)	Journal `.log` + sidecar JSON	Not an app; may be absent in partial clones — not on the docs site. Agents: AGENTS.md.

Cross-project dependency (npm)¶

These dependencies are declared in the workspace copies of the apps (not necessarily identical to published semver on npm).

Consumer (workspace path)	Depends on
`elite-dangerous-surface-map/ui`	`@howfe/elite-dangerous-event-types`, `@howfe/inter-frame-messenger`, `@howfe/stellar-forge-helper`
`elite-dangerous-planet-analyser/api`	`@howfe/stellar-forge-helper`, `@howfe/elite-dangerous-event-types`
`elite-dangerous-remote-journal-reader/ui`	`@howfe/elite-dangerous-event-types`, `@howfe/inter-frame-messenger`
`inter-frame-messenger` (devDependency)	`@howfe/elite-dangerous-event-types` (used in `src/index.ts` for `EliteEvent` / `Status` helpers)
`elite-dangerous-stellar-scan`	`@howfe/elite-dangerous-event-types`, `@howfe/inter-frame-messenger`
`elite-dangerous-credit-account`	`@howfe/elite-dangerous-event-types`, `@howfe/inter-frame-messenger`
`elite-dangerous-local-journal-reader`	`@howfe/elite-dangerous-event-types` (file link in workspace `package.json`); `@tauri-apps/api` in `src/edosBridge.ts` for the shell bridge only — embedded apps must not import Tauri APIs (see `elite-dangerous-local-journal-reader/docs/bridge-contract.md`)

Runtime URLs (hardcoded in app code; not workspace-relative): see also the full registry HOSTNAMES.md.

Usage	Location
Remote journal reader popup opened by surface map	`elite-dangerous-surface-map/ui/src/composables/useJournalReader.ts` — `https://edjr.howfe.org`
Journal event viewer (EDJEV) — typical webview / compile-time default for the local bridge	`https://edjev.howfe.org` (see `elite-dangerous-local-journal-reader/README.md`, `src-tauri/capabilities/default.json` `remote.urls`)
HTTP cache proxy for third-party APIs	`elite-dangerous-surface-map/ui/src/logic/externalDataLoaders/fetchWithCache.ts` — `https://api-cache.howfe.org?url=...`
Planet analyser API (scan credits / lifeforms)	`https://edpa.howfe.org` — `elite-dangerous-planet-analyser/api/` (server-side SPANSH via `API_CACHE_BASE_URL`)
Credit Account (hosted ledger UI)	`https://edca.howfe.org` — `elite-dangerous-credit-account/` (`docker-compose.yaml` Traefik host)
Credit Account — typical `appUrl` for desktop `.exe` builds	`https://edca.howfe.org` — `VITE_DESKTOP_APP_URL` in `elite-dangerous-credit-account/README.md`
URL-wired Windows bridge build API + artifact download	`https://app.edos.howfe.org` — public deployment URL for `elite-dangerous-local-journal-reader`’s `build-service/` (same host for `POST /build` / `GET /build` and `GET /artifacts/<file>`; append `artifactDownloadPath` from the API). See `elite-dangerous-local-journal-reader/docs/build-service.md`.

Why edjev vs app.edos: https://edjev.howfe.org is a hosted web app (EDJEV UI) used as the default appUrl inside the Tauri webview in current defaults — per-product, like edjr. https://app.edos.howfe.org is not another journal UI; it is where the local journal reader project’s server (build-service) is deployed. “Download desktop” / /build links in any EDOS web app should target that host because the wired .exe is produced there, not on each app’s own origin.

Changing these URLs affects integration with deployed services; local dev may need hosts overrides or env-based URLs (TODO: Verify if you add configuration).

`elite-dangerous-event-types`¶

Role: Type definitions for Elite Dangerous journal JSON lines (EliteEvent, Status, guards like isEliteEvent, bio enums, etc.).

Package name: @howfe/elite-dangerous-event-types (see elite-dangerous-event-types/package.json).

Entry / scripts: package.json has main: index.ts and only a placeholder test script — TODO: Verify publish/build pipeline (GitLab registry, etc.) outside this workspace.

Relations: Consumed by inter-frame-messenger, local journal bridge (edosBridge.ts), both Quasar apps, and any other TS client that types journal / sidecar payloads.

`stellar-forge-helper`¶

Role: Shared id64 / boxel addressing for Elite Dangerous (StellarForgeSystem, createBodyAddress, extractSystemAddress). Not Frontier’s Stellar Forge engine.

Package name: @howfe/stellar-forge-helper.

Run locally: npm run build / npm test in stellar-forge-helper/.

Relations: elite-dangerous-planet-analyser, elite-dangerous-surface-map/ui. Capsule: apps/stellar-forge-helper.md.

`inter-frame-messenger`¶

Role: InterFrameMessenger class wrapping window.postMessage between a Window target (e.g. popup) and the embedding page. Declares MessageTypeEnum (e.g. EliteEvent, Status, EdosFileEvent, journal poll/open/stop commands) and validates payloads with @howfe/elite-dangerous-event-types.

Stack: TypeScript, tsup → dist/ (package.json).

Run locally: npm run build in inter-frame-messenger/.

Relations: Required by both Quasar apps. TODO: Verify exact message contracts in a dedicated IPC section of ARCHITECTURE.md (Phase 2).

Source anchor: inter-frame-messenger/src/index.ts.

`api-cache-server`¶

Role: Generic HTTP GET/POST proxy with in-memory cache and a request queue — forwards to a target URL from the url query parameter. Implements caching in api-cache-server/api/src/app.ts (uses ./cache.ts, ./queue.ts). Apps must use this (or an equivalent) for community third-party APIs (SPANSH, EDSM, etc.): those services are volunteer-run and usually lack DDoS protection; the cache is the fair-use layer. Not journal-specific.

Stack: Bun, Elysia, @elysiajs/cors. Prisma client scaffold exists under api-cache-server/api/src/prisma/ but is not imported from app.ts in the current tree — TODO: Verify whether persistence is planned or leftover boilerplate.

Run locally: From api-cache-server/api/: bun run dev (watch) or bun run start → src/app.ts.

Relations: elite-dangerous-surface-map calls the deployed instance https://api-cache.howfe.org via fetchWithCache.ts — not a filesystem path to this repo.

Deployment: api-cache-server/Dockerfile, docker-compose.yml at repo root (TODO: Verify compose services vs production).

`elite-dangerous-surface-map`¶

Workspace checkout note: A partial clone may contain only a subset of ui/src/ (e.g. stellar-forge components without composables/useJournalReader.ts). Open the full elite-dangerous-surface-map repository before grepping journal/IPC paths cited in IPC.md or apps/elite-dangerous-surface-map.md.

Role: Surface map web app: OpenGlobus-based map, commander/journal-driven state, loaders for SPANSH/EDSM (via cached fetch), integration with remote journal reader popup for live EliteEvent / Status streams.

Stack: Quasar 2, Vue 3, TypeScript (elite-dangerous-surface-map/ui/).

Run / build: npm run dev / npm run build in elite-dangerous-surface-map/ui/.

Relations:

NPM: @howfe/elite-dangerous-event-types, @howfe/inter-frame-messenger.
Opens https://edjr.howfe.org and instantiates InterFrameMessenger toward that origin (useJournalReader.ts).
External game data: fetchWithCache → api-cache.howfe.org → upstream URLs (SPANSH, EDSM, etc. in logic/externalDataLoaders/).

`elite-dangerous-remote-journal-reader`¶

Workspace checkout note: The ui/ tree may be empty or incomplete in this meta-repo until the app repository is cloned. IPC behavior described in IPC.md matches the full elite-dangerous-remote-journal-reader repo (JournalWatcher.ts, StatusWatcher.ts, watch buttons).

Role: Quasar web UI that reads the player’s local journal file via the browser File System Access API (JournalWatcher in ui/src/JournalWatcher.ts), parses lines into elite events, and sends EliteEvent / Status to the parent/opener via InterFrameMessenger (sendEliteEvent, sendStatusEvent). Despite the name, “remote” here matches deployment (hosted web app, e.g. Docker/Traefik in docker-compose.yaml) rather than server-side journal storage.

Stack: Quasar 2, Vue 3, @vueuse/core (useFileSystemAccess), @howfe/inter-frame-messenger, @howfe/elite-dangerous-event-types.

Run / build: npm run dev / npm run build in elite-dangerous-remote-journal-reader/ui/.

Relations: Parent windows (e.g. surface map) listen for postMessage traffic; origin allowlists are configured in the consumer (e.g. useJournalReader.ts).

Deployment note: docker-compose.yaml references image registry.gitlab.com/elite-dangerous1/elite-dangerous-remote-journal-reader and host edjr.howfe.org.

`elite-dangerous-local-journal-reader`¶

Role: Desktop host that watches Elite Dangerous journal and sidecar JSON under the player’s install, emits BridgeEnvelope on Tauri IPC channel edos:file:event, and injects a small bridge so the embedded web UI receives IFM-shaped edos-file-event (plus legacy elite-event / elite-status) via postMessage / CustomEvent — see elite-dangerous-local-journal-reader/docs/bridge-contract.md and src/edosBridge.ts.

Stack: Tauri 2 (src-tauri/), shared types from @howfe/elite-dangerous-event-types, optional build-service/ (Node) for packaging workflows documented in elite-dangerous-local-journal-reader/docs/build-service.md.

Run locally: From elite-dangerous-local-journal-reader/: npm run tauri:dev (desktop + webview) or npm run tauri:build. Optional: npm run build-service:dev / npm test for the build helper.

Relations: Complements the hosted remote journal reader: remote reader uses the File System Access API in a browser popup; the local reader is a native shell for the same EliteEvent / Status / envelope contracts when you need filesystem access without a public URL. The webview loads a configurable HTTPS appUrl (CLI → EDOS_APP_URL → PE-tail splice from build-service/ → compile-time default, currently https://edjev.howfe.org — see README.md). To ship a desktop user a build that opens another deployed UI, pass that canonical URL to POST /build / GET /build (see docs/build-service.md); artifact filenames look like elite-dangerous-local-journal-reader-<version>-<prefix>.exe.

Source anchors: src-tauri/src/bridge.rs (constants EVENT_NAME, ELITE_EVENT, ELITE_STATUS), src/edosBridge.ts.

`elite-dangerous-stellar-scan`¶

Role: Stellar Scan — per-system table of bodies/signals from journal events + SPANSH dump (via api-cache). Listens for IFM traffic on window (useJournalConnection.ts: EliteEvent, Status, EdosFileEvent); opens EDJR in a popup when not embedded.

Run locally: npm run dev / npm run build in elite-dangerous-stellar-scan/.

Capsule: apps/elite-dangerous-stellar-scan.md.

`elite-dangerous-credit-account`¶

Role: Credit Account — commander credit ledger from journal events (income, expenses, crew wages, table views, balance graph, local persistence).

Stack: Vite + Solid + TypeScript; @howfe/elite-dangerous-event-types, @howfe/inter-frame-messenger.

Run locally: npm run dev / npm run build / npm test in elite-dangerous-credit-account/.

Deploy: https://edca.howfe.org — docker-compose.yaml at app repo root.

Relations: Same IFM-on-window pattern as Stellar Scan (useJournalConnection.ts); opens EDJR popup when not embedded; desktop install via build-service at https://app.edos.howfe.org.

Capsule: apps/elite-dangerous-credit-account.md.

`elite-dangerous-planet-analyser`¶

Role: Headless HTTP API — exploration scan credit breakdown and optional exobiology prediction for a body (POST /v1/analyze). SPANSH lookups go through API_CACHE_BASE_URL (default https://api-cache.howfe.org).

Run locally: bun run dev / bun test in elite-dangerous-planet-analyser/api/.

Deploy: https://edpa.howfe.org — elite-dangerous-planet-analyser/README.md and docker-compose.yaml at app repo root.

Capsule: apps/elite-dangerous-planet-analyser.md.

Git-only placeholders (separate repositories)¶

These top-level folders may contain only .git (and CURSOR_AGENT_BOOTSTRAP.md) until you clone the app repo into the workspace. Each has a capsule under apps/ with checkout notes; stack and deploy URLs are TODO: Verify in a full clone.

Folder	Capsule
`elite-dangerous-interstellar-scan`	apps/elite-dangerous-interstellar-scan.md
`elite-dangerous-universe-map`	apps/elite-dangerous-universe-map.md
`elite-dangerous-orrery-map`	apps/elite-dangerous-orrery-map.md
`elite-dangerous-living-interior`	apps/elite-dangerous-living-interior.md
`elite-dangerous-planet-scan`	apps/elite-dangerous-planet-scan.md
`elite-dangerous-app-composition`	apps/elite-dangerous-app-composition.md
`elite-dangerous-universe-places`	apps/elite-dangerous-universe-places.md
`elite-dangerous-systems-uninhabitet`	apps/elite-dangerous-systems-uninhabitet.md

`elite-dangerous-expedition-planner`¶

Role: Hosted web app for planning and tracking an ordered list of systems to visit. The first version is manual/client-only: add or paste systems, mark route stops visited, reorder or remove stops, and keep the next unvisited system visible.

Stack: Vite + Solid + TypeScript.

Run locally: npm run dev / npm run build in elite-dangerous-expedition-planner/.

Data/storage: commander-provided route names in browser localStorage; no journal ingestion and no community HTTP APIs in the initial scaffold.

Deployment: https://edep.howfe.org via the app repo's .gitlab-ci.yml, Dockerfile, and docker-compose.yml. /.well-known/edos-integration.json is TODO: Verify once hosted app bootstrap or embed modes are added. Capsule: apps/elite-dangerous-expedition-planner.md.

`elite-dangerous-journal-event-viewer`¶

Role: EDJEV — hosted web application for browsing journal-derived data (separate Git repository; often deployed at https://edjev.howfe.org). It is a consumer of the same bridge / postMessage story as other EDOS web apps when loaded inside the local journal reader webview (IFM-shaped edos-file-event, etc. — see IPC.md).

Stack: Vite + Solid + TypeScript; depends on @howfe/elite-dangerous-event-types and @howfe/inter-frame-messenger (package.json). Ingests elite-event, elite-status, and edos-file-event on window — see project README.md.

Run locally: npm run dev / npm run build in elite-dangerous-journal-event-viewer/.

Desktop distribution: Do not add Tauri here. Windows installers with an embedded appUrl are produced by elite-dangerous-local-journal-reader’s build-service/, deployed at https://app.edos.howfe.org (docs/build-service.md). The EDJEV static site points “download desktop bridge” / /build at that host — see project README.md for env vars.

Embedded layout: URL bootstrap uses edosEmbedded / mode=embedded (and related keys) — see src/App.tsx and project README.md.

Capsule: apps/elite-dangerous-journal-event-viewer.md.

`docs`¶

Role: Workspace documentation (this file, SCOPE.md, DOC_CONVENTIONS.md, original-concept.md).

`docs-deploy`¶

Role: Static documentation site pipeline (MkDocs Material + nginx). Dockerfile + Compose + docs-deploy/mkdocs.yml mirror production at docs.edos.howfe.org. Build and SSH deploy jobs live in repository root .gitlab-ci.yml (:docs image tag).

Capsule: apps/docs-deploy.md.

Data flow (ecosystem)¶

High-level runtime relationships (deployed hostnames match current code; adjust if you self-host).

flowchart TB subgraph disk["Player machine"] JF["Journal .log file"] LJR["elite-dangerous-local-journal-reader\n(Tauri shell + webview)"] end subgraph npm["Shared npm libraries"] ET["@howfe/elite-dangerous-event-types"] IFM["@howfe/inter-frame-messenger"] end IFM --> ET subgraph hosted["Typical deployed services"] EDJR["elite-dangerous-remote-journal-reader\n(edjr.howfe.org)"] EDJEV["elite-dangerous-journal-event-viewer\n(edjev.howfe.org)"] EDSS["elite-dangerous-stellar-scan\n(edss.howfe.org)"] ACS["api-cache-server\n(api-cache.howfe.org)"] end subgraph ext["Third-party HTTP APIs"] API["e.g. SPANSH, EDSM"] end SM["elite-dangerous-surface-map UI"] SS["elite-dangerous-stellar-scan UI"] JF -->|"File System Access API\n(JournalWatcher)"| EDJR JF -->|"filesystem watch\n(journal + sidecars)"| LJR LJR -->|"HTTPS webview\n(default appUrl → EDJEV)"| EDJEV EDJEV --> IFM EDJEV --> ET EDJR -->|"postMessage\nEliteEvent / Status"| SM EDJR -->|"postMessage\n(IFM on window)"| SS SM -->|"window.open + InterFrameMessenger"| EDJR SS -->|"window.open (non-embedded)"| EDJR SM -->|"fetchWithCache"| ACS SS -->|"fetchWithCache / SPANSH"| ACS ACS -->|"proxied fetch + cache"| API SM --> ET SS --> ET EDJR --> IFM SM --> IFM SS --> IFM

npm-only dependency graph (workspace packages)¶

Libraries and apps as declared dependencies (no disk/runtime):

flowchart LR ET["elite-dangerous-event-types"] IFM["inter-frame-messenger"] SM["surface-map UI"] RJR["remote-journal-reader UI"] LJR["local-journal-reader"] IFM --> ET SM --> ET SM --> IFM RJR --> ET RJR --> IFM LJR --> ET

Gaps for later phases¶

Topic	Suggested follow-up
Full IPC contract (message shapes, origins)	Phase 2 — ARCHITECTURE.md + cross-check `inter-frame-messenger/src/index.ts` and Quasar `InterFrameMessenger` usage
`elite-dangerous-journal-event-viewer` source in this workspace	Optional: clone or init submodule so agents can grep EDJEV — capsule apps/elite-dangerous-journal-event-viewer.md and ARCHITECTURE.md already describe runtime role
Prisma in `api-cache-server`	Confirm whether `src/prisma/` should be wired into Elysia routes or removed
Configurable URLs for edjr / api-cache	Search `howfe.org` in UIs; consider env-based base URLs

Repository inventory (EDOS workspace)¶

Partial workspace checkouts¶

Quick reference¶

Cross-project dependency (npm)¶

elite-dangerous-event-types¶

stellar-forge-helper¶

inter-frame-messenger¶

api-cache-server¶

elite-dangerous-surface-map¶

elite-dangerous-remote-journal-reader¶

elite-dangerous-local-journal-reader¶

elite-dangerous-stellar-scan¶

elite-dangerous-credit-account¶

elite-dangerous-planet-analyser¶