The DeepPhe Launcher

The one executable the installer creates is the DeepPhe Launcher — a Java 26 GUI application. It is the front door to everything DeepPhe: it starts the NLP pipeline, the visualizer, and the data API, and builds the visualizer database, all from a single window.

How the launcher is defined

From the install4j project:

• Executable: DeepPhe Launcher, GUI mode, single instance, runs with the highest available privileges, working directory .DeepPhe.
• Main class: org.healthnlp.deepphe.gui.DpheDesktop
• Argument: conf/launcher.conf
• VM options:

  --add-exports=java.base/sun.nio.ch=ALL-UNNAMED
  --add-opens=java.base/java.lang=ALL-UNNAMED

• Classpath: the deepphe-desktop jar plus .DeepPhe/lib and .DeepPhe/resources.
• Icon: icons/rocket.ico / Rocket.png; a splash screen shows the version.

The Java 26 configure step removes the incompatible log4j-1.2-api-* bridge jar from .DeepPhe/lib; the legacy Log4j 1.x jar remains for cTAKES GUI classes.

Where the GUI code lives

The launcher UI (DpheDesktop) ships inside deepphe-desktop.jar, which comes from the DeepPhe application repositories — not from this installer repo. This repo packages that jar and generates the launcher.conf that drives it.

launcher.conf

launcher.conf is written into .DeepPhe/conf/ during the configure step. It is a plain key/value file that tells the launcher where each component lives and how to start/stop it. The installer fills in the per-OS commands (see the table).

Directory keys

Neo4jDir=.DeepPhe
DpheDir=.DeepPhe
DpheVizDbCreatorDir=.DeepPhe/tools/dphe-pipeline
DataApiDir=.DeepPhe/tools/dphe-data-api
VizDir=.DeepPhe/tools/deepphe-visualizer-v2
LogsDir=.DeepPhe/logs

Command keys

Each command is executed in its matching *Dir:

Key	What it starts	Typical value
StartNeo4j / StopNeo4j	Ontology graph	echo … — the ontology is embedded, so these are no-ops
StartDphe	NLP pipeline GUI	bin/runDeepPheGui.sh / .bat
StartDpheVizDbCreator	Builds the visualizer SQLite DB	./runDpheVizDbCreator.sh / .bat
StartDataApi	The data API service	./dphe-data-api-<platform>
StartViz / StopViz	The web visualizer	./deepphe-visualizer-v2-<platform>

Because the ontology is served from embedded resources, there is no external Neo4j server to run — a change from earlier DeepPhe releases that shipped a standalone Neo4j.

The components the launcher orchestrates

1. Pipeline reads reports from ~/DeepPheDocs, runs the DeepPhe NLP pipeline against the embedded ontology, and writes trimmed patient JSON.
2. DB creator turns that JSON (plus demographics) into visualizer_database/deepphe.sqlite3 and an OMOP database.
3. Data API serves that database.
4. Visualizer is the web UI that reads from the data API (default http://127.0.0.1, port 3000).

The DB-creator wrapper scripts

The installer writes runDpheVizDbCreator.sh (Unix) and .bat (Windows) around the raw DeepPheVizDbCreator binary. They:

• pick the right platform binary,
• pass through ---prefixed flags directly, or otherwise expect OUTPUT_DIR DEMOGRAPHICS_JSON [LEGACY_VIZ_DB_DIR],
• resolve the json input dir and the visualizer_database output dirs,
• wrap a top-level-array demographics file in { "patients": … } before merging,
• then invoke the binary with --input-dir, --source-type json, --demographics, --compressed-db, --omop-database, and --output-dir.

Command line vs. GUI

The primary user experience is the GUI launcher — the installed DeepPhe Launcher executable. Underneath, each stage is a command-line program that the launcher shells out to using the launcher.conf values:

• Advanced users can run the NLP pipeline scripts in .DeepPhe/bin (runDeepPhe.sh/.bat, runDeepPheGui.sh/.bat, runDefaultGui.sh/.bat) directly.
• The DB creator, data API, and visualizer binaries under .DeepPhe/tools/… can each be run directly with their platform-specific executable, for example with --help; the wrapper scripts accept ---prefixed flags for exactly this.

For most users, though, the launcher is the intended entry point and hides these details.

Headless launcher test

Maintainers can test the launcher button contract without opening the GUI:

./tests/launcher-headless-buttons.sh

The test compiles a small Java probe, initializes DesktopMainPanel with java.awt.headless=true, verifies the five toolbar buttons (NLP Summarizer, Data Merge Tool, Visualization GUI, Wiki, and Web Site), checks the compiled launcher config keys, and validates every command in launcher.conf.

By default it auto-detects common install roots such as /Applications/DeepPhe on macOS, $HOME/DeepPhe or /opt/DeepPhe on Linux, and /c/DeepPhe in Git Bash on Windows. Override it for staged installs:

INSTALL_ROOT=/path/to/DeepPhe ./tests/launcher-headless-buttons.sh
DEEPPHE_HOME=/path/to/DeepPhe/.DeepPhe ./tests/launcher-headless-buttons.sh

The full Java 26 suite runs this test with SKIP_IF_MISSING=true so Linux or Windows build hosts without an installed launcher do not fail just because no GUI package has been installed yet.