Technical specification

Order Service

In force on 19 November 2026. See it as of 30 June 2025

Computed from 9 decision records. 6 decisions are in force, 6 superseded and 1 proposed.

Persistence

Where order data lives and how it is kept consistent.

PostgreSQL 16 is the primary datastore for the Order Service.

The team already operates Postgres, and orders need multi-row transactions.

Identifiers

How records are keyed, and who is allowed to mint keys.

Primary keys are UUIDv7, generated by the application.

Time-ordered keys insert at the end of the index, and keep the client-side generation we already rely on.

Public API

The contract every client of the Order Service relies on.

The public API is REST over HTTPS with JSON request and response bodies.

Every consumer can call it without special tooling.

Authentication

How the service knows who is calling it.

All clients, browser and partner alike, authenticate with OpenID Connect access tokens issued by the corporate identity provider.

One mechanism, short-lived credentials, central revocation.

Domain events

How other services learn that an order has changed.

Events are written to an outbox table in the same transaction as the change, then relayed to the broker.

No event is published for a change that rolled back, and no committed change is missing its event.

Domain events are published to NATS JetStream.

Lighter to operate, with the durability we need.

Proposed, not yet in force

These records are filed but not accepted. The spec above will change when they are.

CockroachDB replaces PostgreSQL as the primary datastore.

Postgres-compatible wire protocol with multi-region writes.

How the decisions connect

Every arrow is one arc in the linkbase, read straight from links/supersession.xml. The ADR files themselves contain no links.

flowchart RL
  adr_0005_d1["ADR-0005"]:::fossil
  adr_0004_d1["ADR-0004"]:::live
  adr_0006_d1["ADR-0006"]:::live
  adr_0003_d1["ADR-0003 decision 1"]:::fossil
  adr_0003_d2["ADR-0003 decision 2"]:::fossil
  adr_0002_d2["ADR-0002 decision 2"]:::fossil
  adr_0007_d1["ADR-0007 decision 1"]:::fossil
  adr_0001_d1["ADR-0001 decision 1"]:::live
  adr_0001_d2["ADR-0001 decision 2"]:::fossil
  adr_0008_d1["ADR-0008"]:::live
  adr_0009_d1["ADR-0009"]:::proposed
  adr_0004_d1 -- replaces --> adr_0001_d2
  adr_0006_d1 -- replaces --> adr_0003_d1
  adr_0006_d1 -- replaces --> adr_0003_d2
  adr_0006_d1 -- replaces --> adr_0002_d2
  adr_0007_d1 -- replaces --> adr_0005_d1
  adr_0008_d1 -- replaces --> adr_0007_d1
  adr_0009_d1 -. proposes .-> adr_0001_d1

In force Superseded Proposed

6 superseded decisions, kept for the record

Primary keys are UUIDv4, generated by the application.

Partner systems authenticate with static API keys, rotated yearly.

Browser users authenticate with server-side sessions and a secure cookie.

Session state is stored in Redis with a 14-day sliding expiry.

Domain events are published with PostgreSQL LISTEN/NOTIFY.

Domain events are published to Apache Kafka.