This submission implements a controlled April 2026 freight close for Numeric's Finance Engineer Challenge. It rates the supplied April shipment activity against carrier contracts, exposes every calculation and exception for review, records prepare/review/approve decisions, generates booking support, and reconciles later invoices.
The shipment-level rate-card result is $105,050.09. It is the controlled activity-based anchor, not automatically the amount management should approve or book. The application keeps the raw card estimate, any supported expected price-variance adjustment, and the approved best estimate separate. Because the supplied data does not include April invoices, this submission does not claim observed April accuracy or proven superiority to Denise's baseline.
Prerequisites: Python 3.11+, uv (preferred) or pip, Node.js 20.19+ on the 20.x line (or 22.12+), npm, and a desktop browser at least 1024 px wide. The close workflow is intentionally desktop-only and does not provide a phone or tablet interface.
uv sync --extra dev --extra web
source .venv/bin/activate
npm --prefix webapp ci
./scripts/start_app.shIf uv is unavailable:
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev,web]'
npm --prefix webapp ci
./scripts/start_app.shOpen http://127.0.0.1:5173, then:
- Run the April 2026 close.
- Inspect the $105,050.09 raw card anchor, carrier totals, shipment detail, lineage, and exceptions.
- Disposition every warning, prepare the estimate decision, and review and approve it using three distinct declared names.
- Inspect the approved booking support, journal entry, reversal, and immutable decision history.
- Reconcile actuals (locked until the booking is approved) any of three ways: enter one actual total per carrier (the quickest path), upload a judge-provided April invoice CSV (a blank 15-column template is linked on the screen), or load the labeled Synthetic Demo to exercise the workflow without external data.
- Open Method Comparison to see the honest historical backtest: Denise's trailing-three-month baseline beats the card method out-of-sample, and the recovered monthly rate index is diagnostic only — never applied to the April accrual.
The synthetic fixture is visibly labeled and tests workflow behavior only; it is not an April
actual and cannot support an accuracy claim. Uploaded invoices are retained locally with filename,
hash, and timestamp provenance under the Git-ignored outputs/uploads/<period>/ directory.
See the detailed judge walkthrough.
| Surface | Purpose |
|---|---|
React dashboard + FastAPI (webapp/, api.py) |
Primary judge interface for running, reviewing, approving, and reconciling the close. It renders Python artifacts and does not recalculate freight. |
Python pipeline (freight-accrual) |
Deterministic Decimal-based calculation and control oracle with isolated carrier strategies. |
Accounting workbook (outputs/accrual_<period>.xlsx) |
Generated Excel close workbook with BestEstimate, JournalEntry, Controls, RollForward, and TrueUp views. This is the reproducible spreadsheet deliverable. |
Accrual report (outputs/accrual_<period>.json) |
Deterministic shipment-level calculations, controls, exceptions, and raw journal support. |
Approved booking (outputs/approved_booking_<period>.json) |
Current approved decision and booked-amount journal, produced only after final approval. |
Control ledgers (outputs/close_control_ledger.jsonl, outputs/run_ledger.jsonl) |
Append-only decision and execution provenance. |
Reconciliation (outputs/reconciliation_<period>.json) |
Invoice-to-card variance and invoice-to-booked-estimate true-up, kept at their proper grains. |
Generated artifacts, invoice uploads, and confidential source data must not be committed.
flowchart TD
A[April shipment activity] --> B[Normalize and control]
B --> C[Carrier-specific rating]
C --> D[Raw card anchor]
D --> E[Exception review]
E --> F[Separate variance adjustment]
F --> G[Approved best estimate]
G --> H[Journal and reversal]
H --> I[Invoice reconciliation]
The supplied April population normalizes from 161 source rows to 160 canonical shipments plus one duplicate control. Carrier totals are Peak Logistics $49,806.89, Heartland Freight $31,946.25, and Coastal Express $23,296.95, totaling $105,050.09. Historical results and recovered rate indices remain diagnostics; they never silently modify the April estimate. Forward-looking decisions are in assumptions, while historical observations are in findings.
# Fingerprint source inputs.
freight-accrual inventory
# Normalize the selected period's shipments.
freight-accrual run --period 2026-04
# Generate the accrual JSON, Excel workbook, journal support, and run provenance.
freight-accrual accrue --period 2026-04
# Run the historical diagnostic comparison.
freight-accrual backtest
# Reconcile actual invoices after an approved booking exists.
freight-accrual reconcile --period 2026-04 --invoices path/to/invoices.csv--period YYYY-MM drives the shipment window, filenames, report period, and quarter logic. April
2026 is the default because it is the challenge period.
pytest --cov=finance_engineer_challenge
ruff check .
npm --prefix webapp run lint
npm --prefix webapp run build
npm --prefix webapp run e2eThe suite covers deterministic output, rating rules, accounting controls, API behavior, and the desktop workflow. CI runs supported Python versions and frontend checks.
src/finance_engineer_challenge/ Deterministic calculation and accounting core
webapp/ React desktop review workflow
api.py Thin local FastAPI layer
config/ Controlled rates, assertions, and period locks
data/raw/ Supplied challenge inputs
data/demo/ Clearly labeled synthetic reconciliation fixture
data/processed/ Generated normalized data (not committed)
outputs/ Generated reports and ledgers (not committed)
tests/ Python regression and control tests
docs/ Accounting decisions, evidence limits, and operations
Start with challenge alignment for the governing objective and claim boundaries, solution design for the architecture, and invoice reconciliation for the actuals workflow.