Spike First, ADR Second: Evidence and Rationale in System Design

contact@corebaseit.com (Vincent Bevia) — Mon, 24 Aug 2026 00:00:00 +0200

System design discussions often collapse into technology comparisons: Kafka or SQS, PostgreSQL or DynamoDB, synchronous or asynchronous, monolith or microservices. Those choices matter. They are not the whole problem.

Architectural work has two other obligations that diagrams do not carry by themselves:

How did the team gather enough evidence to decide?
Why was this option chosen over the alternatives that were still on the table?

Two lightweight practices address those obligations: Spikes and Architecture Decision Records (ADRs). They solve different problems. Used together under uncertainty, they form a simple decision loop — investigate, decide, document — that keeps future teams from treating intentional trade-offs as accidents.

This post defines each practice, shows how they connect, and grounds the pattern in a payment-system example: asynchronous refund processing with external partner latency, retries, and idempotency. The POS framing draws on POINT OF SALE ARCHITECTURE (the book), especially Chapter 6 (architectural principles and separation of concerns), Chapter 14 (offline / store-and-forward queues, retries, idempotency), and Chapter 15 (backend timeouts, safe retries, STAN/RRN correlation).

Claims to keep separate

Confirmed practice and sources:

An ADR is a short record of an architecturally significant decision, typically covering context, decision, and consequences (Michael Nygard, 2011; Thoughtworks Technology Radar — Lightweight Architecture Decision Records).
A Spike (from Extreme Programming) is a time-boxed investigation used to reduce technical uncertainty before committing to an implementation path.
Payment backends that retry across unreliable partners must assume duplicate delivery and enforce idempotency; store-and-forward and authorization retries make this explicit (the book, Ch. 14–15).
Architecture is largely trade-off analysis among competing characteristics, not selection of a universally “best” technology (Richards & Ford, Fundamentals of Software Architecture).

Interpretation (practitioner method):

“Spike first, ADR second” is a useful default under uncertainty. It is not a rule that every ADR requires a Spike, or that every Spike must produce an ADR.
The refund / SQS example below is illustrative. Your broker, ordering needs, and partner SLAs will differ; the method transfers, the product choice may not.

Architecture contains uncertainty

Consider a refund processing path where an external GDS or airline API can be slow or temporarily unavailable:

Asynchronous processing is a reasonable starting assumption: the external system should not block the merchant-facing API indefinitely. That assumption does not answer the next layer of questions:

Managed queue (for example SQS) or log-oriented broker (for example Kafka)?
What ordering guarantees are actually required — global, per refund, or none?
Can messages be delivered more than once?
How do retries, dead-letter queues, and worker crashes interact?
Is replay a real requirement for this workflow, or only an attractive feature?
What throughput and latency budget does the partner path impose?

Drawing another box on the diagram papers over those unknowns. Naming the unknowns is more useful: the team does not know yet. That is the entry condition for a Spike.

In POS systems the same pattern appears whenever the stack sits between a deterministic payment state machine and an unreliable upstream — store-and-forward sync, scheme timeouts, late issuer responses, and duplicate suppression via STAN/RRN or dedicated idempotency keys (the book, Ch. 14–15; see also double charging).

Spike: reduce uncertainty before committing

A Spike is a time-boxed technical investigation aimed at a specific question. It is not the production implementation. It may include a small proof of concept, a benchmark, an integration test against a partner sandbox, latency or throughput measurement, or structured comparison of two or three alternatives.

The Spike starts with a question, for example:

Can a managed FIFO/work-queue service meet the ordering, retry, and throughput requirements of our refund processing path, if consumers are designed for at-least-once delivery?

Give the investigation a hard time box (often one to three days). Structure the work so findings are reusable:

A useful Spike ends with evidence, not preference. Typical findings for this kind of path:

Throughput is adequate for projected refund volume.
Ordering is required only per refund identifier, not globally.
Duplicate delivery must be assumed; workers need idempotent handlers.
Retries plus a dead-letter path cover the partner failure modes in scope.
Log replay is attractive but unnecessary for this workflow’s recovery model.

The decision can now rest on measured constraints. Months later, though, someone will still ask why the queue technology is what it is. Evidence that lived only in a chat thread or a demo branch will be gone. That is the ADR’s job.

ADR: preserve the reasoning behind the decision

An Architecture Decision Record is a short document that records one architecturally significant decision and the forces around it. Nygard’s original shape is Status, Context, Decision, and Consequences. Many teams add Alternatives Considered; that extension is useful in payment systems where several brokers or sync models are always in play.

