---
id: arch.context-and-interfaces
title: System context and external interfaces
kind: practice
domain: architecture
description: Draw the system context, keep one inventory of every external interface with a contract or an owner for each, and classify every change to an interface as compatible or breaking before it ships.
version: 0.1.1
status: review
authority: uask
applies_to: [core]
sources:
  - title: C4 model — System context diagram
    url: https://c4model.com/diagrams/system-context
    license: CC-BY-4.0
    accessed: 2026-11-21
  - title: Google API Improvement Proposals, AIP-180 Backwards compatibility
    url: https://google.aip.dev/180
    license: CC-BY-4.0
    accessed: 2026-11-21
  - title: OpenAPI Specification (latest)
    url: https://spec.openapis.org/oas/latest.html
    license: Apache-2.0
    accessed: 2026-11-21
standards: [arc42 template 9.1 (October 2026)]
requires: [arch.architecture-description, arch.quality-attributes, config.semantic-versioning]
related: [arch.c4-model, arch.adr, ops.backups, process.release-spec, process.project-lifecycle, arch.fitness-functions]
last_reviewed: 2026-11-21
review_every: 6
---

## Summary

A system is as safe to change as its edges are well known. This item says how a project finds, lists and keeps true every
place where its system meets the world: the **system context diagram**, one **inventory of external interfaces** with a
contract or an owner for each, and a rule for changing an interface without breaking the people on the other side. The
inventory is section 3 of the Blueprint (`arch.architecture-description`). It matters most when a new system replaces a
live one, because that is when the interfaces that nobody wrote down stop working.

## Rules

### Context and inventory

- **R1.** Section 3 of the Blueprint MUST hold one inventory of external interfaces, with one row for each interface and a
  stable id (`I-1`, `I-2`, …) that is never reused, so that section 5, the release spec and the checks can refer to a row.
  The inventory MUST NOT be spread over several sections and MUST NOT be left to the diagram alone.
- **R2.** Every external system on the context diagram (`arch.c4-model#R1`) MUST have at least one row in the inventory.
  Every row MUST name a counterparty that appears on the context diagram or, when it is infrastructure such as DNS or the
  hosting account, on the deployment diagram (`arch.c4-model#R10`).
- **R3.** Each row MUST state its kind, its direction (inbound, outbound or shared), its counterparty, the owner on each
  side, its contract (where it is written, or "none"), and the check that shows it works: a test, a monitor, or a manual
  step with its date. A check that does not exist yet MUST say when it will.
- **R4.** The inventory MUST consider every kind of interface in the Guidance table and MUST say "none" for a kind that
  does not apply. It MUST NOT hold a secret; it names where a credential is kept and who rotates it.
- **R5.** An interface with the contract "none" MUST name a person who can answer for the other side, and the Blueprint
  MUST record the work to write the contract, unless the interface is one that the project cannot change (a hosting
  default), which the row says.

### Replacing a live system

- **R6.** When a system replaces a live one, the inventory MUST be built from what the old system does, not from what its
  documentation says: from its access and error logs, its DNS zone, the hosting panel, its scheduled jobs, its mail logs
  and its code. Each interface found MUST be carried over to the new system or recorded as dropped, with the date on which
  its owner was told.

### Contracts

- **R7.** A contract MUST say what is exchanged (a format and its fields, or a link to a schema), when (the trigger or the
  schedule, and the volume), how it is secured (authentication, the class of data, encryption), what happens on an error
  (status, retries, time limits, whether a repeat is safe), who owns each side, and the version of the contract.
- **R8.** A contract for an interface that the system offers SHOULD be machine-readable (an OpenAPI description for an HTTP
  interface, a schema for a file) and SHOULD be tested against the running system. For an interface that the system
  consumes, the row MUST record the version or the date of the counterparty's contract that the system was built
  against, and SHOULD keep a recorded sample of it as a test fixture.

### Compatibility and change

- **R9.** Every change to an interface MUST be classified as compatible or breaking before it is released, whether the
  project makes the change or the counterparty announces it. The classification MUST be recorded in the release spec
  (`process.release-spec`).
- **R10.** A change is breaking when code written against the old interface can stop working or work differently: a
  removal or a rename, a changed type, unit or default, a new required input, tighter validation, or a changed meaning of
  a value that is already in use. When it is unclear, the change MUST be treated as breaking.
