Documenting Technical Decisions in Architecture Decision Records

Hello again. Last time, you compared build, buy, and open-source approaches for video ingestion. Open-source assembly had a narrow lead in the illustrative matrix, but a change in priorities or a failed recovery test could reverse the result. A score alone is not a technical decision.

Today you will turn that comparison into an architecture decision record (ADR): a short, durable account of what the team proposes to do, why, what it will give up, and what remains unverified. This is useful when a pilot team needs to move forward without allowing a planning assumption to become an unquestioned architectural rule.

Record the why while it is still available

Imagine a new engineer encounters a video-ingestion adapter six months from now. The code may show how it connects to a stream, but not why the team chose that approach over an SDK. Perhaps the choice was made because of a pilot deadline, a media-processing constraint, or evidence that later proved wrong. An ADR preserves that point-in-time reasoning.

Watch the opening of CodeOpinion’s Architecture Decision Records (ADR) as a LOG that answers “WHY?”. Focus on the distinction between seeing a choice in code and understanding the circumstances that justified it.

Not every implementation choice needs an ADR. Choosing a variable name usually does not change the system’s direction. Choosing the video-ingestion approach does: it affects dependencies, the interface delivered to analysis, recovery behavior, maintenance work, and potentially whether the pilot can run on its deployment device. Those effects make it architecturally consequential.

An ADR is neither a full design document nor a promise that an option has passed its tests. Its central question is: Given what we knew and needed at this point, why did we choose this direction rather than the credible alternatives?

Give one decision a clear shape

Read the “Suggested characteristics of an individual record” in Microsoft Learn’s Maintain an architecture decision record (ADR). Its checklist adds two especially useful elements to the basic format: options considered and confidence in the outcome.

A practical record needs a title and status, followed by three core parts:

• Context: the bounded problem, relevant requirements and constraints, and what is known or unknown.
• Decision: the chosen direction, stated directly, with its rationale and credible alternatives.
• Consequences: benefits, costs, new responsibilities, and conditions that could invalidate the choice.

Keep the decision separate from its implementation details. “Use an open-source media framework plus a team-owned adapter for pilot ingestion” is an architectural direction. A long account of pipeline configuration belongs in implementation documentation. The ADR may link to that documentation, but it should make sense on its own.

Status matters just as much as wording. Proposed means the team is being asked to review the choice; it does not mean the choice has been approved. Accepted means the decision has been reviewed and is currently in force. A later decision can supersede it. These states prevent a draft in a repository from quietly becoming policy.

Write the decision the matrix can actually support

Here is an illustrative ADR based on the previous lesson. It chooses a specific direction—GStreamer plus a small team-owned adapter—without claiming that the camera, license, target device, or recovery behavior has already been verified. GStreamer is named to make the proposal reviewable; its suitability for this pilot remains a question to test.

ADR-001: Use an open-source framework for pilot video ingestion
Status: Proposed
Owner: Assigned video-ingestion engineer
Accountable reviewer: Technical lead
Scope: Pilot video ingestion only; not event detection, alerting, or general fleet architecture

Context
The pilot needs to connect to a camera stream, recover from a temporary disconnection, decode video, and deliver frames with a source identifier and usable timestamp to the analysis component. The team considered building this component using lower-level media interfaces, buying an on-device ingestion SDK, and assembling an open-source framework with a small adapter.

A preliminary weighted matrix gives open-source assembly a narrow lead under the agreed pilot priorities. Its ratings are planning judgments, not measured results. The camera interface, deployment-device compatibility, license obligations, and recovery behavior have not yet been verified. Media-location requirements must also be confirmed.

Proposed decision
We propose to use GStreamer with a team-owned adapter for the pilot’s video-ingestion boundary. The adapter will expose frames, source identity, and timestamps to the analysis component. This proposal does not authorize pilot deployment until the unresolved checks below pass and the ADR is accepted.

Why this direction
It appears to offer a testable integration path without requiring the team to build most ingestion behavior from lower-level interfaces or commit immediately to a licensed SDK. The matrix’s lead is small, so the rationale depends on the pending evidence. Build retains control but places more implementation and maintenance work on this team. Buy might provide a shorter integration path and supplier support, but its actual interface fit, terms, and total cost remain unverified.

Consequences and trade-offs
A benefit, if validated, is that the team can concentrate its own code at the adapter boundary rather than own an entire ingestion component. The team still owns integration, dependency maintenance, disconnection handling, and diagnosis of failures. It must test the selected packages on the selected device and software environment; “open source” alone establishes neither commercial suitability nor reliable operation.

Evidence required before acceptance
Confirm the representative camera interface and demonstrate frames with source identity and timestamps. Check the exact packages, versions, and applicable license obligations; verify the intended deployment environment and media-location constraint. Run a representative sustained-stream test that includes disconnection and reconnection, and record the observed behavior. Review the resulting evidence against the alternatives before approving this choice.

Revisit if
A non-negotiable gate fails; recovery evidence weakens the open-source option’s rating enough to change the comparison; or an agreed change in pilot priorities favors another option. Record a replacement decision rather than silently changing this one.

Notice what the ADR does not say. It does not call the framework reliable because it is widely used. It does not assert compatibility with a particular Jetson model without a test. And it does not translate the matrix’s 3.50 score into “approved.” The previous lesson showed that changing the reliability rating could reverse the ranking; the ADR therefore makes recovery evidence part of the decision’s review.

There is also an important difference between accepting an ADR and accepting a pilot. Accepting this ADR would authorize an architectural direction under its stated scope. Pilot acceptance will require separate, measurable product criteria—our next lesson’s subject.

For a small team, the record can be a Markdown file such as docs/adr/0001-pilot-video-ingestion.md. Keep it close to the code and link to the matrix and test records when they exist. The file should retain the essential reasoning even if those supporting materials move.

Review it as a team decision, not a private note

A written proposal is valuable only if the people responsible for building and testing it can challenge it. AWS Prescriptive Guidance describes an ADR owner, a Proposed state, review, possible rework or rejection, and an Accepted state. Read its process with this pilot in mind: what question should a reviewer ask before permitting implementation to depend on the proposed framework?

For the sample ADR, the review should produce a clear outcome. If the camera interface is still unknown, reviewers may leave it Proposed, assign someone to obtain a representative stream, and schedule another review. If the candidate cannot meet a required media-location rule, reviewers should record the reason for rejection rather than keep polishing an unsuitable proposal. If the evidence supports it, they can mark the ADR Accepted and record when and by whom it was reviewed.

After acceptance, preserve the reasoning as a historical record. If a later pilot exposes unacceptable reconnection failures, write a new ADR explaining the new evidence and the replacement choice; link it to the old record and mark the old one Superseded. Correcting an error or updating a status is different from rewriting the original rationale to make an earlier decision appear better informed than it was.

The governing habit is simple: make uncertainty visible, give it an owner, and do not confuse a reviewable proposal with verified deployment readiness.

Key takeaways

An ADR records one consequential choice, its context, the alternatives, the rationale, and both favorable and unfavorable consequences. Its status tells the team whether that choice is merely proposed or currently in force. For this pilot, the most honest record proposes an ingestion direction while explicitly holding acceptance on camera, device, licensing, media-location, and recovery evidence.

In the next lesson, you will define pilot acceptance criteria using baselines, targets, test conditions, and exclusions. That will make it possible to judge not just whether an architectural choice is justified, but whether the delivered system meets the pilot’s agreed expectations.