A Harper-native catalog service and reference implementation for the Harper Application Architecture Benchmarks. This repo contains the application, its stack-neutral specification, and the conformance suite used by every implementation.
Pre-release. The specification has not passed its review gate, and no run is a publishable result. See project status and open work.
The benchmark catalog has 2 million products, 6.5 million purchasable SKUs, and eight fulfillment locations. Two endpoints exercise its read paths:
| Endpoint | Behavior | Caching |
|---|---|---|
POST /cart/:id/quote |
Reads the cart, products, variants, inventory, customer, promotions, shipping, and tax in roughly four to five dependent waves (60–150 reads). | Entity caches are allowed; response caching is forbidden. |
GET /product/:id?tier=®ion= |
Returns the product, variants, inventory, resolved price, review rollup, and related items. | Cache keys include tier and region. |
Background inventory and price writes target the same records, exercising cache coherence. Their latency is not a headline metric.
Eight logical entities are the source of truth: cart, customer, product, variant, inventory, location, promotion, and rate. Money uses integer minor units. SPEC.md defines pricing and promotion order; the data-model notes explain Harper's implementation.
Requires Node >=22. Install Git LFS to use the benchmark dataset; the development dataset is stored in plain git.
git lfs install
npm install
npm run devIn another terminal, load the committed development dataset and request a quote:
node scripts/load-dataset.mjs --scale dev
curl -s -X POST localhost:9926/cart/cart-000042/quote -H 'content-type: application/json' -d '{}'Do not run npm run seed for setup. It regenerates the pinned dataset. Read Contributing before changing it.
| Scale | Storage | Use |
|---|---|---|
dev |
Plain git | Local development and CI. Fits in memory; never a benchmark target. |
bench |
Git LFS, compressed | Benchmarking. Designed to exceed the target container's memory budget. |
Each dataset's MANIFEST.json defines its row counts and checksums. Every implementation loads the committed artifact and verifies its checksum; see dataset generation.
npm run check
npm run test:e2eSPEC.md defines the requirements, packages/spec holds the contract and registry, and e2e tests conformance. Requirements must be implementable on other stacks, including Fastify + Postgres + Redis.
Use the container workflow for benchmark runs. Read the harness limitations before interpreting any output.
| Document | Purpose |
|---|---|
| Specification | Stack-neutral requirements and review gate |
| Project plan | Status, priorities, blockers, and dated observations |
| Data model | Harper schema and indexing decisions |
| Dataset generation | Reproducibility and distribution rules |
| Repository structure | Deployment layout and dependency rules |
| Future work | Deferred scope and decisions |
| Contributing | Change and validation workflow |
Harper 5.2.12 · Node >=22 · TypeScript 7.0.2 · Apache 2.0