From 193df74b560c14f42812c236483b3ad77e34e703 Mon Sep 17 00:00:00 2001 From: Matthew Horridge Date: Thu, 9 Jul 2026 10:12:56 -0700 Subject: [PATCH] Refactor sidecar API service documentation Reorganize and clarify the documentation for the sidecar API service and its integration with Electron apps. --- README.md | 112 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 58 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 5586690..4234388 100644 --- a/README.md +++ b/README.md @@ -41,60 +41,6 @@ Notes: - Restrict outputs with `--targets nih_age,nih_sex`. - `--dataset-name` sets the dataset name used for metadata columns (defaults to the input file name). -### Sidecar (local API service) - -The package exposes a small sidecar entrypoint for running the FastAPI backend -as a local service (intended to be launched by an Electron app). - -Required environment variables: -- `API_PORT` (required): port to bind. -- `API_HOST` (optional): defaults to `127.0.0.1`. - -Example: - -```bash -API_PORT=54321 API_HOST=127.0.0.1 harmonization-sidecar -``` - -When running, the health check is available at: - -``` -GET http://127.0.0.1:54321/health/ -``` - -Graceful shutdown is supported via: - -``` -POST http://127.0.0.1:54321/shutdown/ -``` - -Logs are written to stdout/stderr as JSON lines. Optionally, set `API_LOG_PATH` -to also write logs to a file. - -### Sidecar packaging (CI) - -The repository includes a GitHub Actions workflow that builds the sidecar -executable for macOS, Windows, and Linux. The workflow outputs artifacts: - -- `harmonization-sidecar-mac` (tar.gz) -- `harmonization-sidecar-win` (zip) -- `harmonization-sidecar-linux` (tar.gz) - -Artifacts are built under: - -``` -dist/sidecar// -``` - -### Electron consumption (high level) - -Electron should consume the per-OS artifact produced by the packaging workflow, -unpack it into the app's bundled resources, and launch the sidecar binary at -runtime. The launcher sets `API_PORT` (and optionally `API_HOST`) and then polls -`/health/` before issuing API calls. - -See `docs/electron_sidecar.md` for the full packaging and launch guide. - ## Serialization Format Harmonization rules and primitives serialize to JSON-friendly dictionaries with a consistent schema. A rules file is a flat array of rule dicts, written as JSON or YAML depending on the file extension (`.yaml`/`.yml` for YAML, otherwise JSON) — both encode the same structure. @@ -290,3 +236,61 @@ For newline-separated input, use: ```json {"operation": "parse_array", "format": "delimiter", "delimiter": "\\n", "item_type": "integer"} ``` + +## Using the framework in an Electron App + +The framework can be integrated into an Electron App + +### Sidecar (local API service) + +The package exposes a small sidecar entrypoint for running the FastAPI backend +as a local service (intended to be launched by an Electron app). + +Required environment variables: +- `API_PORT` (required): port to bind. +- `API_HOST` (optional): defaults to `127.0.0.1`. + +Example: + +```bash +API_PORT=54321 API_HOST=127.0.0.1 harmonization-sidecar +``` + +When running, the health check is available at: + +``` +GET http://127.0.0.1:54321/health/ +``` + +Graceful shutdown is supported via: + +``` +POST http://127.0.0.1:54321/shutdown/ +``` + +Logs are written to stdout/stderr as JSON lines. Optionally, set `API_LOG_PATH` +to also write logs to a file. + +### Sidecar packaging (CI) + +The repository includes a GitHub Actions workflow that builds the sidecar +executable for macOS, Windows, and Linux. The workflow outputs artifacts: + +- `harmonization-sidecar-mac` (tar.gz) +- `harmonization-sidecar-win` (zip) +- `harmonization-sidecar-linux` (tar.gz) + +Artifacts are built under: + +``` +dist/sidecar// +``` + +### Electron consumption (high level) + +Electron should consume the per-OS artifact produced by the packaging workflow, +unpack it into the app's bundled resources, and launch the sidecar binary at +runtime. The launcher sets `API_PORT` (and optionally `API_HOST`) and then polls +`/health/` before issuing API calls. + +See `docs/electron_sidecar.md` for the full packaging and launch guide.