Tools Internal Route Map

Date: 2026-06-14. Scope: r-server/routes/tools.js. Purpose: define split points before extracting the tools module from the historical mixed backend tree.

Current Runtime

Public nginx routes known /api/platform/tools/* paths to ECS platform. The ECS process authenticates users, reads/writes PostgreSQL tool_jobs, and calls Dell through internal-token routes for local execution and file access.

browser
  -> /api/platform/tools/*
  -> ECS biof3-platform
  -> PostgreSQL tool_jobs
  -> Dell /api/internal/tools/* when local execution or files are needed

/api/r/tools/* no longer reaches Dell through the broad R compute catch-all. Legacy public/demo asset paths are explicitly terminated at ECS platform for old reports and exported docs, while legacy metadata, submit, private file, job, and cancel routes return 404.

Route Classification

Route	Current behavior	Target owner
POST /api/tools/run	In platform mode proxies to Dell internal run; in Dell mode creates local job and executes.	Public route stays platform-owned; Dell execution moves to internal module.
GET /api/tools/status/:id	Reads tool_jobs; no local files.	Platform metadata.
GET /api/tools/history	Reads tool_jobs; no local files.	Platform metadata.
PUT /api/tools/job/:id/name	Updates tool_jobs.	Platform metadata.
PUT /api/tools/job/:id/public	Admin update of public demo flag in tool_jobs.	Platform metadata.
DELETE /api/tools/job/:id	Platform authorizes and deletes PG row; Dell removes local output via internal route.	Platform metadata plus Dell cleanup proxy.
POST /api/tools/cancel/:id	Platform updates PG status; Dell kills local process via internal route.	Platform metadata plus Dell cancel proxy.
GET /api/tools/file/:jobId/:filename	Platform authorizes against tool_jobs; Dell serves local private file.	Platform authorization plus Dell file proxy.
PUT /api/tools/file/:jobId/:filename	Platform authorizes; Dell replaces local output file and regenerates report.	Platform authorization plus Dell file proxy.
GET /api/tools/public-demo/:toolId	Public; in platform mode proxies to Dell internal public demo asset handler.	Platform public endpoint plus Dell asset handler.
GET /api/tools/public-file/:jobId/:filename	Public; in platform mode proxies to Dell internal public file handler.	Platform public endpoint plus Dell asset handler.
GET /api/tools/demo/:toolId[/filename]	Legacy static demo; in platform mode proxies to Dell.	Compatibility only; retire after legacy URL migration.
GET /api/tools/demo-data/:toolId/:filename	Demo input data; in platform mode proxies to Dell.	Compatibility/public asset endpoint; keep until frontend/docs no longer rely on legacy paths.
/api/internal/tools/*	Internal-token Dell local execution/files/cancel/delete/demo assets.	Dell internal only.
POST /api/internal/smoke-test-result	Internal smoke notification guarded by SMOKE_TEST_TOKEN.	Dell/internal ops helper.

Code Split Candidates

1. Done 2026-06-14: routes/tools-metadata.js Platform-owned handlers that only read/write PostgreSQL: status, history, job name, job public.

2. routes/tools-platform.js Platform-owned public routes that authenticate/authorize then proxy to Dell: run, file GET/PUT, cancel, delete, public-demo, public-file, demo, demo-data.

3. Done 2026-06-15: routes/tools-internal.js Dell-only internal-token handlers: internal/tools/run, internal file read/write, local cancel/delete, demo assets, smoke-test result.

4. Done 2026-06-14: helpers/tools-assets.js Shared path-safe asset helpers: safeJoinUnder, PUBLIC_DEMO_ASSETS, public demo/file readers, demo-data readers.

5. Done 2026-06-14: helpers/tools-dell-proxy.js ECS-to-Dell internal-token proxy helpers: proxyDellToolRun, public/demo asset streaming, private file read/write proxy, cancel proxy, and delete proxy.

6. Done 2026-06-14: helpers/tools-executor.js Dell-local execution helpers: handleToolRun, executeJob, killLocalToolJob, report regeneration, uploaded-file validation, R error translation, zombie recovery.

Safe Extraction Order

1. Extract metadata-only routes first. They do not touch Dell files, Docker, or active job processes.
2. Extract asset helpers next, keeping route behavior unchanged.
3. Extract internal Dell routes as a Dell-owned module.
4. Extract platform proxy routes after internal helpers have stable boundaries.
5. After docs/static legacy URLs are migrated and generated site output is redeployed, add nginx probes and blocks for public /api/r/tools/* control-plane leakage. Done on 2026-06-14: old public/demo asset paths are kept compatible via ECS platform, and old control-plane paths return 404.

Compatibility Notes

• Frontend src/pages/tools/index.tsx uses getApiPrefix() which resolves to /api/platform in production for R tools and /api/py for Python tools.
• Source Docusaurus docs now use https://biof3.com/api/platform/tools/... links for machine-learning public demo images. Ignored/generated static/exports/ output is refreshed by site build/deploy, not edited by hand.
• DESeq2 report templates now use /api/platform/tools/demo/.... Runtime report regeneration intentionally recognizes both old /api/r/tools/demo/... and new /api/platform/tools/demo/... URLs so old stored reports/templates can still be inlined.

Current Verification

As of 2026-06-14:

• /api/platform/tools/history returns 200.
• /api/platform/tools/public-demo/bindea-immune returns 200 with asset files.
• Unknown /api/platform/tools/* returns 404.
• /api/r/tools/public-demo/bindea-immune still returns 200 through ECS compatibility routing for old public links.
• /api/r/tools/history, /api/r/tools/run, /api/r/tools/status/*, /api/r/tools/file/*, /api/r/tools/job/*, and /api/r/tools/cancel/* return 404; the old public R tools control plane no longer leaks to Dell.
• /api/r/internal/tools/* and /api/platform/internal/tools/* return 401 or 403 without internal credentials.