Skip to content

0004. Provider knowledge packs live in this repo (consolidate now)

  • Status: Accepted
  • Date: 2026-06-09
  • Deciders: POS Integration team

Context

Integration knowledge for the first providers was captured in separate per-provider repositories — expert-revelsystem, expert-deliverect, expert-lightspeed. They share an identical structure (README / api-docs / field-mapping / changelog / samples/) and were a good way to gather provider facts. But maintaining a repo per provider scales badly: cross-provider conventions drift, the structure is duplicated verbatim, and there is no single place to look when onboarding the next POS. Lightspeed is already a stub that never got backfilled.

At the same time this service has grown the machinery to consume such docs directly: central.knowledge_bases registers GitHub repos of POS API docs per provider_slug, and the AI generation pipeline (ADR 0005) reads them when producing adapter scripts. In other words, the expert-* repos already function as knowledge bases.

We need to decide where provider knowledge lives going forward.

Note on history. This ADR initially proposed a hybrid stance — document new providers here but leave the expert-* repos in place and migrate later. On review we chose to consolidate now: comparing expert-revelsystem against the in-repo revel.md showed the separate repo was actually more complete (full sync_products, samples, verification log) and even corrected a bug in the in-repo guide (it documented Revel prices as cents; they are decimal). That made "consolidate now" a correctness win, not just tidying.

Decision

pos-integration-service is the single source of truth for all provider integration knowledge — existing providers and new ones alike.

  1. Each provider gets one all-topics knowledge pack at docs/guides/adapters/<slug>.md, following the shape of adapters/revel.md, with sample fixtures under docs/guides/adapters/samples/<slug>/.
  2. The expert-revelsystem / expert-deliverect / expert-lightspeed repos are migrated now and then deprecated. Their content is folded into the corresponding knowledge pack; each repo's README is replaced with a deprecation notice pointing to this repo, and the repo is frozen (no further edits). Migrated in this pass: Revel (full), Deliverect (full, grounded in the kds production integration), Lightspeed (stub — least complete).
  3. A knowledge pack and a knowledge base are complementary. The Markdown pack is the human-curated, reviewed reference; a central.knowledge_bases entry (a repo of raw API docs/samples) is machine-readable fuel for AI generation. New providers may still register a docs repo as a knowledge base, but the curated pack lives here.

Consequences

Positive

  • One place to look and to keep conventions consistent, for every provider.
  • Corrects drift/errors discovered during the merge (e.g. the Revel price-format bug) and pulls verified samples + verification logs into the repo.
  • No more parallel-repo maintenance.

Negative / costs

  • A one-time migration effort (done in this pass) and the loss of per-provider repo git history for the docs (the source repos remain readable until archived).
  • Sample fixtures now ship as static assets in the docs site — acceptable, and useful for downloads.

Follow-ups

  • Archive the three expert-* repos once the deprecation notices are merged.
  • Optionally register any provider's external API-docs repo as a central.knowledge_bases row for the generation pipeline.

Alternatives considered

  • Hybrid / defer (the original stance) — keep the expert-* repos and migrate later. Rejected once the comparison showed the separate Revel repo was more accurate than the in-repo guide; deferring would have left a known bug in place.
  • Keep one repo per provider — status quo. Rejected: doesn't scale, drifts, and leaves no single onboarding home.

References