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 behavior and data flow, see ARCHITECTURE.md and IPC.md. For conventions and scope, see DOC_CONVENTIONS.md and SCOPE.md.

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/`
`api-cache-server`	HTTP service	Bun + Elysia	`bun run dev` / `bun run start` in `api-cache-server/api/`
`elite-dangerous-surface-map`	Web UI	Quasar (Vue 3) + Vite	`npm run dev` / `npm run build` in `elite-dangerous-surface-map/ui/`
`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`	Missing in this checkout	—	TODO: Verify — clone or populate submodule; only `.git` present here
`docs`	Documentation	Markdown	N/A

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`
`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)

Runtime URLs (hardcoded in app code; not workspace-relative):

Usage	Location
Remote journal reader popup opened by surface map	`elite-dangerous-surface-map/ui/src/composables/useJournalReader.ts` — `https://edjr.howfe.org`
HTTP cache proxy for third-party APIs	`elite-dangerous-surface-map/ui/src/logic/externalDataLoaders/fetchWithCache.ts` — `https://api-cache.howfe.org?url=...`

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, both Quasar apps, and any other TS client that types journal payloads.

`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, 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`¶

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`¶

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`¶

State of this checkout: The directory contains only a .git tree — no application source files. TODO: Verify remote URL, submodule init, or whether this project was renamed/superseded by the remote reader flow.

`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).

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"] 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)"] 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"] JF -->|"File System Access API\n(JournalWatcher)"| EDJR EDJR -->|"postMessage\nEliteEvent / Status"| SM SM -->|"window.open + InterFrameMessenger"| EDJR SM -->|"fetchWithCache"| ACS ACS -->|"proxied fetch + cache"| API SM --> ET EDJR --> IFM SM --> 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"] IFM --> ET SM --> ET SM --> IFM RJR --> ET RJR --> IFM

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-local-journal-reader` source	Clone or init submodule; then add row to Quick reference and update diagrams
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)¶

Quick reference¶

Cross-project dependency (npm)¶

elite-dangerous-event-types¶

inter-frame-messenger¶

api-cache-server¶

elite-dangerous-surface-map¶

elite-dangerous-remote-journal-reader¶

elite-dangerous-local-journal-reader¶

docs¶

docs-deploy¶