solidAtoms
legacy.solidatoms.com
LEGACY API DISCOVERY SPRINT — WORKED EXAMPLE

Meridian Wholesale: a legacy order system, recovered and running.

Meridian Wholesale is a wholesale distributor whose order-to-cash process lived in an undocumented Node command-line application — “Stockdesk”. No spec, no tests, no API. This page is the complete output of a Legacy API Discovery Sprint on that system: the recovered business rules running live below, the machine evidence behind them, an independent verification re-run, and the reconstructed REST API you can call right here. Everything on this page executes the recovered logic — nothing is a screenshot or a mock-up.

What was recovered

REA (Reverse Engineer Anything) 6.7.0 statically analysed the Stockdesk source and rebuilt its behaviour as evidence: pricing tiers, volume discounts, regional tax, a Sunday surcharge, credit control, stock reservation with backorders, a four-state order lifecycle, Net 30 invoicing and returns with a restocking fee. Each rule was then ported line-for-line into this page and into the reconstructed API specification, so the system you can drive below behaves exactly as the original CLI did — including its error strings and its flaws, which are documented in the findings section rather than hidden.

Analysis evidence

ToolREA 6.7.0
JavaScript files parsed8
Parse failures0
Graph nodes / edges29 / 54
Findings37
Integrity contradictions0
Evidence IDev_d2f161d8…fbc6
01

The live system

Stockdesk, running in your browser with its original seed data. Create orders, confirm them to reserve stock, ship, invoice, take payment and process returns. The state tables update as you work — use Reset system to return to the seed data at any time. The business date drives the Sunday surcharge and invoice due dates.

IDCustomerTierRegionCredit limitBalanceAvailable
SKUProductPriceIn stockReorder atStatus

Build an order or a quote

No lines yet — the prepared scenarios below load lines for you, or add your own.

Quote applies tier discount, per-line volume discount (qty ≥ 100), regional tax and the Sunday surcharge. Creating an order also runs the credit check — exactly as the CLI did.

OrderCustomerLinesTotalStatusInvoiceActions
No orders yet. Run a prepared scenario or create one above.

Prepared scenarios

The exact cases from the reconstructed specification, one click each. They run against the live system above, so run them on a freshly reset system to see the documented numbers.

A — Full order-to-cash cycle

Gulf Supplies orders 5 × Widget A and 2 × Gadget Pro, then the order is confirmed, shipped, invoiced on Net 30 and paid in full.

EXPECTED · total 15,750 · WDG-001 → 115 · GDT-100 → 43 · INV-1001 due 2026-12-19 · balance returns to 45,000

B — Backorder on short stock

Karachi Traders orders 10 × Widget B, but only 8 are in stock. The confirm still succeeds: 8 are reserved and 2 become a backorder line.

EXPECTED · reserved 8 · backordered 2 · WDG-002 stock → 0 · reorder alert fires

C — Credit refusal

Lahore Retail Group has 20,000 of credit available. A large Gadget Pro order exceeds it and is refused at creation — before any stock moves.

EXPECTED · error CREDIT:EXCEEDED:C-1003 · no order created

D — Return with restocking fee

After scenario A, Gulf Supplies returns 1 × Gadget Pro from the invoiced order. The unit goes back into stock and a 10% restocking fee is charged.

EXPECTED · fee 450 · GDT-100 stock → 44 (run A first)

E — Tier, volume & Sunday pricing

A gold-tier quote of exactly 60,000, a 120-unit cable line that earns the 5% volume discount, and the same quote priced on a Sunday to expose the +2% surcharge.

EXPECTED · gold/PK 60,000 → 62,304 · Sunday adds 2%

F — Illegal transition

The lifecycle only allows draft → confirmed → shipped → invoiced, with cancel from draft or confirmed. Jumping a draft straight to shipped is rejected.

EXPECTED · error ILLEGAL_TRANSITION:draft->shipped

The recovered pricing rules, as implemented

tier discount — gold ≥ 50,000 → 12% · silver ≥ 20,000 → 7% · bronze → 0%
volume discount — 5% off any line with qty ≥ 100, applied per line before the tier discount
tax by customer region — PK 18% · AE 5% · US 0% · GB 20% · unknown region defaults to 18%
Sunday surcharge — +2% on the taxed total when the pricing date is a Sunday
credit control — order refused at creation when total > credit limit − balance → CREDIT:EXCEEDED:<customerId>
lifecycle — draft → confirmed → shipped → invoiced; cancel only from draft or confirmed; anything else → ILLEGAL_TRANSITION:<from>-><to>
02

REA replay — how the rules were recovered

No one read the Stockdesk code and wrote down what they believed it did. REA parsed the source into a behaviour graph and emitted findings, each tied to evidence in the code itself. Press play to replay the analysis summary.

REA 6.7.0 · target: demo/legacy-stockdesk/ · press “Replay analysis”.

Evidence summary

Files parsed8 JavaScript files
Parse failures0
Behaviour graph29 nodes · 54 edges
Findings emitted37
Integrity contradictions0
Evidence IDev_d2f161d8dfddc8833536a133b56ab39306f7fe225e310fb972d29e0e8fd1fbc6

