# bahuckel/edexo-compare architecture

> Architecture diagram of the GitHub repository bahuckel/edexo-compare, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bahuckel/edexo-compare
- Repository: https://github.com/bahuckel/edexo-compare

## Overview

EDEXO-Compare is a journal-linked Elite Dangerous exobiology companion. Its main workflow watches and merges local game journals, builds a view of the commander’s visited systems, predicts candidate species and payouts for biological signals, and presents the result in the desktop browser UI. Separate capabilities include post-DSS species matching, first-footfall and discovery tracking, maps and an encyclopedia, plus optional EDSM lookup and Canonn uploads. The README documents these capabilities; some wiring below is based on that documentation because the sampled source excerpts do not show every subsystem’s implementation.

Main entry points: [`src/server/snapshot.ts`](https://github.com/bahuckel/edexo-compare/blob/main/src/server/snapshot.ts) (App snapshot), [`src/server/httpServer.ts`](https://github.com/bahuckel/edexo-compare/blob/main/src/server/httpServer.ts) (HTTP and WebSocket server), [`src/server/journalWatcher.ts`](https://github.com/bahuckel/edexo-compare/blob/main/src/server/journalWatcher.ts) (Journal watcher), [`src/feeder/pipeline.ts`](https://github.com/bahuckel/edexo-compare/blob/main/src/feeder/pipeline.ts) (Species data feeder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User views"]
  node_app["Main companion UI<br/>[App.tsx]"]
  node_second["Triage screen<br/>[SecondScreen.tsx]"]
end

subgraph group_journal["Journal processing"]
  node_journalwatcher["Journal watcher<br/>[journalWatcher.ts]"]
  node_mergecache["Journal merge cache"]
  node_snapshot["App snapshot<br/>[snapshot.ts]"]
  node_server["HTTP and WebSocket server<br/>[httpServer.ts]"]
end

subgraph group_biology["Biology predictions"]
  node_matchcontext["Match context"]
  node_speciesmatch["Species matching<br/>[matchSpecies.ts]"]
  node_likelihood["Species likelihood"]
  node_payout["Payout estimates"]
  node_exotracker["Organic tracking"]
  node_encyclopedia["Species encyclopedia"]
  node_feeder["Species data feeder<br/>[pipeline.ts]"]
  node_feederdb[("Feeder SQLite store<br/>[feederDb.ts]")]
end

subgraph group_galaxy["Galaxy and discovery"]
  node_galaxymap["Galaxy sector map"]
  node_systemmap["System map<br/>[systemMap.ts]"]
  node_discoveries["Discovery tracking<br/>[discoveries.ts]"]
end

subgraph group_integrations["External services"]
  node_edsmautofetch["EDSM system lookup<br/>[edsmAutoFetch.ts]"]
  node_canonnupload["Canonn uploads<br/>[canonnUpload.ts]"]
end

node_commander(("Commander"))
node_journalfiles["Game journals"]
node_edsm(("EDSM"))
node_canonn(("Canonn archive"))

node_commander -->|"generates events"| node_journalfiles
node_journalfiles -->|"reads updates"| node_journalwatcher
node_journalwatcher -->|"merges journals"| node_mergecache
node_mergecache -->|"provides state"| node_snapshot
node_snapshot -->|"serves snapshot"| node_server
node_server -->|"updates view"| node_app
node_server -->|"updates view"| node_second
node_server -->|"serves map data"| node_galaxymap
node_commander -->|"views results"| node_app
node_matchcontext -->|"provides context"| node_speciesmatch
node_speciesmatch -->|"scores candidates"| node_likelihood
node_snapshot -->|"builds context"| node_matchcontext
node_snapshot -->|"estimates value"| node_payout
node_snapshot -->|"tracks scans"| node_exotracker
node_snapshot -->|"tracks discoveries"| node_discoveries
node_snapshot -->|"provides system state"| node_systemmap
node_edsmautofetch -.->|"looks up systems"| node_edsm
node_snapshot -.->|"requests lookup"| node_edsmautofetch
node_canonnupload -.->|"sends live events"| node_canonn
node_journalwatcher -.->|"dispatches events"| node_canonnupload
node_commander -->|"runs data import"| node_feeder
node_feeder -.->|"fetches occurrences"| node_edsm
node_feeder -->|"installs profiles"| node_feederdb
node_encyclopedia -->|"supplies reference"| node_app

click node_journalwatcher "https://github.com/bahuckel/edexo-compare/blob/main/src/server/journalWatcher.ts"
click node_mergecache "https://github.com/bahuckel/edexo-compare/blob/main/src/server/journalMergeCache.ts"
click node_snapshot "https://github.com/bahuckel/edexo-compare/blob/main/src/server/snapshot.ts"
click node_matchcontext "https://github.com/bahuckel/edexo-compare/blob/main/src/server/speciesMatchContext.ts"
click node_speciesmatch "https://github.com/bahuckel/edexo-compare/blob/main/src/server/matchSpecies.ts"
click node_likelihood "https://github.com/bahuckel/edexo-compare/blob/main/src/server/speciesLikelihood.ts"
click node_payout "https://github.com/bahuckel/edexo-compare/blob/main/src/server/explorationPayoutHeuristic.ts"
click node_exotracker "https://github.com/bahuckel/edexo-compare/blob/main/src/server/exoOrganicTracker.ts"
click node_server "https://github.com/bahuckel/edexo-compare/blob/main/src/server/httpServer.ts"
click node_app "https://github.com/bahuckel/edexo-compare/blob/main/src/client/App.tsx"
click node_second "https://github.com/bahuckel/edexo-compare/blob/main/src/client/SecondScreen.tsx"
click node_galaxymap "https://github.com/bahuckel/edexo-compare/blob/main/src/client/GalaxyMapScreen.tsx"
click node_systemmap "https://github.com/bahuckel/edexo-compare/blob/main/src/server/systemMap.ts"
click node_discoveries "https://github.com/bahuckel/edexo-compare/blob/main/src/server/discoveries.ts"
click node_encyclopedia "https://github.com/bahuckel/edexo-compare/blob/main/src/server/exomasteryEdsmEncyclopedia.ts"
click node_edsmautofetch "https://github.com/bahuckel/edexo-compare/blob/main/src/server/edsmAutoFetch.ts"
click node_canonnupload "https://github.com/bahuckel/edexo-compare/blob/main/src/server/canonnUpload.ts"
click node_feeder "https://github.com/bahuckel/edexo-compare/blob/main/src/feeder/pipeline.ts"
click node_feederdb "https://github.com/bahuckel/edexo-compare/blob/main/src/feeder/feederDb.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_second toneBlue
class node_journalwatcher,node_mergecache,node_snapshot,node_server toneAmber
class node_matchcontext,node_speciesmatch,node_likelihood,node_payout,node_exotracker,node_encyclopedia,node_feeder,node_feederdb toneMint
class node_galaxymap,node_systemmap,node_discoveries toneRose
class node_edsmautofetch,node_canonnupload,node_commander,node_journalfiles,node_edsm,node_canonn toneIndigo
```

## Components

### User views

- [Main companion UI](https://github.com/bahuckel/edexo-compare/blob/main/src/client/App.tsx): `src/client/App.tsx`
- [Triage screen](https://github.com/bahuckel/edexo-compare/blob/main/src/client/SecondScreen.tsx): `src/client/SecondScreen.tsx`

### Journal processing

- [Journal watcher](https://github.com/bahuckel/edexo-compare/blob/main/src/server/journalWatcher.ts): `src/server/journalWatcher.ts`
- [Journal merge cache](https://github.com/bahuckel/edexo-compare/blob/main/src/server/journalMergeCache.ts): `src/server/journalMergeCache.ts`
- [App snapshot](https://github.com/bahuckel/edexo-compare/blob/main/src/server/snapshot.ts): `src/server/snapshot.ts`
- [HTTP and WebSocket server](https://github.com/bahuckel/edexo-compare/blob/main/src/server/httpServer.ts): `src/server/httpServer.ts`

### Biology predictions

- [Match context](https://github.com/bahuckel/edexo-compare/blob/main/src/server/speciesMatchContext.ts): `src/server/speciesMatchContext.ts`
- [Species matching](https://github.com/bahuckel/edexo-compare/blob/main/src/server/matchSpecies.ts): `src/server/matchSpecies.ts`
- [Species likelihood](https://github.com/bahuckel/edexo-compare/blob/main/src/server/speciesLikelihood.ts): `src/server/speciesLikelihood.ts`
- [Payout estimates](https://github.com/bahuckel/edexo-compare/blob/main/src/server/explorationPayoutHeuristic.ts): `src/server/explorationPayoutHeuristic.ts`
- [Organic tracking](https://github.com/bahuckel/edexo-compare/blob/main/src/server/exoOrganicTracker.ts): `src/server/exoOrganicTracker.ts`
- [Species encyclopedia](https://github.com/bahuckel/edexo-compare/blob/main/src/server/exomasteryEdsmEncyclopedia.ts): `src/server/exomasteryEdsmEncyclopedia.ts`
- [Species data feeder](https://github.com/bahuckel/edexo-compare/blob/main/src/feeder/pipeline.ts): `src/feeder/pipeline.ts`
- [Feeder SQLite store](https://github.com/bahuckel/edexo-compare/blob/main/src/feeder/feederDb.ts): `src/feeder/feederDb.ts`

### Galaxy and discovery

- [Galaxy sector map](https://github.com/bahuckel/edexo-compare/blob/main/src/client/GalaxyMapScreen.tsx): `src/client/GalaxyMapScreen.tsx`
- [System map](https://github.com/bahuckel/edexo-compare/blob/main/src/server/systemMap.ts): `src/server/systemMap.ts`
- [Discovery tracking](https://github.com/bahuckel/edexo-compare/blob/main/src/server/discoveries.ts): `src/server/discoveries.ts`

### External services

- [EDSM system lookup](https://github.com/bahuckel/edexo-compare/blob/main/src/server/edsmAutoFetch.ts): `src/server/edsmAutoFetch.ts`
- [Canonn uploads](https://github.com/bahuckel/edexo-compare/blob/main/src/server/canonnUpload.ts): `src/server/canonnUpload.ts`

### Other components

- **Commander**
- **Game journals**
- **EDSM**
- **Canonn archive**

## Connections

- Commander → Game journals: generates events
- Game journals → Journal watcher: reads updates
- Journal watcher → Journal merge cache: merges journals
- Journal merge cache → App snapshot: provides state
- App snapshot → HTTP and WebSocket server: serves snapshot
- HTTP and WebSocket server → Main companion UI: updates view
- HTTP and WebSocket server → Triage screen: updates view
- HTTP and WebSocket server → Galaxy sector map: serves map data
- Commander → Main companion UI: views results
- Match context → Species matching: provides context
- Species matching → Species likelihood: scores candidates
- App snapshot → Match context: builds context
- App snapshot → Payout estimates: estimates value
- App snapshot → Organic tracking: tracks scans
- App snapshot → Discovery tracking: tracks discoveries
- App snapshot → System map: provides system state
- EDSM system lookup → EDSM: looks up systems
- App snapshot → EDSM system lookup: requests lookup
- Canonn uploads → Canonn archive: sends live events
- Journal watcher → Canonn uploads: dispatches events
- Commander → Species data feeder: runs data import
- Species data feeder → EDSM: fetches occurrences
- Species data feeder → Feeder SQLite store: installs profiles
- Species encyclopedia → Main companion UI: supplies reference