SA Teaches: The Architecture Decision Record (ADR) and Why Every Project Needs One
An ADR captures every significant architectural decision. SA writes one for every major decision on every engagement — short, structured, and delivered to clients as institutional memory that survives team changes.
The Most Important Documentation Practice You Are Not Doing
An Architecture Decision Record (ADR) is a short document capturing a significant architectural decision: what the decision was, why it was made, what alternatives were considered, and what the trade-offs are. ADRs are the institutional memory of a software system. Without them, people who maintain the system years later have no way of knowing why it was designed as it was — and risk making changes that violate assumptions the original architecture depended on.
What Every Architecture Decision Record Contains
// Date: 2026-03-15 | Status: Accepted | Author: SA
Context
Multi-tenant SaaS application. Multiple organisations share one application
instance. Complete isolation of each organisation’s data is required.
Decision
Use a Workspace data type as the tenant boundary.
Every application data type will have a workspace field.
Privacy rules on every type will check for active Membership
linking the current user to the record’s workspace.
Alternatives Considered
1. User-level isolation (no Workspace): rejected, users collaborate within orgs.
2. Separate database per tenant: not supported by Bubble.io platform.
Consequences
+: Complete tenant isolation at PostgreSQL level.
-: All queries must include workspace constraint.
Risk: Forgetting workspace field on a new type creates a gap.
Mitigation: Two-browser isolation test before every deployment.
The Decisions That Deserve Documentation
| Decision Type | Write ADR? | Why |
|---|---|---|
| Technology or platform choice | Yes | Future teams need to understand why this was chosen over alternatives |
| Data model design choice | Yes | Why this structure rather than another affects feature extensibility |
| Security pattern choice | Yes | Security reasoning must be preserved for audit and future changes |
| Integration pattern choice | Yes | Why webhook vs polling; why this provider vs another |
| Performance optimisation | Yes (for architectural changes) | Denormalisation decisions affect how data must be maintained |
| UI component choice | No | UI decisions are low-cost to change and not structural |
| Naming conventions | No | Style decisions, not architectural decisions |
How We Integrate ADRs Into Every Engagement
SA creates an ADR for every significant architectural decision on every client engagement. Written at the time the decision is made, not retrospectively. Numbered sequentially (ADR-001, ADR-002) and included in the architecture document delivered to the client. When a decision is revisited and changed, the original ADR is marked superseded and a new ADR documents the new decision and the reason for the change.
Q: How long should an ADR be?
Short. 150-200 words. Context, decision, alternatives, consequences. If it is getting long, break it into smaller decisions, each with its own ADR.
Q: Should ADRs be shared with clients?
Yes. Architecture decisions affect the client’s system for years. Clients who understand why decisions were made are better positioned to make future product decisions that align with the existing architecture.
Q: What if an architectural decision turns out to be wrong?
Write a new ADR documenting the change. Mark the original superseded. Document the reason for the change. This creates a decision history showing the architecture evolving deliberately, not randomly.
Work With SA — Simple Automation Solutions
Pakistan’s leading no-code systems architecture practice. We design tech systems before we build them.
