cat ~/production/e-commerce-and-erp-backend/REPORT.md

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.

role Tech Lead, Backend Architecturetimeline 2025category platformclient A multi-location retail business

Problem

A retail client needed inventory across locations, an ERP-grade stock ledger, a content surface, and crucially the ability to change how the storefront looks without asking an engineer. Every layout change becoming a support ticket was the actual problem to solve.

Approach

Chose GraphQL over REST specifically because the client requirement was that the frontend decides what it renders. Fourteen GraphQL modules over nineteen models let the storefront query exactly the shape a client-configured layout needs, rather than the backend hardcoding a response per page. Stock has exactly one mutation point, so every quantity change writes an audit row and the ledger is complete by construction.

Outcome

The owner reconfigures storefront sections from the dashboard with no deploy. Inventory is auditable to the individual movement, with deduplicated low-stock alerting.

19Domain models
14GraphQL modules · typedefs and resolvers
14Role scopes · across 6 roles
AR / EN / KULocales
architecture --explain

How it's built

GraphQL-first, modular by domain. Nineteen models, fourteen typedef and resolver pairs, nine services. Six roles resolved against fourteen distinct scopes. Trilingual throughout.

GraphQL over REST for the storefront

The client controls layout, so the frontend has to ask for arbitrary shapes. With REST that means over-fetching everything or shipping an endpoint per layout change, which is exactly what the client was paying to avoid.

N+1 resolution has to be actively managed, and the team needed bringing up to speed on schema design before writing resolvers.

One mutation point for stock, one ledger row per movement

Quantity changes in exactly one function, which writes a signed movement with the resulting balance. Nothing else touches quantity, so the audit trail cannot drift from reality.

Every stock path routes through one function, a bottleneck by design and the reason the ledger is trustworthy.

Deduplicated low-stock alerts with a reset threshold

An alert fires once on crossing below the threshold and the guard clears only when stock climbs back above it, so admins get a signal instead of a stream.

One extra field per stock level, cheap next to alert fatigue.

related --by-stack

Adjacent systems

REL-001 / platform

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.

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.