Deployment & Hosting

Deployment guidance keeps local development, hosted documentation, and platform operations aligned.

Documentation build

cd moltrace_docs
npm run build

The generated documentation output is written to dist/.

Port expectations

• Frontend development: 3000
• Backend development: 8000
• Docs development: the Astro dev server URL, usually 4321

Keep externally mapped hosting ports separate from local development conventions so developer workflows remain predictable.

Hosting checks

• Confirm the /guides/ route is available.
• Confirm favicon, manifest, logo assets, and Open Graph preview assets resolve.
• Confirm search index generation completes during the static build.
• Confirm no sidebar or header links point at missing pages.

GSD experimental backend rollout (v0.6 soak loop)

The opt-in Global Spectral Deconvolution backend (POST /spectrum/analyze/gsd, see NMR Interpretation) ships behind a per-request experimental: true flag while it accumulates a soak record on real-tenant traffic. The full pipeline from per-call telemetry to per-tenant graduation is feature-complete: the readiness panel renders in two API calls and the entire policy is owned by the backend.

Pipeline

1. Per-call audit event — every opt-in GSD invocation writes a structured spectrum.analyze_gsd audit event capturing the request shape (level, nucleus, declared solvent, field_mhz, input_point_count, wall_ms) and outcome shape (peak / environment counts by category, detected solvents, error_kind on failure). Tenants can query their own events via GET /audit/events?event_type=spectrum.analyze_gsd. (v0.6.3)
2. Aggregate rollup — GET /spectrum/analyze/gsd/telemetry-summary?window_days=N (admin-only; default 90 days, clamped [1, 365]) returns a pre-aggregated SpectrumGSDTelemetrySummary — invocations, error rate, median / p95 wall time, solvent auto-detect rate, plus per-nucleus / per-level / per-error-kind slice breakdowns. The readiness panel reads off the rollup; the raw event stream stays available for tenant-scoped per-event inspection. (v0.6.4)
3. Flip-readiness verdict — the rollup carries flip_readiness_verdict ("insufficient_data" | "clear" | "blocked"), flip_readiness_reasons (human-readable strings the FE shows verbatim), and flip_readiness_policy (the threshold snapshot: min_invocations=500, max_error_rate=0.05, min_solvent_detect_rate=0.95). A future policy tightening is a one-line backend change with no FE deploy required. (v0.6.5)
4. Per-tenant scope — GET /spectrum/analyze/gsd/telemetry-summary?actor_user_id=<id> (admin-only) computes the same verdict over only that user’s audit stream. The response echoes scope_actor_user_id so cached or replayed responses are self-describing. (v0.6.6)
5. Graduation action — POST /admin/users/{user_id}/gsd-graduation with body {"graduated": bool, "reason": str} (reason required, 1–500 chars — regulatory-relevant audit evidence). Idempotent on repeat-graduate. users.gsd_graduated_at is a nullable timestamp (None = still experimental; timestamp = graduated at that moment); spectrum_analyze_gsd consults it at request time so graduated tenants get experimental: false in both the response and the soak-telemetry audit event. API-key callers (no user attached) stay on experimental: true. (v0.6.7)
6. Adoption telemetry — the rollup carries graduated_user_count (full platform count globally; 0 or 1 when scoped). The FE readiness panel can render “X tenants graduated” from a single API call. (v0.6.8)
7. Per-tenant graduation history — GET /admin/users/{user_id}/gsd-graduation-history (admin-only) returns the full graduate / ungraduate sequence newest-first, each event carrying the admin’s documented reason and structured before/after state. Auditors reconstruct every decision without filtering the global audit stream client-side. (v0.6.9)
8. Adoption velocity — the rollup carries newly_graduated_in_window (unique users with a graduate event inside the window; repeat graduations dedup, ungraduate events don’t count). The readiness panel renders “X tenants graduated this quarter” alongside the snapshot count. (v0.6.10)

Operational summary

• Two-call FE readiness panel — rollup (/telemetry-summary) plus per-tenant graduation history (/gsd-graduation-history) covers the full v0.6 story for the readiness review meeting.
• Backend-owned policy — the flip decision lives in _compute_flip_readiness_verdict; tightening (for example, raising min_invocations to 2000) is a one-line backend change that lands in every caller’s rollup with no FE deploy.
• Audit-first — every graduation decision is reconstructible end-to-end without a separate reporting pipeline.