In the first two articles of this series (How to Start Thinking Like a Salesforce Architect and Why Design Authority Is Crucial in Salesforce Architecture), we explored how enterprise architecture thinking translates to Salesforce and why Design Authority is essential to protecting architectural intent at scale.
This final article focuses on what comes next: how architects ensure those decisions persist as teams, priorities, and platforms evolve.
Why Good Architecture Still Fades
Early in a Salesforce program, architectural intent is usually clear. Key decisions are discussed, trade-offs are debated, and patterns emerge. But as teams change, priorities shift, and delivery accelerates, the reasoning behind those decisions fades. What remains are the outcomes – objects, flows, integrations – divorced from the intent that shaped them.
Over time, architecture becomes fragile not because decisions were wrong, but because context was lost. The diagram below maps this pattern of erosion and the practices that interrupt it.
From Design Authority to Architectural Memory
Design Authority helps teams make better decisions in the moment, but what it does not guarantee is that those decisions will be remembered.
Picture this: a new architect joins six months after go-live, and they ask why Platform Events were chosen over Change Data Capture. No one in the room remembers. The original decision-makers have moved on, the meeting notes are buried, and the debate starts again from scratch, consuming time that should have been spent building forward.
This is where many governance models stall – not in the decisions they produce, but in the memory they fail to preserve. The mind map below shows how the concepts in this article connect, tracing the path from architectural fade to the practices that create durability.
Architecture Decision Records (ADRs) in a Salesforce Context
Architecture Decision Records are not a new concept – they are a well-established practice in the enterprise architecture discipline, rooted in decision traceability and intent preservation. The goal is not to introduce new frameworks, but to bring proven architectural rigour into the realities of a metadata-driven platform.
An ADR does not attempt to explain the entire system. It captures a single decision and its rationale, making it particularly effective in Salesforce environments, where many architectural choices appear small at first but carry long-term consequences.
Consider the decisions that quietly shape a platform:
- Flow vs. Apex: Choosing the default automation mechanism determines how future teams handle complexity, recursion, and transaction control, not just today’s use case.
- Synchronous vs. asynchronous integrations: The default shapes coupling, retry complexity, and consumer resilience across every integration that follows.
- Platform Events vs. Change Data Capture: Each carries different implications for schema exposure, consumer constraints, and event replay.
- Data replication vs. virtualization: A choice with lasting consequences for reporting architecture, data freshness, and downstream dependencies.
- Permission Set Groups vs. profiles: The access model chosen early determines how composable and maintainable permissions remain as the org scales.
None of these is universally right or wrong. They depend on scale, skill sets, compliance needs, and future expectations. Problems arise when that context is lost.
A well-written Salesforce ADR answers the questions future teams will inevitably ask:
- What alternatives were considered?
- What constraints mattered at the time?
- What risks were knowingly accepted?
- Under what conditions should this decision be revisited?
When decisions are recorded this way, teams stop debating history and start building forward. New architects ramp up faster. Design Authority discussions become cumulative rather than repetitive. Most importantly, architecture no longer depends on who remembers what – the platform itself begins to carry intent forward.
The most effective starting point is not a retrospective audit, but a commitment to record the next significant decision as it is made.
Example: Salesforce Architecture Decision Record (ADR)
The example below shows how a Salesforce ADR captures architectural intent in a lightweight, durable way.
The fields shown represent the minimum viable structure. Teams can extend this as needed, but the core value lies in recording the decision, the context, and the conditions for revisiting it.
ADR Integration Flow (Conceptual)
| Aspect | Decision Detail |
|---|---|
| Decision | Use Platform Events for cross-system state change notifications instead of synchronous APIs or Change Data Capture. |
| Context | The Salesforce platform integrates with multiple downstream systems. Consumers may evolve, and tight coupling would limit scalability and resilience. |
| Options Considered | 1. Synchronous REST APIs – not selected due to tighter coupling and retry complexity. 2. Change Data Capture (CDC) – not selected due to schema exposure and consumer constraints. 3. Platform Events – selected for decoupling and extensibility. |
| Decision Rationale | Platform Events support asynchronous processing, reduce consumer dependencies, and align with future growth in integration. |
| Implications | – Event consumers must handle eventual consistency. – Monitoring and replay strategies are required. – Schema discipline is needed upfront. |
| Revisit Triggers | – Event volume exceeds platform limits. – New Salesforce-native integration capabilities emerge. – Regulatory or audit requirements change. |
Guardrails: Designing for Freedom, Not Control
Guardrails are not rules, nor are they approval gates. They define safe boundaries within which teams can make autonomous decisions without repeatedly revisiting foundational debates.
In Salesforce environments, effective guardrails tend to emerge around a small set of architectural choices that repeatedly shape the platform.
For example:
- Automation Guardrail: Record-triggered Flow is the default automation mechanism unless logic requires bulk-safe recursion control, complex transaction management, or coordinated external callouts – which is where Apex is appropriate.
- Integration Guardrail: Integrations are asynchronous by default unless a genuine user-blocking dependency exists and latency thresholds are explicitly defined.
- Data Guardrail: Data is replicated only when reporting, performance, or downstream processing requires it; otherwise, virtualization or event-driven access is preferred.
- Access Model Guardrail: Permission Set Groups are the standard for composing access; profiles define only baseline permissions.
These examples are not rigid mandates. They represent agreed defaults shaped by prior decisions and platform experience. When exceptions are required, they are made deliberately, with context understood and trade-offs acknowledged.
Guardrails are most effective when informed by architectural memory and when they are discoverable. ADRs preserve the rationale; guardrails operationalize that intent. Together, they allow the platform to evolve without losing coherence.
Designing for Evolution in a Metadata-Driven Platform
Durable Salesforce platforms are not built to last forever – they are built to adapt without losing coherence.
Salesforce evolves continuously: new features, new clouds, new integration patterns. Architecture that assumes stability will eventually break. Architecture that assumes change, and designs for it explicitly, can evolve without reintroducing fragmentation or drift.
This is not theoretical. The shift from Process Builder to Flow, the rise of Data Cloud, the maturation of MuleSoft: each forced architectural rethinking across thousands of orgs. Evolutionary design is about ensuring the platform can absorb it without losing the coherence that gives teams confidence to act.
In each case, the teams that fared best weren’t those with the most rigid architectures. They were the ones whose decisions were visible, whose guardrails had explicit revisit conditions, and whose ADRs gave them a clear basis for updating rather than replacing their foundations.
Consider what this looks like in practice. A team that had documented their Process Builder automation decisions – including the constraints that ruled out Apex at the time – was able to assess the move to Flow with clarity rather than from scratch.
Their ADR recorded that the original choice was driven by team skill level and a low-complexity automation backlog. When both of those constraints had changed, the revisit trigger was obvious, the migration rationale was straightforward, and the new decision was recorded in turn. Without that record, the same conversation would have been relitigated in full, likely with different conclusions depending on who was in the room.
Signals That Architecture Is Being Institutionalized
The diagram below shows what architectural maturity looks like in practice – when the practices described in this article have taken hold and compound over time.
A new architect joins mid-programme. Rather than being briefed by whoever is available, they spend a morning reading through ADRs. By the afternoon, they are asking informed questions about current trade-offs rather than relitigating decisions that were settled two years ago. Onboarding time drops from weeks to days – not because the codebase got simpler, but because the reasoning behind it became visible.
A delivery team requests an exception to the default asynchronous integration guardrail. Because the boundary is documented and the reasoning is clear, the conversation is constructive rather than adversarial. The exception is made deliberately, the trade-offs are acknowledged, and the decision is recorded. Rather than quietly becoming a new undocumented pattern that future teams will inherit without context.
Over time, the most telling sign of architectural maturity is not what happens when the lead architect is in the room, but what happens when they are not. Delivery continues. The platform holds its coherence. The team already knows why the system is the way it is, and they continue building in alignment with that intent.
These are not aspirational outcomes. They are the practical result of the practices described in this article, accumulated over time.
As architects mature, their impact shifts. Early in their careers, architects make decisions. Later, their value increasingly comes from enabling others to make good decisions through clear communication, deliberate mentoring, and modelling sound judgment in the room.
This transition is not automatic. It requires architects to invest in articulating not just what they decided, but why, and to treat knowledge transfer as part of the role, not an afterthought.
Summary: Architecture That Endures
Architecture, at its best, creates the conditions for good decisions to outlast the people who made them. It does this not through rigid processes or comprehensive documentation, but through preserved intent, agreed boundaries, and a culture of deliberate stewardship.
As architects mature, their impact increasingly comes from how they communicate, mentor, and model good judgment. Clear explanations replace detailed designs. Framing trade-offs becomes more important than choosing tools. Listening, facilitation, and trust-building become as critical as technical expertise.
Over time, many architects also recognize a responsibility beyond individual programs – contributing patterns, documenting hard-won lessons, and sharing experience with the broader community. These acts don’t just develop others; they reinforce the discipline itself.
This is how architecture becomes durable in the deepest sense: not because every decision was perfect, but because understanding, intent, and responsibility continue long after the original architects have moved on.
