00 Example · ADR
Architecture decision record
ADR-0003, the fictional Lanefold decision to prefer carrier REST APIs over EDI that DD-0021 cites, with context, considered options, outcome and consequences in MADR fields.
No credit card required
01 Markdown
Copy the markdown
# ADR-0003 Prefer carrier REST APIs over EDI where available
Fictional example from Lanefold, a made-up freight company. ADR-0003 is the decision that the DD-0021 example and the tech lead use case cite. Paste each section into the matching field of a new decision record, or have an agent create it over MCP with create_adr.
## Context
ADR-0002, Tender loads over EDI 204 before carrier APIs, chose EDI 204 tenders for every carrier because it reached the carriers Lanefold already integrated with and reused the established tender workflow. Its recorded downside was that delayed acknowledgements complicate the tender deadline. Since then, a growing share of active carriers offer REST tender APIs that acknowledge within seconds, while EDI acknowledgements still arrive minutes later and sometimes out of order. Dispatchers re-tender API-capable loads by hand to work around the wait.
## Deciders
Priya Raman (dispatch engineering), Maya Chen (carrier integrations).
## Considered options
### Keep EDI 204 for every carrier
- Pro: one integration path, already monitored.
- Pro: no per-carrier configuration.
- Con: acknowledgement latency stays at minutes for carriers that could answer in seconds.
- Con: dispatchers keep re-tendering by hand.
### Prefer the carrier's REST API where it offers one, EDI otherwise (chosen)
- Pro: API carriers acknowledge in seconds, which lets Dispatch Service use a shorter tender window for them.
- Pro: EDI carriers keep working unchanged.
- Con: two tender paths to monitor and test.
- Con: the carrier's channel becomes configuration that someone has to keep current.
### Replace EDI with REST for every carrier
- Pro: one modern path.
- Con: most carriers have no REST tender API, so loads to them would have no tender path at all.
## Decision outcome
Carrier Gateway tenders through a carrier's REST API when the carrier record has one configured, and through EDI 204 otherwise. Each tender carries the channel it went out on. ADR-0002 is superseded by this record. Its constraint still applies to EDI carriers: their acknowledgements arrive late, which is why DD-0021 keeps a 15-minute window for EDI and shortens it only for API carriers.
## Consequences
- Dispatch Service needs a per-channel tender window, recorded as a separate change in DD-0021.
- Carrier onboarding gains a step: record whether the carrier has a REST tender API.
- Monitoring covers two tender paths. Alerts on acknowledgement latency need a per-channel threshold.
- What happens when a carrier accepts after its window closes is still open as Q1 on DD-0021 and may become its own decision record.
This example is fictional. Lanefold is a made-up freight company, and the carriers and people in it don't exist. Use the shape, not the content.
Put it in ArchDocs
- Open Decisions in the sidebar and select New decision. Enter the title and check the decision date.
- Paste the Context and Deciders sections into Context.
- Add each considered option under Considered options with its pros and cons, and mark the chosen one Chosen.
- Paste Decision outcome and Consequences, then select Record decision.
- Under Linked records, link the objects and documents the decision affects. The object page then lists the decision.
Over MCP, an agent can create the record with create_adr and link it with update_adr. A new decision starts as Proposed; changing its status, and superseding an earlier decision with this one, are on Business and Enterprise. The decisions guide covers status changes and supersede links.
02 Start
Write the real one
No credit card required