- **R11.** A breaking change to an interface that others use MUST be made either as a new version that runs beside the old
  one, which takes a new MAJOR version of the contract (`config.semantic-versioning#R4`), or after the owner of every
  consumer has agreed to it in writing, with the date and the way back.
- **R12.** An interface that others use MUST NOT be removed without notice. Its row MUST record that it is deprecated, the
  date from which it will go and the confirmation of its consumers (`config.semantic-versioning#R10`).
- **R13.** A change to an interface MUST change its inventory row and its contract in the same pull request.

### Tiers

- **R14.** At the lightweight tier, the inventory MAY be a list with a name, an owner and a contract or "none" for each
  row, and R3 applies in that short form. At the standard tier, all the rules apply. At the high-assurance tier, every
  row MUST have an automatic check that fails when the contract is broken, and a compatibility review of each change by a
  verifier who did not make it.

## Guidance

### The kinds of interface

Walk the list for every project. The right column says what each kind tends to hide.

| Kind | What to look for |
|---|---|
| Public URLs and redirects | the addresses that other sites, search engines and bookmarks use, and the redirects from old addresses to new ones |
| APIs the system offers | who calls them, how they sign in, which versions are in use |
| Webhooks | calls that arrive without anyone asking: who sends them, how they are checked, what happens when one is missed |
| Calls the system makes | payment, courier, mail, maps, analytics: their versions, limits and costs |
| Scheduled jobs | cron jobs, queue workers and timers, and who is told when one stops |
| File exchange | imports and exports, with a format, a schedule and an owner on the other side |
| Mail | sending and receiving, the sender's records (SPF, DKIM, DMARC), and the mailboxes that other parties write to |
| DNS | every record of the zone, the certificates and their renewal |
| Hosting settings | redirect rules in a panel, the language version, limits, the firewall |
| Shared data stores | a database or a folder that another system reads or writes |
| Embedded parts | a widget on another site, a script that other pages load |
| Command line and configuration | commands that people or other programs run, and the files they read |

### Finding what the old system really does

A system that has run for years does things nobody remembers. Before a replacement is built, read the evidence:

- the **access log** for the most requested addresses, including the ones that are not on any page;
- the **error log** and the log of unanswered requests, which show what others still expect to find;
- the **DNS zone** and the **hosting panel**, row by row;
- the **cron tables**, and the mail log for what is sent and who writes in;
- the **code**, for outbound calls and for fixed addresses.

Each finding becomes a row, or a reason to drop it. Do this early in the Blueprint, not at cutover.

### What a contract says

A contract can be a page. It does not need a tool. It must be possible for two people who have not met to agree on what
is meant. The points are in R7. A machine-readable form, such as an OpenAPI description (the description language for HTTP
interfaces), also lets a test read it: the contract and the test then cannot drift apart.

A project that offers an interface to others can go further and freeze a snapshot of the contract at each release, then
fail the build when the running interface differs from it. A check like that needs a self-test: a copy of the interface
with one deliberate break must fail it. `arch.fitness-functions` says why.

### Is this change breaking?

The Google guidance on backwards compatibility distinguishes three kinds of compatibility, and they are a good checklist:

| Kind | The question | A breaking example |
|---|---|---|
| Source | Does code written against the old version still build against the new one? | a function in a client library is renamed |
| Wire | Do the old and the new talk correctly? | a field changes from a number to a string |
| Semantic | Does the new version still mean what the caller expected? | "total" used to include delivery and now does not |

Adding something optional is usually compatible. Adding something required, removing, renaming, and changing a type or a
default are not. A rename is a removal and an addition. The guidance itself says that the lists are indicative, and that
the judgement of what users expect decides the unclear cases. R10 takes the cautious side.

### Tailoring by tier

| Tier | Inventory | Contracts and checks |
|---|---|---|
| Lightweight | a list, one line a row, owner and contract or "none" | a check named for the ones that carry money or data |
| Standard | the full row (R3) for every kind in the table | a written contract for each row; a test or monitor for the important ones |
| High-assurance | as standard | an automatic check for every row; a second reviewer on each change |

## Explanation

**Why an inventory.** Reviews of past projects found their worst gaps at the edges of the system: a redirect that nobody
had listed, a webhook that was no longer received after the move, a cron job that stopped, a DNS record that was changed
and not recorded, a mail setting that moved the receipts to spam. None of them is in the code of the new system, so no test
of the new system catches them. A row for each, with an owner and a check, does.

