Architecture decision records for client platforms

An architecture decision record is one page. It captures the context a decision was taken in, the options that were on the table, what was chosen and what it costs. Plus a status: proposed, accepted, superseded. That is the complete format.

The distinction that matters is the one from documentation. Documentation describes what applies. An ADR describes why it applies, which alternative was discarded and what was accepted in exchange. A console can export the first. The second exists only if somebody writes it down.

Why the endpoint platform in particular

Endpoint configuration rarely arrives in one piece. It grows over years, along migrations, acquisitions, incidents and requests from individual departments. Every single setting was a decision at some point. Two years later it is a given, and nobody knows any more whether it reflects a security requirement or a workaround from back then.

Three situations make that expensive. A security incident where it has to be established whether a configuration was cause or coincidence. An audit where the question is not whether a setting is applied but on what basis. And a change of staff, after which the new owner inherits an environment they cannot explain and therefore dare not touch.

The result is the same in all three cases: the platform is no longer governed, it is preserved.

What ten ADRs cover for an Apple platform

In practice an architecture engagement for an Apple fleet comes down to roughly ten decisions that justify this effort. Everything below that is configuration and belongs in the operations documentation.

• Identity binding: Platform SSO against the Kerberos legacy, with the consequences for sign-in and password synchronisation.
• Device trust: certificate based against password rotation, including issuance and revocation.
• Management model: declarative target states against command-based profiles.
• Apple accounts: Managed Apple IDs, federation with the corporate IdP, handling of personal accounts.
• Enrollment path: automated through Apple Business Manager against manual routes, with an exception rule for existing stock.
• Update control: deadlines, windows, deferral, and who approves a deferral.
• Baseline origin: BSI IT-Grundschutz or CIS, and how deviations are handled.
• Roles in the management plane: who configures, who approves, who only reads.
• Exceptions: who requests, who approves, how long they hold, where they are visible.
• Recovery: encryption keys, emergency access, loss and decommissioning.

The list is meant as a test rather than a table of contents. Where a deliberate answer to one of the points is missing, the decision still exists: it was inherited rather than taken.

What such a page looks like

Context: sign-in on the Mac currently runs against Active Directory, the password is cached locally, and mobile use produces drift between the local and the central password.

Options: keep the existing mechanism, introduce a third-party product for password synchronisation, or use Platform SSO against the existing identity provider.

Decision: Platform SSO, because sign-in then runs against the central identity without an intermediate product, and device state belongs in the same chain of trust.

Consequence: the identity provider becomes critical for device sign-in, a documented path for its outage is required, and devices below a given OS version fall out of the mechanism. Status: accepted, effective from rollout wave two.

Four paragraphs of this kind record what is otherwise no longer reconstructable two years later.

Recurring mistakes in practice

ADRs written afterwards. Writing the decision down after implementation documents a justification. The value is created before, because writing makes visible the options one otherwise skips.

No status. An ADR without a status is an opinion with a date. Only the chain of accepted and superseded explains why the platform looks different today than it did three years ago.

No consequences. The section that names the price is the only one anyone believes later. Without it every ADR reads like a brochure for the choice that was made.

Filed in the ticket system. Decisions belong where the configuration lives, versioned and with a change history. A ticket is closed. An ADR holds.

How this connects to evidence

Auditors ask why. Regulation asks for traceable decisions, not for complete lists of settings. A maintained set of ADRs answers both, without anyone reconstructing intent the week before the appointment.

The second effect weighs more in daily work. A platform whose decisions are written down can be handed over. One whose decisions live in people's heads can only be passed on. That difference is the difference between governing endpoints and administering them.

How configuration can be kept versioned is covered in Config as code at the endpoint.