Architecture Decision Records — AI Learning

How decisions are recorded

Records move from Proposed to Accepted, and a replacement supersedes them.

Each significant decision is an architecture decision record (ADR): a short, dated document with its status, the context that forced the choice, the decision, its consequences and the alternatives rejected. ADRs are kept in the repository beside the code, reviewed like code, and never edited after acceptance; a changed decision gets a new ADR that supersedes the old one.

Decision log

ADR	Decision	Status	Date
ADR-001	Use a DAG (Directed Acyclic Graph) orchestrator for the invoice pipeline	Accepted	2026-08-04
ADR-002	Deterministic rules decide matching and approval; models only extract and explain	Accepted	2026-08-06
ADR-003	All enterprise system access goes through an MCP (Model Context Protocol) gateway	Accepted	2026-08-11
ADR-004	Ground contract and policy answers in RAG (Retrieval-Augmented Generation) with access filters and mandatory citations	Accepted	2026-08-13
ADR-005	Approval bands and human decisions for exceptions	Accepted	2026-08-18
ADR-006	Model tiering behind one vendor-neutral interface	Accepted	2026-08-20
ADR-007	Use the ERP (Enterprise Resource Planning)'s native approval workflow rather than building one	Proposed	2026-10-09

Routing comes from the amount, so the same rule applies to every invoice.

Status values: Proposed, Accepted, Superseded. Dates are the day the status last changed.

The records

ADR-001 Accepted 2026-08-04

Use a DAG orchestrator for the invoice pipeline

Context: The pipeline has fixed stages with retries, timeouts and a clear audit requirement. An autonomous agent loop would make ordering and retries implicit and harder to audit.
Decision: Model the pipeline as a directed acyclic graph run by a workflow orchestrator. Each node is an idempotent task with a declared input, output, retry policy and timeout. Agents run only inside the exception node.
Consequences: Run history and retries come from the platform, not from prompts.

Every node is testable in isolation.

Adding a stage means adding a node and an edge, not rewriting a prompt.
Alternatives considered: A single agent controlling everything (rejected: opaque ordering, hard to bound cost)

A hand-rolled queue with cron jobs (rejected: retries and visibility built by hand)

ADR-002 Accepted 2026-08-06

Deterministic rules decide matching and approval; models only extract and explain

Context: Matching and approval are money decisions that auditors must be able to reproduce. Models are probabilistic and their output varies between runs.
Decision: Three-way matching, tolerances and approval bands are code with unit tests and versioned rules. Models are used for document classification, field extraction, and drafting an explanation for a human. A model never posts, approves or pays.
Consequences: Matching results are reproducible for the same inputs.

Rule changes go through code review.

Model upgrades cannot silently change a payment decision.
Alternatives considered: Let the model decide matches (rejected: not reproducible, hard to audit)

ADR-003 Accepted 2026-08-11

All enterprise system access goes through an MCP gateway

Context: Agents and workers need to read and write the ERP, vendor master, POs (Purchase Orders), receipts and approvals. Giving each its own credentials and client code would spread access control across the system.
Decision: Expose enterprise capabilities as MCP tools behind one gateway. The gateway authenticates the caller with SSO (Single Sign-On), checks scopes per tool, applies policy and rate limits, filters output, and writes an audit record. Backend credentials exist only in the gateway.
Consequences: One place to review, revoke and audit tool access.

Agents get capabilities, never credentials.

A new backend means a new tool definition, not a new integration in every agent.
Alternatives considered: Direct database access for agents (rejected: broad, unaudited)

Per-agent API (Application Programming Interface) clients (rejected: credential sprawl)

ADR-004 Accepted 2026-08-13

Ground contract and policy answers in RAG with access filters and mandatory citations

Context: Exceptions often turn on a clause in a supplier contract or a sentence in the AP (Accounts Payable) policy. Answers without a source are not acceptable to finance.
Decision: Index contracts, policies and pricing schedules at clause level with vendor, date and access metadata. Use hybrid retrieval (vector and keyword), filter by tenant, vendor and access group at query time, rerank, and require every claim in an answer to cite a retrieved passage. If no passage supports an answer, return no answer.
Consequences: Answers are checkable against the source.

Access is enforced at retrieval, not by trusting the prompt.

Clause-level chunks cost more to index but cite precisely.
Alternatives considered: Whole-document retrieval (rejected: citations too coarse)

Fine-tuning on contracts (rejected: stale, uncitable, and changes are slow)

ADR-005 Accepted 2026-08-18

Approval bands and human decisions for exceptions

Context: Finance wants automation for routine invoices and a named human for anything unusual. The threshold cannot depend on how confident a model feels.
Decision: Approval routing is by amount band and exception type, as a table in configuration. Clean matches up to $5,000 approve automatically. $5,000–$25,000 needs the AP Manager. Above $25,000 needs the Finance Director. Every exception needs a human decision whatever the amount.
Consequences: Routing is explainable from the table.

Changes to limits are reviewed like any financial control.

Some clean invoices still wait for a person above the band.
Alternatives considered: Confidence-based auto-approval (rejected: confidence is not authority)

ADR-006 Accepted 2026-08-20

Model tiering behind one vendor-neutral interface

Context: Classification is simple and high-volume. Extraction from poor scans and exception reasoning are harder. Locking the system to one model vendor would make cost and quality changes expensive.
Decision: A small, low-cost model classifies documents. A frontier model handles extraction of difficult documents and exception reasoning. All calls go through one internal model interface that handles retries, token budgets, logging and provider selection, so either tier can change without touching pipeline code.
Consequences: Most volume runs on the cheapest adequate model.

Provider changes are a configuration change, validated by the evaluation set.

The interface is one more component to maintain.
Alternatives considered: Single frontier model for everything (rejected: cost at volume)

Direct vendor SDK (Software Development Kit) calls in each node (rejected: no single place for budgets or logging)

ADR-007 Proposed 2026-10-09

Use the ERP's native approval workflow rather than building one

Context: The ERP already records approvals and their audit trail for finance. A separate approval service would duplicate that and need its own controls.
Decision: Proposed: approvals are requested through the ERP's approval workflow via the approvals tool in the MCP gateway, and the DAG waits for the decision event. Not yet accepted: the ERP's event API must be confirmed for the bands in ADR-005.
Consequences: Reuses finance's existing controls and audit trail.

Depends on ERP event capability that is not yet verified.

Decision pending a spike against the ERP sandbox.
Alternatives considered: Build a standalone approval service (deferred: duplicates controls)

The template

Every ADR follows the same five headings, so reviewers know where to look:

docs/adr/template.md

# ADR-NNN: <decision in one line>

Status:  Proposed | Accepted | Superseded by ADR-MMM
Date:    YYYY-MM-DD

## Context
What forces are at work, including constraints and what is unknown.

## Decision
What we will do, in the present tense.

## Consequences
What becomes easier, what becomes harder, and what we must now watch.

## Alternatives considered
What we rejected, and why.

Build this for your business

This example uses a generic invoicing system, but the same pattern — orchestrated steps, governed tools, grounded knowledge and a documented lifecycle — fits most back-office processes. We can scope a pilot on your own documents and systems.

Book a discovery call