**Why from behaviour, not from documents.** Documents say what was meant. Logs and settings say what happens. The two
differ more the longer a system has run, and a replacement keeps the documents' promises and breaks the logs'.

**Why a contract, even a short one.** Without it, each side learns what the other expects when it breaks. A contract
makes the expectation a thing that can be reviewed, versioned and tested, and the owner column says who to ask.

**Why classify changes.** The cost of a change is mostly paid by someone else, later. Asking "compatible or breaking?" before
release moves the question to when it is cheap. The three kinds of compatibility come from the Google guidance on API
design, which assumes consumers who cannot be made to update; where the consumers are the team's own code, the project
may relax them, and says so in the row.

**Why arc42 by reference.** The Blueprint's section 3, "Context and scope", follows arc42, and arc42 distinguishes a
business context from a technical one. The Hub cites the structure by reference (`arch.architecture-description#R13`) and
writes its own text: the inventory is the technical context in a form that a check can read.

## Examples

**Good.** A synthetic example: the interface inventory of a small UK web shop that sells refurbished bicycles, at the
standard tier. It replaces an older shop, so R6 applies: rows I-6 and I-7 were found in the old shop's logs and cron table,
and were in no document.

| Id | Interface | Kind and direction | Counterparty, owner | Contract | Check |
|---|---|---|---|---|---|
| I-1 | Redirect to the hosted payment page | outbound redirect | payment provider; lead | provider's integration guide, version 3 | staging test with the provider's test card, every release |
| I-2 | Payment result notice | inbound webhook | payment provider; lead | the same guide, signature header | replay of a recorded sample in the tests; monitor: alert if none arrives for 30 minutes in opening hours |
| I-3 | Nightly order export | outbound file, SFTP | accountant's bookkeeping package; owner | `contracts/order-export.md`, version 2 (columns, format, time) | a test compares the columns with the contract; the accountant imports the first file of each month |
| I-4 | Order and receipt mail | outbound mail | hosting provider's relay; lead | sender records SPF and DKIM; sends from the shop's domain | a weekly test message to a seed mailbox, headers read |
| I-5 | DNS zone | shared infrastructure | DNS provider; owner | the zone file kept in the repository | `dig` check on the release checklist |
| I-6 | Old product addresses (`/product/NN`) | inbound public URL | search engines, bookmarks; owner | a redirect map, 412 rows, from the old shop's access log | link check of the 200 most requested old addresses after each release |
| I-7 | Nightly job: dump and export | scheduled job | hosting panel; lead | the cron table, kept in the repository | monitor: the dump is newer than 26 hours |
| I-8 | Courier tracking | outbound API | courier; lead | the courier's OpenAPI file, version 3 (taken 2026-08) | a recorded sample response as a test fixture |

When the courier announces version 4, in which `tracking_no` becomes `tracking_number`, the change is classified before the
release: a rename is a removal and an addition, so it is breaking for the shop (R9, R10). The shop reads both names until
version 3 is switched off on the courier's date, which the row records (R12), and the release spec says so.

**Bad.** A Blueprint whose section 3 says "Integrations: payments, email, accounting". There is no owner, no contract and no
check for any of them, and the old shop's redirects, webhook and cron job are not named. After the cutover the paid
orders stay "pending" because the notice no longer arrives, the old product addresses answer "not found", and nobody knows
who to ask. Rules R1, R3, R5 and R6 are missed.

## Sources

- [C4 model — System context diagram](https://c4model.com/diagrams/system-context) — Simon Brown, CC BY 4.0; the scope of
  the diagram and what it shows. Accessed 2026-11-21.
- [Google API Improvement Proposals, AIP-180 Backwards compatibility](https://google.aip.dev/180) — CC BY 4.0 (page
  footer); the three kinds of compatibility and the list of changes, paraphrased. Accessed 2026-11-21.
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) — Apache License 2.0; the idea of a machine-readable
  contract for an HTTP interface. Accessed 2026-11-21.
- [arc42 template, edition 9.1 (October 2026)](https://docs.arc42.org/home/) — CC BY-SA 4.0; referenced for the order of
  the Blueprint's sections only; no text is adapted (`arch.architecture-description#R13`).
