Architecture decision records for Dynamics 365

A Dynamics 365 implementation makes hundreds of architectural decisions — Sales vs Customer Service for some workflow, BC vs F&O for a subsidiary, Power Automate vs plug-in for some logic, partner ISV vs custom build. Three years later, when someone asks "why did we do it this way?", nobody remembers. Architecture decision records (ADRs) are the lightweight discipline that captures the reasoning while it's fresh.

What an ADR is. An ADR is a short document — typically one or two pages — capturing one architectural decision:

• Title — succinct description.
• Status — Proposed, Accepted, Deprecated, Superseded.
• Context — what problem are we solving? What's the situation? What constraints apply?
• Decision — what did we decide?
• Consequences — what are the implications? Trade-offs? Risks?
• Alternatives considered — what else was on the table? Why was each rejected?
• Decision-makers — who decided?
• Date — when.

Format-wise, plain markdown files in a version-controlled repository — docs/adr/0001-use-dataverse-for-shared-customer-data.md, docs/adr/0002-bc-not-f-and-o-for-uk-subsidiary.md, sequentially numbered.

Why bother.

• Decisions are made by people who leave. Three years from now, the original architect is at another company. Without ADRs, their reasoning is lost; successors reverse decisions without understanding why.
• Decisions need to be revisited. "Did we decide F&O for the UK because of complexity or because BC didn't support a feature in 2023?" Without an ADR, that question can't be answered.
• Decisions are evidence in audits and post-mortems. "Why did we choose vendor X over vendor Y?" The ADR is the evidence.
• Onboarding new team members. Reading ADRs gives them context faster than reverse-engineering decisions from code.

Common ADR topics in Dynamics 365 programs.

• Product selection per subsidiary — why F&O for one entity, BC for another.
• CRM-side product choice — why Sales + Service, or Sales-only, or Customer Insights without Sales.
• Customisation strategy — when to use Power Platform vs AL/X++ vs plug-ins.
• Integration patterns — Dual-write vs Synapse Link vs custom for specific data flows.
• Multi-currency / multi-entity setup — chart of accounts shared or per-entity, reporting currency, consolidation approach.
• Security model — business unit topology, role design, hierarchical security.
• Environment topology — number of sandboxes, naming, lifecycle.
• DLP policies — connector classification choices.
• ISV selection — why Continia for AP automation vs ExFlow vs Documotor.
• Identity provider — Entra ID, External ID, federated, social.
• API authentication — service principals vs managed identity vs OAuth.
• Disaster recovery strategy — RPO/RTO targets and how they're met.

Writing a good ADR.

The hardest part isn't the format — it's documenting honestly. Good ADRs:

• Explain context that's not in the decision. Why now? What pressures, constraints, opportunities led here?
• List real alternatives, not strawmen. "We considered X, Y, Z" — actual considered options, with real reasons each was rejected.
• Acknowledge trade-offs. Every architectural decision has trade-offs; pretending otherwise is dishonest.
• Are short. One or two pages, not twenty. ADRs that nobody reads are wasted effort.

ADR lifecycle.

• Proposed — under discussion; comments expected.
• Accepted — decision made; team is acting on it.
• Deprecated — decision is no longer current; usually superseded by a newer ADR.
• Superseded — explicitly replaced by another ADR (which references the predecessor).

Old ADRs aren't deleted — they're marked superseded with a reference to the new ADR. The history matters.

Storage and access.

Best practice:

• In source control — alongside the code, in a docs/adr/ folder.
• Versioned — Git tracks changes; review through PRs.
• Linkable from the code — code comments can reference ADR numbers ("see ADR-0042 for why we use this pattern").
• Discoverable — index file listing all ADRs with status.

For Dynamics 365 programs without a central code repo, ADRs can live in Azure DevOps wikis, Confluence, or SharePoint. The format matters less than the discipline.

Frequency.

Not every decision warrants an ADR. Heuristics:

• Architecturally consequential — affecting the broader system, not local code style.
• Hard to reverse — once committed to, reversing is expensive.
• Debated — alternatives were seriously considered.
• Non-obvious to a future reader — without context, someone would do something different.

Roughly: a healthy Dynamics 365 program produces 20-50 ADRs over its first year, with steady-state of 10-20 per year afterward.

Reviews and revisits.

Schedule periodic ADR reviews:

• Each release cycle, identify ADRs that should be revisited based on what's been learned.
• Annual review of accepted ADRs — still relevant? Still correct? Still consistent with current state?
• On major changes (new modules, big integrations, organisational changes), audit affected ADRs.

Common pitfalls.

• No ADRs at all — decisions are tribal knowledge; lost when people leave.
• ADRs written but not maintained — stale ADRs are worse than no ADRs (they mislead).
• ADRs too detailed — multi-page ADRs nobody reads.
• ADRs as documentation, not records — ADRs aren't user guides; they're decision records.

Operational reality. ADRs are a small investment that pays back enormously. Adopt the practice; treat it seriously; the program's institutional memory thanks you.