Skip to content

architecture.md

Latest commit

 

History

History
77 lines (62 loc) · 4.57 KB

architecture.md

File metadata and controls

77 lines (62 loc) · 4.57 KB
Raw

Architecture

RareLink uses existing frameworks at every commodity layer:

  • FastAPI and Pydantic for validated HTTP contracts;
  • SQLModel/SQLAlchemy with Alembic-managed PostgreSQL for the production coordinator ledger; SQLite is limited to development and isolated integration;
  • the OpenAI Python client for Step 3.7's compatible API;
  • React Query for server state, Recharts for metric comparison, and React Markdown for reports;
  • MONAI and NVIDIA FLARE behind a federation adapter on DGX Spark.

The project-specific code is intentionally limited to the research workflow, experiment contract, patient-data egress policy, evidence linkage, and the Spark/FLARE adapter.

React console → FastAPI → workflow + policy + ledger + agent artifact registry
                         ↘ Step 3.7 Agent Team (aggregate inputs only)
                            ├── Research Director → protocol
                            ├── Experiment Designer → fixed comparison proposal
                            ├── Statistical Reviewer → evidence and fairness review
                            ├── Privacy Reviewer → report release decision
                            └── Research Writer → evidence-grounded narrative
                         ↘ FederationRunner
                            ├── MockFederationRunner (local development)
                            └── MonaiNvflareRunner (local CPU or DGX Spark GPU)

Each Agent output is validated against a Pydantic schema, persisted independently, linked from the audit ledger, and exported in agent_artifacts.json. The Experiment Designer can only propose a contract; a human principal investigator must approve and lock it. The Privacy Reviewer can block report generation but cannot relax the deterministic egress policy.

The mock runner is deterministic and is always labelled mock mode. It exists to develop and test the control plane; it is not evidence of GPU or federated training.

The Spark path uses NVIDIA FLARE 2.7.2's maintained Recipe and Client APIs directly:

  • nvflare.app_opt.pt.recipes.FedAvgRecipe defines FedAvg/FedProx jobs;
  • nvflare.recipe.SimEnv runs the three named logical sites with one worker thread to limit unified-memory pressure;
  • nvflare.client receives and returns MONAI SegResNet weights;
  • NVIDIA's PTFedProxLoss supplies the proximal regularization term.

The same recipe can be exported for POC/production environments without rewriting the MONAI training script. Auto-FL remains an optional feature flag after the stable FedAvg/FedProx path is proven.

Physical multi-Spark deployment path

The local SimEnv path is deliberately not reused as a claim of multi-hospital execution. Physical deployment uses a separate, validated topology contract in deploy/physical/topology.example.yml:

Coordinator (FLARE Server + Admin Kit)
  ├─ mTLS ─ Hospital A Spark (independent FLARE Client + local MONAI + local manifest)
  ├─ mTLS ─ Hospital B Spark (independent FLARE Client + local MONAI + local manifest)
  └─ mTLS ─ Hospital C Spark (independent FLARE Client + local MONAI + local manifest)

The physical coordinator fails closed if it is configured with SQLite. A non-SQLite coordinator never creates or mutates tables at application startup: an authorized migration job must first apply the reviewed Alembic revision, and the API then verifies that alembic_version equals the repository head. The database deployment contract, recovery procedure, and current unvalidated hospital PostgreSQL boundaries are documented in postgresql-alembic.md.

scripts/render_physical_federation.py turns that central, non-sensitive contract into the project source that NVIDIA FLARE signs. It contains no data mount, image identifier, label, patient field, certificate, private key, public IP or SSH detail. Each hospital keeps an untracked site-runtime.yml and passes a local manifest to its own Client. The physical job export sets --require-local-only-manifest; the Client rejects a manifest containing any other site's cases before opening an image. The full operational runbook is physical-deployment.md.

In nvflare mode, FastAPI creates a persisted TrainingJob and returns immediately. A process-local unified-memory guard serializes Local, FedAvg, and FedProx workloads on one Spark. Progress, logs, aggregate Dice/HD95, workspace, failure details, and global-model paths are written back to SQLModel; the React console polls these records every 1.5 seconds. A failed job is retryable without creating a duplicate experiment.