MetalDesk — a reference precious-metals trading platform

This site documents a reference architecture for a precious-metals e-commerce and trading platform — live spot pricing, a shopping cart with a manager-mediated handoff for large orders, and multi-provider payments — built as a from-scratch, MIT-licensed monorepo targeting GCP, with every external dependency mocked at the boundary.

It exists to demonstrate a specific piece of engineering judgment: how to design a small multi-service system so that a well-known failure mode (a shared domain model that forks because nobody actually depends on it) is structurally prevented rather than relying on discipline to avoid it. See Lessons Learned for the failure mode itself, and Architecture for how the module boundaries here respond to it.

Start here

Page	What’s in it
Business Requirements	The functional and business-rule spec this system implements — catalog, checkout, tiered fulfillment, payments.
Architecture	C4 system context and containers, the domain model, the payment-provider abstraction, and the GCP reference deployment.
Modernization Plan	The build order — from an empty repository to a deployed system — and the standards held constant across every phase.
Lessons Learned	The engineering failure modes this design exists to prevent, stated generally rather than as a specific case study.
ADRs	The decisions that were actually weighed against an alternative, with their accepted costs written down alongside their benefits.
Meeting Notes	Executive summaries and action items from project meetings — the process decision record, alongside the ADRs’ architecture decision record.

Provenance

See the repository README for what this project is derived from and what it deliberately is not.