A lightweight example:

ADR-017: Use a managed work queue for refund processing

Status
Accepted

Context
Refund processing is asynchronous. The external GDS can be slow or
unavailable. Workers can crash mid-flight. At-least-once delivery
must be assumed; duplicate refund side effects are unacceptable.

Decision
Use a managed work queue (SQS-class) for refund jobs, with
idempotent consumers keyed by refund id (and STAN/RRN where the
payment network is involved).

Alternatives considered
- Log-oriented broker (Kafka-class) for replay-first design
- Self-managed broker (RabbitMQ-class)
- Synchronous refund calls from the API

Consequences
+ Managed operations and built-in retry / DLQ patterns
+ Simple worker model aligned to job processing
- Consumers must be idempotent under duplicate delivery
- Weaker fit if full event replay becomes a primary requirement

The decision line alone is cheap; the architecture diagram already shows the queue. The durable value is context, alternatives, and accepted downsides. Without that, a later engineer can “fix” an intentional trade-off — for example by introducing a replay-heavy broker when the original Spike showed replay was out of scope.

Spike + ADR as a loop

Compact form:

Spike = investigate.
ADR = decide and document.

A Spike does not always produce an ADR. An ADR does not always require a Spike. Some decisions are constrained enough that experimentation would waste calendar time. When uncertainty is material — partner behaviour, ordering, duplicate risk, certification impact — the combination is hard to beat on cost relative to the confusion it prevents.

Why diagrams are not enough

System diagrams show what exists:

API → queue → workers → PostgreSQL / partner API

They do not naturally show why it exists: why this broker, why asynchronous rather than synchronous, why pessimistic rather than optimistic concurrency, why REST rather than an event bus for a given boundary.

A working architecture therefore has a second layer behind the boxes:

In POS application design, Chapter 6’s principles — separation of concerns, deterministic state management, security by design, targeted observability — are the kinds of constraints that should appear in ADR context when a team chooses how refunds, reversals, or store-and-forward sync are structured (the book, Ch. 6, 14).

Architecture is trade-off work

Richards and Ford argue that architecture is fundamentally about understanding and balancing trade-offs. There is rarely a universally correct choice. A log-oriented broker is not simply “better” than a work queue. Microservices are not simply “better” than a modular monolith. Event-driven flows are not simply “better” than synchronous request/response.

Each option improves some characteristics and degrades others. The productive question shifts from “What is the best technology?” to “Given our requirements and constraints, which trade-offs are we willing to accept?”

Spikes surface those trade-offs under load, latency, and failure. ADRs make the accepted set explicit. Software Architecture: The Hard Parts pushes the same style into decomposition, data ownership, coupling, orchestration versus choreography, and evolution — problems that rarely have perfect answers, only recorded compromises.

Payment systems sharpen the stakes: a wrong retry policy can double-post; a missing idempotency key can create chargebacks and reconciliation debt; a store-and-forward design that ignores scheme and liability constraints can pass a demo and fail certification (the book, Ch. 14–15).

Keep both practices light

Neither practice needs bureaucracy.

A Spike answers a question inside a time box. It should not become an open-ended research programme.
An ADR preserves a decision in a page or two. It should not become a 40-page design specification.

Question → Spike → Evidence → Trade-offs → Decision → ADR → Architecture

Months later, when someone asks why the system looks the way it does, the answer need not be tribal memory about an engineer who left. The reasoning is still in the repository, next to the code that implements it.

References

Nygard, M. — “Documenting Architecture Decisions,” Cognitect blog, 15 Nov 2011. https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Thoughtworks Technology Radar — Lightweight Architecture Decision Records (Adopt). https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
Fowler, M. — “Architecture Decision Record” (bliki). https://martinfowler.com/bliki/ArchitectureDecisionRecord.html
Richards, M. & Ford, N. — Fundamentals of Software Architecture: An Engineering Approach (2nd ed.). O’Reilly.
Ford, N., Richards, M., Sadalage, P. & Dehghani, Z. — Software Architecture: The Hard Parts. O’Reilly.
Extreme Programming / Kent Beck — Spike Solution (time-boxed investigation before committing to an implementation).
Bevia, V. — Point-of-Sale Systems Architecture, Chapters 6, 14, and 15: https://corebaseit.com/my-books/
Corebaseit — Double charging; Offline EMV vs store-and-forward.

System-Design on Corebaseit — Design System Engineering · POS · Payments · Security