# 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).