Skip to content

Architecture Decision Records (ADRs)

This directory records the significant architecture decisions behind the POS Integration Service — what we decided, why, and what it commits us to.

An ADR is a short, immutable document. We write one whenever a decision constrains future integration work: a new cross-cutting mechanism, a schema boundary, a workflow every new provider must follow, or a choice we expect someone to later ask "why did we do it this way?" about.

Day-to-day "how" lives in the guides (architecture, contracts, onboarding). ADRs capture the "why".

When to write an ADR

Write one when a change:

  • introduces or removes a cross-cutting mechanism (e.g. the JS adapter runtime, the dispatch pipeline);
  • draws or moves a boundary (central vs per-tenant data, which table owns what);
  • defines a process every future provider must follow (e.g. onboarding);
  • supersedes a previous decision.

Do not write one for routine bug fixes, copy edits, or a single provider's field mapping — those belong in that provider's guide.

Process

  1. Copy _template.md to NNNN-short-title.md using the next free zero-padded number.
  2. Open it with status Proposed; fill in Context / Decision / Consequences / Alternatives.
  3. Once agreed, change the status to Accepted and add the row to the index below.
  4. ADRs are immutable once Accepted. Don't rewrite history — if a decision changes, write a new ADR and mark the old one Superseded by NNNN (and link forward).

Statuses: Proposed · Accepted · Superseded by NNNN · Deprecated.

Index

ADR Title Status
0001 JS adapter scripts in centraldb, executed via goja Accepted
0002 Two-tier order-dispatch pipeline (standard + transformer) Accepted
0003 Central vs per-tenant schema boundary Accepted
0004 Provider knowledge packs live in this repo (consolidate now) Accepted
0005 Standard AI-assisted framework for onboarding a new POS Accepted
0006 OAuth token management (config token shape + refresh-before-execute) Accepted
0007 Product field ownership on re-sync + async image→GCS pipeline Accepted
0008 items_flat regeneration: kds-owned, triggered per-outlet at publish Accepted
0009 Storefront category grouping uses the V1 model; publish projects sections into it Accepted
0010 Refactoring hygiene and logging conventions Accepted

ADRs 0001–0003 are retroactive — they document decisions that were already built into the service before this directory existed, so the record is complete.