A solid Solution Design Document is one of the most genuinely useful things an architect can produce. It gives developers a clear starting point, gives QA something concrete to test against, and means any team member joining mid-project can get up to speed without a two-hour handoff call. The problem is that most SDDs are written for governance sign-off rather than for the people who actually have to build from them. They have sections without real content, design choices without rationale, and integration descriptions that look complete until a developer tries to act on them.
This guide walks through every section of a Salesforce SDD: what goes in each one, what makes it useful rather than just present, and what an empty-looking section usually signals. There’s a free downloadable template at the end.
Table of Contents
What a Salesforce Solution Design Document Is (and Isn’t)
The SDD is solution-oriented documentation. That distinction matters more than it looks on paper.
A Business Requirements Document captures what the business needs. The SDD describes how Salesforce will deliver it, and why specific design choices were made over the alternatives. “Cases should route to the right team automatically” is a requirement. “Routing will use Omni-Channel with Skills-Based Routing rather than standard assignment rules, because the client’s support model requires matching on both agent skill and current workload capacity simultaneously” is solution design.
Most enterprise implementations split this into two layers. The High-Level Design (HLD) covers architecture, connected systems, and key solution choices at a level that business and executive stakeholders can engage with. The Low-Level Design (LLD) gets into field-level specs, automation logic, configuration notes, and integration mappings the material the build team works from daily. In practice, the SDD starts as an HLD and evolves to include LLD detail as the project moves from design into delivery. They’re usually the same document at different stages of maturity, not two separate deliverables.
What the SDD is not: a BRD, a project plan, a test script, or a technical specification — though it references and informs all of those. They serve different purposes and different audiences. The SDD doesn’t replace them.
Where the SDD Fits in the Project Lifecycle
Discovery → Requirements → High-Level Design → Sign-Off → Low-Level Design → Build → Test → Go-Live
The SDD doesn’t exist before requirements are validated. This is practical, not procedural. If you start designing against assumptions, you spend the build phase correcting your own document.
After requirements are signed off, the architect produces an HLD. Once implementation scope is locked, the LLD fills in the technical detail. Typically, the Solution Architect or Technical Architect owns this document, but the process is collaborative: Business Analysts provide information on requirements traceability, Lead Developers review feasibility, and Project Managers keep the scope boundaries clear.
The thing that gets skipped too often: the SDD is a living document. Every significant design decision that shifts during build — a new integration, a data model change, a security approach that turns out to be unworkable in practice should be reflected in it. A version history table sounds like admin overhead right up until you’re six weeks into build, arguing about when the object relationship changed and why it was changed.
The 8 Sections Every Salesforce SDD Needs
Document Control & Version History
A simple table: version number, date, author, approver, status (draft / under review / approved), and a one-line description of the changes made. For projects involving multiple architects or long build phases, this table is the only reliable way to determine which version of the SDD was active when a key design decision was made.
Maintaining this section takes ten minutes. It has saved hours of confusion across countless projects.
Project Overview & Scope
What the implementation covers: Salesforce cloud(s) in scope, project name, key stakeholders, go-live target, and delivery approach.
What is *out* of scope is more important than what is *in* scope. “Partner community and mobile experience are out of scope for this SDD and will be addressed in a separate design phase.” This single sentence has done more to curb debates about scope creep than any formal change control process. Write it down. Clearly state it in the document.
Don’t copy requirements verbatim from the BRD. Cross-reference it. The SDD should capture what was agreed and how the design addresses it — the BA already wrote the requirements document.
Current State Assessment
Before describing what you’re building, describe what you’re replacing or working alongside. What legacy systems are in play? What manual processes are being automated? Where are the pain points the client actually wants solved?
This section gets treated as administrative padding by clients who want to skip straight to design. That’s usually a mistake. Every major design decision in the SDD should trace back to a documented current-state problem. If you’re recommending Omni-Channel routing over standard assignment rules, the current-state gap is what justifies the recommendation. Without it, your design choice looks like an architect preference rather than a response to a real constraint.
Proposed Solution & Architecture Overview
The to-be picture. What does the proposed Salesforce environment look like, and how does it connect to the systems around it?
Include or reference a system context diagram showing Salesforce, connected platforms, and data flow directions. It doesn’t need to be polished — it needs to be accurate and up to date.
Document the rationale behind every major design decision. Instead of simply stating, “We will use Flow for automation,” write, “We will use Flow because the client’s admin team will be responsible for maintenance post-go-live, whereas Apex would require continuous developer support—a capacity they do not possess.” This is precisely what makes this section valuable even six months after go-live, should anyone wish to make changes.
A practical validation lens here: Salesforce’s Well-Architected Framework organizes architectural guidance around three qualities — Trusted (secure, compliant, reliable), Easy (user-friendly, maintainable, automatable), and Adaptable (scalable, resilient, composable).  It takes about 20 minutes to map out the key design options based on those three attributes. This gives stakeholders a meaningful way to evaluate your perspective, rather than relying solely on a diagram they do not fully understand.
Data Model & Object Design
Two types of shortcomings are frequently observed in this section. The first is a vague list of items (e.g., “We will use accounts, contacts, and opportunities”). The second is a 40-page “field dump” that lacks information regarding the purpose or source. Neither provides the developer with concrete information to get started.
A field specification table that covers the label, API name, data type, whether it is required or optional, and a brief description of the field’s purpose and its source system is usually the right format. Pair that with an ERD (Entity Relationship Diagram) showing object relationships.
A sample row for context:
| Label | API Name | Type | Required | Description |
|---|---|---|---|---|
| Customer Tier | Customer_Tier__c | Picklist | Yes | Segment classification synced nightly from ERP. Read-only in Salesforce. |
Clearly document decisions related to relationships. Lookup vs. Master-Detail affects record ownership, deletion behavior, and roll-up summary capabilities. If you chose Master-Detail because you need roll-up summaries and child records have no independent business meaning, write that down. If you chose Lookup because children need to survive parent deletion, write that down too. These decisions get questioned during UAT and post-go-live — having the rationale documented saves a lot of time.
One other thing worth flagging in this section: data volume estimates. If the client expects 10 million Case records in 18 months, that has implications for indexing strategy and query performance that need to be designed for now rather than discovered later.
Security & Sharing Model
Consistently the most under-documented section. Also the first one that surfaces during a security review or compliance audit.
Cover: Org-Wide Defaults (OWD) for key objects, whether the project uses legacy Profiles or Permission Sets and Permission Set Groups, sharing rules, and any records requiring manual sharing or Apex Managed Sharing.
For the integration, document your approach regarding Named Credentials. Credentials should not be stored in Custom Settings or hardcoded in Apex classes. Named Credentials represent the correct pattern; documenting this approach in the SDD ensures that the developer building the integration does not take a shortcut that becomes a maintenance issue during the next audit.
Integration Design
For each integration, the SDD must specify the following: source system, target system, data direction, trigger type (real-time vs. batch), protocols (REST, SOAP, Platform Events, Change Data Capture, etc.), error handling method, and retry behavior.
The piece that most integration sections skip: define the System of Record for each shared data entity. Who owns the Account — Salesforce or the ERP? Who controls product pricing? Leaving this ambiguous on paper doesn’t keep it ambiguous for long. This leads to production-related issues in which two systems provide different answers to the same data query.
For any specific integration, be sure to include at least one field mapping table or a sample payload. The difference between an integration section that a developer can work on directly and one that requires further discussion with you often comes down to the presence of a solid table.
Automation Strategy
Document the automation approach for each business process in scope: tool used (Flow, Apex Trigger, Scheduled Job, Platform Events), trigger conditions, and the reason that tool was chosen over the alternatives.
The starting position should be declarative first. Flow before Apex, unless there’s a documented reason Apex is necessary for the specific use case. If you’re mixing automation tools on the same object, flag it and explain why. Mixing Flows and triggers on the same object is a known maintenance risk — leaving it undocumented means the admin inheriting this org 12 months post-go-live has no way to understand what’s running or why.
Also document error handling. What happens when a scheduled Flow fails overnight? How are integration faults surfaced to the admin team? These questions come up in UAT whether or not you planned for them.
What Separates a Useful SDD from a Performative One
A document written for governance sign-off reads differently from one written for the developer sitting down to build from it. The sections look the same from the outside, but the content isn’t.
The gap shows up in specifics or the absence of them. “Integration: Salesforce will integrate with SAP” is not integration design. “Security model: roles and profiles will be configured according to business requirements” is not a security model. These take up space without containing anything actionable.
Before declaring the SDD ready for review, a functional test can be performed on each section: Can a developer create it just by looking at the document, without asking you? If the answer to any section is ‘no’, then more work is needed on that section. This is a direct check of quality, and is more difficult to cheat or manipulate than a completion checklist.
The other failure mode is the frozen SDD: a document that reflects the design as it existed at sign-off, not as the project actually evolved. Scope shifts during build. Integration approaches that looked clean in design turn out to need adjustment once the external API is tested in a sandbox. That’s not a failure; it’s normal. Failing to update the document is the failure. An SDD that doesn’t match what was built has no value to whoever maintains the org next.
Version discipline from the start fixes this. One line in the revision history per significant update. That’s it.
Download the Free Salesforce SDD Template
The template covers all eight sections above, with instructional notes inside each one explaining what to include, not just what to call the heading. It includes a pre-formatted field specification table, a version history table, and placeholder examples for the security and integration sections, providing you with a working starting point.
[Download the Free Salesforce SDD Template →]
Final Thoughts
Open the template, fill in the project context in Sections 1 and 2, and work through the sections in order. The architecture overview and data model are where most of the real thinking happens — those sections benefit from a second set of eyes before you send for stakeholder review.
The SDD isn’t a ceremony. It’s what stops someone from having to reconstruct the original design from memory nine months after go-live when a requirement changes and nobody can explain why something was built the way it was.
Frequently Asked Questions (FAQ)
The SDD is the primary technical reference for a Salesforce implementation. It translates validated requirements into design decisions — data model, security, integrations, automation — so developers, QA engineers, and admins have a single authoritative source for what was built and why.
Typically the Solution Architect or Technical Architect. The Business Analyst contributes to requirements traceability, and Lead Developers should review the technical sections before sign-off. On smaller projects without a dedicated architect role, a senior consultant often produces it.
A Business Requirements Document captures what the business needs. The SDD describes how Salesforce will deliver it, including the specific design choices made and the reasoning behind them. They’re complementary. The SDD references the BRD rather than repeating it.
Scope determines length. A focused Sales Cloud implementation for a mid-size company might produce 15–20 pages. A multi-cloud enterprise implementation with complex integrations might run 60 or more. Length is not the quality measure — completeness is.
Any project that involves more than one person or more than a sprint’s worth of work benefits from one. The documentation reduces rework, speeds up knowledge transfer, and provides a reference point for post-go-live changes. Smaller projects can have lighter SDDs. Skipping one entirely is always a gamble.
Any time a significant design decision changes. Minor configuration choices don’t need to trigger an update, but changes to the data model, security approach, integration design, or automation strategy should be logged and reflected in the document.
Arun Kumar
Arun Kumar is a 4x Salesforce Certified professional. He designs and implements scalable solutions that improve customer engagement, streamline business processes, and drive measurable results. Passionate about exploring the latest Salesforce innovations, Arun enjoys sharing practical insights and best practices to help businesses build smarter, data-driven strategies.
- Arun Kumar
- Arun Kumar
- Arun Kumar
- Arun Kumar
