Backend/API Contract
The backend/API contract is the bridge between frontend design changes and runtime behavior. When a new surface appears in the frontend, the matching backend capability should be identified, confirmed, or added before the change is considered complete.
Review checklist
Section titled “Review checklist”- Confirm every new data view has a backend endpoint or a documented static source.
- Confirm every new action has a stable request path, method, payload shape, and response shape.
- Preserve existing endpoints, response fields, and error behavior unless a migration is explicitly planned.
- Add route coverage to the visual baseline list when a new user-facing surface is introduced.
- Keep desktop, laptop, browser, PWA, and mobile behavior aligned with the same contract.
Common surfaces
Section titled “Common surfaces”- SpectraCheck uploads and analysis results
- Raw FID archive preservation
- Regulatory records and evidence trails
- Reaction optimization workspaces
- Deployment health, readiness, and diagnostics
SpectraCheck NMR analysis endpoints
Section titled “SpectraCheck NMR analysis endpoints”The NMR analysis backend exposes a growing surface of typed endpoints. Each one writes a structured audit event so reviews remain reconstructible. The full capability detail with validation numbers lives in NMR Interpretation; the inventory below is the contract list a frontend or integrating system codes against.
| Method + path | Purpose | Audit event |
|---|---|---|
POST /spectrum/analyze/gsd | Opt-in Global Spectral Deconvolution; returns peaks + classifications + per-peak QC. | spectrum.analyze_gsd |
POST /spectrum/analyze/multiplets | Group GSD peaks into multiplets, recover J couplings, expose a synthetic forward modeller. | spectrum.analyze_multiplets |
POST /spectrum/analyze/integration | Quantitative region integration — Sum / Edited Sum / Peaks. | spectrum.analyze_integration |
POST /spectrum/predict/shifts | Predict ¹H / ¹³C shifts (ppm) + per-atom uncertainty (NMRNet or HOSE-code fallback). | spectrum.predict_shifts |
POST /spectrum/retrieve | FAISS HNSW similarity retrieval — top-k nearest reference spectra by L2 distance. | spectrum.retrieve |
POST /candidates/compare/jcoupling | Multiplet J-coupling unified-confidence bridge; per-candidate agreement labels + contradiction flags. | confidence.candidates.multiplet_jcoupling_bridge |
GET /spectrum/solvents/known | Canonical solvent catalog for FE dropdown validation. | — |
Admin / operations endpoints (GSD soak loop)
Section titled “Admin / operations endpoints (GSD soak loop)”These endpoints support the per-tenant graduation rollout for the opt-in GSD backend. See Deployment & Hosting → GSD experimental backend rollout for the operational policy.
| Method + path | Purpose |
|---|---|
GET /spectrum/analyze/gsd/telemetry-summary?window_days=N | Aggregate rollup — invocations, error rate, median/p95 wall time, solvent auto-detect rate, plus flip_readiness_verdict + flip_readiness_reasons + flip_readiness_policy + graduated_user_count + newly_graduated_in_window. Accepts an admin-only ?actor_user_id=<id> for per-tenant scope. |
POST /admin/users/{user_id}/gsd-graduation | Admin action — graduate or ungraduate a tenant out of experimental: true, with a required reason (1–500 chars). |
GET /admin/users/{user_id}/gsd-graduation-history | Full graduation history for one tenant — every graduate / ungraduate decision with the admin’s documented reason, newest-first. |
Frontend regeneration cadence
Section titled “Frontend regeneration cadence”The FE↔BE contract is openapi.json → npm run generate:openapi → moltrace_frontend/src/lib/api/schema.d.ts. Regenerate the schema after any release that adds a new endpoint or changes an existing request/response shape (every release flagged “Contract change — frontend must regenerate schema.d.ts” in the upstream moltrace_backend/CHANGELOG.md).