ERP connector platform · proof of concept

One reusable integration for hundreds of independent NetSuite accounts.

A connector platform where a customer's credentials, base URL, field names and custom fields are data on a connection — not code branches. Four NetSuite APIs behind one interface, bidirectional sync that is resumable, idempotent, conflict-aware and observable.

▶ Open the docs page 🖥️ The running app — dashboard & API

Opens the live Omni app, signed in to the demo account, on the documentation page.

Nothing signs in until you click — the demo account is shared, so this page never logs you in on its own.

Demo sign-in if asked: … / …

Live platform · API docs (OpenAPI) · Prometheus metrics · Grafana dashboard · Repository

What the demo shows you

A landing pane and a documentation panel, each a note — one tab per document, so you can edit the docs and see the tab follow. The platform itself runs on the same box: the dashboard can start the scenario, inject faults and configure field mappings.

🔌 Four NetSuite APIs, one interface

SuiteTalk REST + SuiteQL (OAuth 2.0 / TBA)
SuiteTalk SOAP, TBA-signed envelopes
A RESTlet with a server-side delta window
SuiteScript: User Event push + Map/Reduce backfill

🛡️ Reliability is the product

Idempotent writes — a lost response cannot duplicate an invoice
Jittered retries that honour Retry-After
A per-connection circuit breaker
Conflict detection that refuses to guess

🧪 Evidence, not claims

125 tests against a fake NetSuite that verifies signatures
A 15-step scenario that breaks things on purpose
Fault injection: 429s, 5xx, a lost write, schema drift
Every step prints its own numbers

📈 Observable, and instrumented for real

Prometheus metrics from the platform itself
A Grafana dashboard scraped every 60s
Self-throttling, circuit state, stream leases, backfill progress
Ranked "what needs a human" view, not a wall of graphs

Run it yourself

The deployed instance is the same code, one bash deploy/install-vps.sh away. No NetSuite account required — the bundled simulator speaks the real wire protocol.

git clone <this repo> && cd erp-connector-poc
make install        # python 3.11+ venv + deps
make demo           # the whole scenario in ~3s: 15 steps, each printing its evidence
make serve          # fake NetSuite :8011 + API :8000 + dashboard

# or as services on a box (this is what erppoc.stage.lohan.me runs):
bash deploy/install-vps.sh --dry-run

Inside the demo account

Overview — what it is, and the brief-to-code mapping.
Architecture — the data model, sync design, and the failure mode behind each decision.
Talking points — the design decisions, the bugs the tests caught, and the trade-offs behind each choice.
SuiteScript — the code that runs inside the customer's own account.

The notes are real Omni notes: searchable, editable, and the page follows them.