What “0 contradictions” means

REA cross-checks every recovered rule against every other path through the code. A contradiction would mean two parts of the system disagree about the same rule — for example, pricing a line two different ways. Zero contradictions means the behaviour documented in the reconstructed specification is the behaviour the code actually has, stated once and consistently. Where the code itself is the problem — a missing audit trail, a credit check that runs only once — that is reported as a finding, not smoothed over. Those findings are in section 05.

03

Verification re-run

The specification was verified by executing the recovered logic against fixed cases with known-correct answers. This re-run executes the same cases, live, against a fresh copy of the system — independent of anything you have done in section 01 — and compares every figure.

Not run yet.
04

The reconstructed REST API

The sprint’s main deliverable: Stockdesk’s behaviour, re-expressed as a REST API. These endpoints are callable here — they execute against the same live system as section 01, return the same payloads the specification defines, and fail with the same error strings as the CLI (CREDIT:EXCEEDED:…, STOCK:UNKNOWN_SKU:…, ILLEGAL_TRANSITION:…).

IDs in paths (ORD-1001, INV-1001) refer to the live system in section 01 — create an order there or via POST /orders first.

// Select an endpoint and press “Send request”.

Error contract

CREDIT:EXCEEDED:<customerId> — order total exceeds available credit at creation
STOCK:UNKNOWN_SKU:<sku> — a line references a SKU that does not exist
ILLEGAL_TRANSITION:<from>-><to> — lifecycle move the state machine forbids
RETURN:NOT_INVOICED:<orderId> — returns are accepted only on invoiced orders
05

Findings, risks & migration roadmap

Recovering the rules is only half the value. The analysis also surfaces where the legacy system is exposed — the things a rewrite must fix deliberately, because a line-for-line port would faithfully reproduce them.

HIGH

Single JSON file store

All customers, stock, orders and invoices live in one JSON file, rewritten on every change. No transactions, no locking: two processes writing at once can corrupt the entire order book, and there is no recovery point short of a file backup.

HIGH

No authentication or authorisation

Anyone who can run the CLI can create orders, invoice customers and record payments. There is no user identity, no role separation between sales, warehouse and finance, and nothing to attribute an action to.

MED

No audit trail

State is overwritten in place. Once an order is invoiced, its earlier prices, quantities and status history are gone — disputes and reconciliation have nothing to check against.

MED

Credit is checked once, at creation

The credit check runs when an order is created and never again. An order created inside the limit can still be confirmed and invoiced after the customer’s balance has grown past it.

MED

Backorders are never auto-fulfilled

When stock runs short, the shortfall is recorded as a backorder line — and then nothing watches for replenishment. Backorders are only ever cleared by a human noticing them.

LOW

Hard-coded tax and pricing rules

Tax rates, tier thresholds and the Sunday surcharge are constants in code. A tax change in any region means a code change, a redeploy, and a risk of silently changing historical pricing behaviour.

Four-phase migration roadmap

P1

Wrap — put the recovered API in front

Deploy the reconstructed REST API as a façade over the existing system, unchanged.

  • Existing behaviour preserved, verified against the spec cases
  • Clients integrate against the API, not the file store
P2

Stabilise — real storage and identity

Move state from the JSON file to a transactional database; add authentication, roles and an audit log.

  • Fixes the HIGH findings without touching business rules
  • Every state change attributed and recoverable
P3

Harden the rules

Re-check credit at confirmation and invoicing; auto-fulfil backorders on stock receipt; move tax and tier rules into configuration.

  • Rule changes become data changes, tested against the recovered spec
P4

Replace — retire the legacy core

Rebuild the order-to-cash core service by service behind the same API contract, then switch the legacy system off.

  • The API contract from P1 means clients never notice the swap
06

What a Legacy API Discovery Sprint delivers

This page is one complete sprint, worked end to end on a real (sample) legacy system. A sprint on your system delivers the same six things, for your codebase:

✓

Evidence-backed analysis. Your application parsed by REA, with a behaviour graph and findings — every recovered rule traced to evidence in your own code.

✓

Reconstructed API specification. Endpoints, payloads, state machines and the full error contract, written down so any developer can build against your system.

✓

Runnable reference implementation. Working code that executes the recovered rules — like the live system on this page — so the spec is testable, not just readable.

✓

Verification suite. Fixed cases with known-correct answers, executed against the reconstruction, proving the port behaves like the original — figures included.

✓

Findings & risk report. The exposures the analysis surfaces — storage, audit, credit, security — rated, with the reasoning shown.

✓

Migration roadmap & handover. A phased plan from wrapping the legacy system to replacing it, plus a walkthrough call so your team owns the result.

Have a system only its code understands?

If a legacy application runs part of your business and nobody can say exactly what it does, a Discovery Sprint is the first step: one fixed-scope engagement that turns it into a documented, callable API — before you commit to any rewrite. Tell us what the system is and what it runs on, and we will tell you honestly whether it is in scope.

Email solidAtoms about a sprint
info@solidatoms.com · solidAtoms — software & IT services