rods/docs/engineering/architecture.md

Architecture and requirement traceability

Owner: Rods Project Team
Status: Active
Last Updated: 2026-04-16
Version: 0.2.0

Module boundaries

• solver-c: Authoritative numerics — FDM, FEA, diagnostic FDM, trajectory preprocess, distributed side-load/friction coupling, valve/gas dynamic diagnostics, optional Fourier analytical baseline, gravity/buoyancy, variable (E(x), A(x), \rho(x)), JSON stdin contract (schemaVersion: 2). No HTTP/XML.
• solver-api: Local HTTP service — parse XML, convert to SI, surface-card QA, spawn C binaries with JSON pipe, attach verbose, comparison, pumpMovement, schemaVersion.
• gui-ts: Workflow and visualization (tabbed case editor, XML round-trip, dynacards, engineering checks, 3D wellbore preview); not the primary PDE solver.
• data/cases: Canonical inputs and regression cases.
• data/golden: Fingerprints for deterministic API regression.
• references/papers/README.md: Citation index for external literature used by Agents/MATH_SPEC.md.

C driver contract

Executables read one JSON object from stdin (UTF-8). Required top-level keys are produced by solver-api/src/solverClient.js — see that file for the exact shape (workflow, model, optional surfaceCard, optional options).

options supports:

• enableProfiles — includes trajectory + side-load + friction profile payloads.
• enableDiagnosticsDetail — includes valve-state and chamber/gas time-series.
• enableFourierBaseline — computes analytical Fourier baseline in C.
• fourierHarmonics — harmonic count for baseline reconstruction.

Legacy argv-based invocation has been removed to avoid drift between CLI and API.

MVP requirement traceability

Requirement	Module	Notes
Real C solver path	solver-c, solver-api	JSON pipe; no mock-only solve
XML inspectability	solver-api, gui-ts	rawFields, unsupportedFields
Output cards primary	solver-c, gui-ts	Polished + downhole series
Determinism	solver-c, solver-api	Golden hash; no randomness
Warnings / numerics	solver-c, solver-api	warnings, verbose.numerics, CFL
3D survey visibility	gui-ts	Results tab includes projected 3D wellbore with DLS/side-load overlay modes + rod/pump overlays + interactive camera controls

System flow

1. GUI or client sends XML (+ options) to API.
2. API parses to canonical SI model + preserves unknown fields.
3. Optional: POST /solve/validate-card runs QA only.
4. API builds JSON and runs solver_main / solver_fea_main with stdin.
5. C returns JSON stdout; API merges parsed, comparison, runMetadata.
6. GUI renders cards, survey, inspection panels.

Execution guidelines for upcoming hardening

• Keep defaults stable; grow contract additively behind options.
• Treat C as numerical source-of-truth; API orchestrates and validates.
• Require test evidence for every new equation term:
  • unit-level numeric sanity,
  • integration-level behavior,
  • deterministic regression impact.
• Pair every new feature with:
  • one "happy path" case,
  • one edge/stress case,
  • one regression gate entry.

GUI guardrails and thresholds

• Pump-depth consistency gate: solver run is blocked when abs(PumpDepth - totalRodLength) > 15 m.
• DLS bad-section threshold: 15 deg/100 used both for warning logic and 3D contour highlighting.
• Thresholds are intentionally fixed (not user-configurable) to keep deterministic behavior.
• Diagnostic GUI path is now wired:
  • measured card input + QA call in Kinematics tab,
  • workflow=diagnostic run from Solver tab with surfaceCard payload.
• Results now include trajectory segment analytics and artifact export actions (3D SVG/PNG, summary JSON).