Backend Systems · Marketplace
A backend-first marketplace built around the failure modes CRUD demos avoid: concurrent inventory, idempotent orders, payment reconciliation, financial compensation, and operational evidence.
TypeScript · Node.js · Express · PostgreSQL · Prisma · Docker · k6
Neon Arsenal is my main backend engineering case study. The product is a marketplace for unique Counter-Strike 2 items, but the real subject is correctness: what happens when two buyers race for one listing, a payment provider succeeds while local state fails, a webhook is duplicated, or a process crashes halfway through a workflow.
At a glance
The functional roadmap is closed. The project is intentionally frozen as a portfolio case study; future architecture work requires a measured problem and a new engineering decision, not a larger technology stack.
Architecture
The current deployment is intentionally small: browser traffic reaches a Vite SPA, the SPA calls one Express API, and PostgreSQL owns business truth. External providers remain outside that trust boundary.
Client
Browser
Vercel
Vite SPA
Static frontend. Not a security boundary.
Render
Express API
Source of truth
PostgreSQL
Orders, listings, payments, ledger, idempotency, webhook and outbox state.
External boundaries
PayPal · Resend · cs2.sh
Untrusted integrations around the authoritative database state.
Redis, Kafka, SQS, a separate worker service, ECS/Fargate, RDS, and an ALB are not presented as live architecture because they are not part of the current canonical deployment.
What the design guarantees
Two concurrent buyers cannot both acquire the same unique listing.
Replaying the same valid order request does not create a second order.
Duplicate verified PayPal webhook delivery converges to a no-op after the event is persisted.
A lost payment webhook can be recovered through reconciliation against PayPal.
Captured money that cannot be fulfilled becomes an explicit refund obligation instead of hidden state drift.
Background side effects are coordinated through durable PostgreSQL records before a broker is justified.
Critical flows
01 · Concurrency
Buyer A
POST /orders
Buyer B
same listing
PostgreSQL conditional transition
ACTIVE → RESERVED
Winner
201 · order committed
Loser
409 · reservation conflict
The invariant lives in PostgreSQL, so correctness does not depend on which API process receives the request.
02 · Partial failure
PayPal capture COMPLETED
Local fulfillment path fails
Persist, do not hide
Durable refund obligation
Reconciliation / compensation
Payment truth is recoverable even when delivery is duplicated, delayed, lost, or interrupted halfway through a workflow.
03 · Durable side effects
The design keeps failure recovery explicit without adding distributed infrastructure solely for appearance.
Key engineering decisions
Decision
Keep unique-inventory correctness in conditional database state transitions.
Why
Process memory cannot safely coordinate competing buyers once more than one request or API replica is involved.
Decision
Keep one deployable API while domain boundaries remain explicit inside the codebase.
Why
The current product does not justify the operational cost of distributed ownership, networking, deployment, and recovery.
Decision
Treat webhooks as an unreliable signal, not the only path to payment truth.
Why
Delivery can be duplicated, delayed, or lost, so recovery must converge through persisted state and provider reconciliation.
Decision
Commit business state and outbox records together, then publish from an idempotent in-process job.
Why
A queue should arrive when measured backlog, replay, ordering, throughput, or independent-consumer requirements make it necessary.
Scaling path
Today
One modular-monolith API, one PostgreSQL source of truth, and idempotent in-process jobs.
Triggers
Database saturation, connection pressure, shared rate-limit needs, sustained job lag, or an outbox backlog that requires independent scaling.
Possible next steps
Redis for demonstrated shared coordination, a separate worker for independent background throughput, and a broker only when replay, ordering, throughput, or multi-consumer requirements justify it.
What was deliberately left unfinished
The final audit separates credible future improvements from portfolio theater. These limits remain visible because closing them would require a real product, operational, or scale requirement.
The customer cancellation/refund semantics for already-confirmed orders remain an explicit product decision rather than a hidden implementation gap.
Two legitimate recovery-depth improvements remain frozen because they do not create a duplicate economic effect in the current system.
Authenticated standalone reserve can still create TTL-bounded inventory griefing; closing it requires an explicit product/API decision.
Production OTLP reception, managed backup/restore, sustained production SLOs, HA, and multi-region capacity are not claimed because they were not proven.
Implementation notes
Unique listings are reserved through PostgreSQL transactions and conditional state transitions so concurrent buyers cannot both acquire the same item. Order creation is customer-scoped and idempotent, with the key, canonical request hash, order, and reservation effects converging in the database.
PayPal is treated as an unreliable external boundary. Capture, webhook processing, reconciliation, and compensation are designed around retries and partial failure. When money is captured but fulfillment can no longer complete, the system creates a durable refund obligation; seller financial history remains append-only through compensating entries.
The API exposes health and readiness probes, structured logs, request IDs, optional OpenTelemetry, runbooks, explicit shutdown behavior, reconciliation jobs, and database-backed invariants. Operational behavior is documented alongside application behavior rather than treated as deployment trivia.
The repository separates query-plan evidence from load-test evidence. PostgreSQL hot paths are measured with EXPLAIN ANALYZE and service timing, while k6 capacity runs use isolated disposable environments and record offered load, achieved RPS, latency, failures, dropped iterations, resource usage, and domain invariants. Controlled CI results are explicitly not presented as Render or production capacity.
Reviewer proof
The project has a dedicated review path, a canonical case study, a claim-to-proof index, an adversarial Senior Backend audit, and a bounded operational-proof phase.
A 5–15 minute path for hiring managers and Senior/Staff/Principal reviewers.
The canonical problem, decisions, hardest failure modes, trade-offs, and final engineering result.
A claim-to-proof map connecting invariants and decisions to implementation, tests, and operational evidence.
Adversarial review across 28 dimensions and 34 findings; all seven P0 findings were corrected and re-verified.
Bounded evidence for topology, probes, recovery, SLO targets, game days, runbooks, and explicit unknowns.
Final audit scope: 28 dimensions, 34 findings, seven P0 findings corrected and re-verified, unresolved P0 = 0. Remaining P1 limitations are documented and frozen rather than presented as completed work.
Engineering evidence
The reviewer path above is the fast route; these repository artifacts expose the deeper architecture, reliability, operations, and performance proof.
Canonical deployables, API components, external boundaries, and what is explicitly not live.
Checkout, concurrent reservation, webhook verification, and reconciliation flows matched to current code.
Documented failure scenarios and recovery behavior.
The invariants the implementation is expected to preserve under retries, concurrency, and partial failure.
This project is intentionally frozen. Further architecture work requires a measured problem, not a larger technology stack.
The live product shows the customer experience. The repository and architecture links show the engineering decisions, failure handling, and evidence behind it.
Next: Team Scrapbook