Skip to content

README.md

Latest commit

 

History

History
194 lines (152 loc) · 6.61 KB

README.md

File metadata and controls

194 lines (152 loc) · 6.61 KB
Raw

BioModStack Control Platform API

This FastAPI service is the control plane for BioModStack. It is not just a job submission wrapper: it owns orchestration state, result metadata, lineage, analysis scheduling, file access, sequence operations, runtime administration, and bounded instrument integrations.

Entry point

The managed pre-launch path initializes genuinely empty databases and runs registered migrations; ordinary API startup attests the existing schema rather than silently repairing it. The API starts the analysis worker and registers the router surface used by the web UI, Electron shell, and local tooling. The GPU workflow orchestrator starts only when the runtime is allowed to own workflow launches; guarded core-runtime mode skips that scheduler ownership and relies on the host workflow adapter instead.

Runtime role

In the current workstation architecture the API normally runs inside the containerized core runtime, while Nextflow job ownership remains host-native via biomodstack-workflow-adapter.service.

That means:

  • API/web runtime is usually containerized
  • job launch/cancel/running-job execution still crosses the workflow-adapter boundary
  • browser, Electron, GTK, and optional mobile shells all talk to the same API contract

Managed Development startup

Complete the nonproduction installation procedure first. From the repository root, explicitly select Development:

./start_ui.sh start --runtime dev
./start_ui.sh status --runtime dev --json
./start_ui.sh stop --runtime dev

Use start-api, restart-api, and stop-api through the same launcher when a targeted operation is required. Do not start an independent Uvicorn process as a substitute for the managed service: dependency ownership, pre-launch migrations, readiness, and workflow-adapter ownership belong to the supported control path.

For focused tests, use the locked environment without starting services:

cd platform/api
uv run --frozen --group dev python -m pytest <focused tests> -q -rs

Keep the repository's route-free test guards enabled. Skipped native-tool checks are not evidence of native acceptance; see AGENTS.md.

Major router surface

The API currently includes routers for:

  • models and input schemas
  • jobs and queue/orchestration controls
  • designs and persisted analyses
  • files and artifact browsing
  • analytics
  • system and GPU status
  • install-profile/runtime-state inspection
  • workflow-adapter launch/cancel/running-job bridge routes
  • framework lookup and MSA helpers
  • nucleotide sequence storage and mol bio operations
  • RCSB and Ribocentre helpers
  • the compact BioXP profile/status/connection/protocol/job/command control plane
  • mobile UI update/feed endpoints for optional phone shells

Router registration lives in main.py.

Notable local-admin/runtime routes

Important runtime/admin surfaces include:

  • /api/system/runtime-state
  • /api/system/install-profile
  • /api/workflow-adapter/health
  • /api/workflow-adapter/launch
  • /api/workflow-adapter/cancel
  • /api/workflow-adapter/running-jobs
  • /api/mobile-ui/channels/{channel}/manifest
  • /api/mobile-ui/bundles/{channel}/{version}.zip
  • /api/mobile-ui/files/{channel}/{version}/{asset_path}

The system/install-profile routes are intended for localhost/testclient-scoped administration, not general remote multi-tenant API exposure.

Pathing and data roots

Path resolution is centralized in paths.py.

Important functions/roots include:

  • code root: get_code_root()
  • data root: get_data_root()
  • results: get_results_dir()
  • work: get_work_dir()
  • analysis cache: get_analysis_cache_dir()
  • containers: get_container_dir()
  • weights: get_weights_root()
  • database: get_db_path() / get_db_url()
  • mobile-update payloads: get_mobile_ui_updates_dir()

Priority for database location is:

  1. DATABASE_URL
  2. BMS_DB_PATH
  3. install profile
  4. ${BMS_DATA}/biomodstack.db
  5. repo-local fallback

GPU scheduler state defaults to ${BMS_DATA}/scheduler/gpu_config.json. Set BMS_SCHEDULER_STATE_DIR to select a different persistent scheduler-state directory; the service resolves it at process start, so restart the scheduling authority after changing that environment variable.

Nextflow launcher logs remain append-only and durable on disk while diagnostic tails are bounded in memory. Incremental reads are also byte-bounded. Deployments can tune the in-memory/read limits with:

  • BMS_NEXTFLOW_LOG_READ_BYTES (maximum incremental read size)
  • BMS_NEXTFLOW_RETAINED_LOG_MAX_BYTES (in-memory diagnostic tail bytes)
  • BMS_NEXTFLOW_RETAINED_LOG_MAX_LINES (in-memory diagnostic tail lines)

Core runtime env vars

Common env vars include:

  • BMS_HOME
  • BMS_DATA
  • BMS_INPUTS
  • BMS_DB_PATH
  • BMS_SCHEDULER_STATE_DIR
  • DATABASE_URL
  • BMS_WEIGHTS
  • BMS_CONTAINER_DIR
  • BMS_MSA_CACHE
  • BMS_COLABFOLD_DB
  • BMS_SABDAB_CACHE
  • BMS_WORKFLOW_ADAPTER_URL
  • BMS_NEXTFLOW_LOG_READ_BYTES
  • BMS_NEXTFLOW_RETAINED_LOG_MAX_BYTES
  • BMS_NEXTFLOW_RETAINED_LOG_MAX_LINES
  • BMS_MOBILE_UI_UPDATES_DIR
  • BMS_FAN_CONTROL_BACKEND
  • CORS_ORIGINS

BioXP-specific env vars are documented in ../../docs/Lab_Automation_MolBio_and_Sequencing.md.

Operational responsibilities

The API is responsible for:

  • normalizing launch params
  • mapping UI model definitions to workflow runtime behavior
  • persisting Job, Design, and AnalysisRun records
  • tracking stage outputs and lineage
  • serving artifacts back to the frontend
  • scheduling post-hoc analyses and review refresh flows
  • exposing runtime/install-profile state to local control surfaces
  • brokering host-native workflow execution through the workflow adapter
  • serving optional mobile shell update metadata/assets
  • enforcing the bounded BioXP control-plane and mutation-admission contract

The BioXP router is intentionally compact and is not a generic robot proxy. It contains bounded profile, status, explicit connection, BMS-local logs, offline protocol, durable local job, typed command, and emergency-delivery routes. Hardware-family, arbitrary-path, host-lifecycle, shell, and remote-log routes are absent. See ../../docs/BioXP_Compact_Control_Plane.md.

Related docs