cat ~/production/hardware-retail-platform-with-erp-sync/REPORT.md

Hardware Retail Platform with ERP Sync

Storefront, app and operations dashboard sitting in front of an external ERP, with data flowing both directions and staying consistent.

role Tech Lead, Backend and Integrationtimeline 2025category platformclient A regional hardware and building-supplies retailer

Problem

A hardware and building-supplies retailer already ran their business on an external ERP platform. They wanted a customer app, a storefront and an operations dashboard, but the ERP had to stay the system of record for products, stock and pricing. Two systems both accepting writes is where retail data goes wrong, so the sync had to be genuinely bidirectional rather than a nightly export.

Approach

Built the platform as a layer over the ERP rather than a replacement for it. Product, inventory and pricing flow in from the ERP; orders, customers and fulfilment events flow back out. Six roles including vendors and field technicians, bulk product import and export for catalogue operations, 124 endpoints across 17 collections. The integration itself was the coordination problem: I worked directly with the ERP vendor engineering team in another country, established what their system expected on each side of the exchange, and specified what they needed to build to meet ours.

Outcome

The retailer keeps their ERP as source of truth and gets a full customer-facing platform in front of it. Nine written guides ship with the codebase, including dedicated integration documentation, because a two-system contract that only exists in one engineer head is a liability.

124Route declarations
17Domain models
6Roles · customer, vendor, technician, sales, admin, superadmin
9Written guides
architecture --explain

How it's built

The ERP owns products, stock and pricing. The platform owns customers, carts, orders and fulfilment. Each side is authoritative in exactly one direction, which is what keeps a bidirectional sync from becoming a conflict engine.

ERP stays the system of record

The client business already runs on it. Replicating pricing and stock authority into a new system means two truths and a reconciliation problem nobody wants to own.

The platform depends on the ERP being reachable, so read paths cache and write paths are designed to be replayable.

Bulk import and export as a first-class path

Catalogue operations at retail scale are not done one product at a time. The largest single controller in the codebase is the import and export handler, which is the correct place for that weight to sit.

A bulk path needs its own validation and partial-failure reporting, separate from the single-record path.

related --by-stack

Adjacent systems

REL-001 / platform

E-commerce and ERP Backend

GraphQL commerce backend where the client rearranges their own storefront from the dashboard, over an inventory ledger with a single mutation point.

REL-003 / platform

Offline-First Pharmacy Platform

A pharmacy management system that keeps selling when the internet drops, then reconciles every till operation exactly once when it returns.