Spare Parts Marketplace

Overview#

A multi-tenant B2C marketplace for automotive spare parts, connecting many merchants to many customers through a shared catalog, wallet and order system. This is a private, in-progress commercial codebase, so this case study is architecture-first rather than screenshot-driven — the engineering decisions are the interesting part.

Problem#

Spare-parts retail has fragmented inventory (the same physical part listed differently by every seller), cash-sensitive settlement (merchants need to trust the platform's numbers), and optional integrations (payment gateways, ERP systems, WhatsApp notifications) that shouldn't be allowed to take the core system down if they fail or aren't configured for a given tenant.

Solution#

The backend is a modular monolith in NestJS, organized as Clean Architecture / DDD: every module has its own domain / application / infrastructure / presentation layers with strict boundaries, and every optional third-party integration sits behind an anti-corruption layer so the core marketplace runs fully independent of any external service being available. Financially, the system is ledger-first: wallet and inventory balances are never trusted as raw mutable numbers — they're derived from append-only ledgers, which is what makes the numbers auditable and the recovery scripts possible.

Architecture#

Three Next.js dashboards (admin, merchant, customer) and a Flutter customer app all talk to the same NestJS API, sharing a common design-system package on the web side. Real-time state — order status, wallet balance, merchant notifications — is pushed over WebSockets rather than polled. PostgreSQL (via Prisma) is the system of record; Redis and BullMQ handle background jobs, from commission calculation to the scheduled batch job that powers product recommendations.

Features#

• Ledger-first wallet & inventory — append-only ledgers as the single source of truth, with a rule-based commission engine scoped per category, brand or store.
• Auditable withdrawal workflow — multi-state, with automated invoice generation, sequential numbering, and QR-based pickup verification.
• Order lifecycle state machine — merchant confirmation → payment → fulfillment → pickup, with automated timeout/expiration handling, a dispute-resolution workflow, and partial/full refunds that generate credit notes.
• Cross-merchant product search — canonical-part deduplication across sellers, vehicle-fitment filtering, and faceted search.
• Recommendations — frequently-bought-together and alternative/cross-reference parts, driven by real purchase-history analytics computed in a scheduled batch job.
• Data-integrity tooling — automated, idempotent consistency-check and repair scripts that continuously validate cached balances, stock and invoices against their ledgers of record.

Development Process#

Architecture came first: domain boundaries and the anti-corruption layer were defined before any integration was wired up, specifically so payments, ERP and WhatsApp could be added, swapped or disabled per tenant without touching core order or wallet logic. Data-integrity tooling was built alongside the ledger system from day one rather than retrofitted after a discrepancy was found in production.

Challenges#

Keeping three separate frontends (admin, merchant, customer) consistent while iterating quickly meant investing early in a shared design-system package rather than letting each dashboard drift. Getting the order state machine right — particularly timeout/expiration and partial refunds interacting with the ledger — required modelling every transition explicitly rather than relying on implicit status fields.

Results#

A production-facing marketplace with three live dashboards, real-time order and wallet updates, and a financial core that reconciles itself automatically rather than depending on manual audits.

Future Improvements#

Expanding the anti-corruption layer to support additional payment providers per region, and extending the recommendation engine with collaborative filtering on top of the existing purchase-history analytics.