Home / architect / nfr-definition-for-salesforce
nfr-definition-for-salesforce
Defining measurable non-functional requirements for Salesforce implementations: performance SLIs, scalability targets, availability SLAs, security and compliance requirements, usability benchmarks. Use when starting architecture design or preparing for go-live sign-off. NOT for technical implementation of those requirements. NOT for HA/DR and failover planning — use architect/ha-dr-architecture. NOT for governor limit and scale headroom analysis — use architect/limits-and-scalability-planning.
Open the skill folder on GitHub
NFR Definition for Salesforce
This skill activates when a team needs to define and document non-functional requirements (NFRs) for a Salesforce implementation before design begins or before go-live sign-off. It produces a structured NFR register with measurable acceptance criteria grounded in Salesforce platform realities: governor limits, the shared responsibility availability model, compliance control requirements, and usability benchmarks.
Before Starting
Gather this context before working on anything in this domain:
- Confirm the Salesforce org edition and feature set — NFRs for a Government Cloud org with Shield differ substantially from a standard Enterprise edition org.
- Establish the business criticality tier: what is the cost of one hour of downtime, one day of data unavailability, or a compliance breach? This sets the stakes for each NFR category.
- Identify the 3-year scale horizon — user count, record counts per major object, daily transaction volume, API call volume. Governor limits are hard ceilings; you need headroom calculations now, not at go-live.
- Confirm which regulations apply. GDPR, HIPAA, and PCI-DSS each impose specific technical controls that must appear as NFRs, not as vague security goals.
- The most common wrong assumption: "Salesforce handles availability — we don't need to define it." This confuses infrastructure uptime (Salesforce's responsibility) with data recovery, custom code reliability, and integration availability (customer's responsibility).
Questions to Ask Before Configuring
Each question traces to a gotcha in references/gotchas.md.
| Question | Why it matters | What a good answer adds | What proper configuration adds over just doing it |
|---|---|---|---|
| "What does one hour of Salesforce being unavailable cost, and which processes must keep running?" | Availability is shared responsibility; the platform's figure says nothing about custom code or integrations (Gotcha 3) | A criticality tier and team-owned RPO and RTO per process | Availability NFRs that the team can actually influence and test |
| "How many users, records per object, and API calls per day at launch, at peak hour, and at three years?" | Daily allocations scale with licences; per-transaction limits never do (Gotchas 2, 4) | A limit translation table with utilisation at launch and at the horizon | Async patterns chosen at design time, not after a limit breach |
| "Where, with what tool, and at which percentile will each performance NFR be measured?" | Only a Full sandbox approximates production volume, and page-time evidence lives in Event Monitoring (Gotchas 1, 7) | The environment, the data source (EFFECTIVE_PAGE_TIME or browser timing), and the percentile per NFR | Go-live criteria that produce evidence instead of opinions |
| "Which integrations share the org's API allocation, and how many run in parallel?" | One pool serves every integration, and 25 long requests can block new ones (Gotchas 2, 6) | One API budget table with calls per day, concurrency, and duration per integration | No integration starves another, and throughput tests use production's numbers |
| "Which regulations apply, and which named control does each one impose?" | A licence is not a control; only verified configuration passes an audit (Gotcha 5) | One NFR per control with a UAT acceptance test | Compliance evidence exists before go-live, not after the auditor asks |
| "Which jobs must finish in which window, and how are they started?" | Scheduled Apex runs under synchronous limits (Gotcha 8) | The execution context and window per job | Batch windows sized on the limits the job will really get |
What proper configuration adds over "just writing NFRs": every requirement names a metric, a threshold, a measurement source, and an owner, and each one is tied to the platform limit or responsibility split that decides whether it can pass.
Core Concepts
NFR Categories for Salesforce
The five categories that must always appear in a Salesforce NFR register, mapped to Well-Architected pillars:
- Performance (Performance Efficiency pillar) — Page load times, report execution times, batch job completion windows, API response times. Must be expressed as Service Level Indicators (SLIs): "95th-percentile Lightning page load under 3 seconds measured in a Full sandbox." Vague targets ("fast") cannot be tested.
- Scalability (Performance Efficiency + Reliability pillars): Salesforce governor limits are hard, non-negotiable platform ceilings, not soft guidelines. Every scalability NFR must be expressed relative to these limits. Key limits: SOQL rows per transaction (50,000), DML statements per transaction (150), CPU time per transaction (10,000 ms Apex), heap size (6 MB sync / 12 MB async), cumulative callout timeout per transaction (120 s), daily API request allocation (varies by edition/user count). Architect for 50% headroom against any limit that correlates with data growth.
- Availability (Reliability pillar): Salesforce Trust publishes a 99.9% infrastructure uptime SLA (UNVERIFIED (2026-10-03): no fetched source states this figure; quote the customer's contract instead, see
references/gotchas.mdGotcha 3). This covers the platform, it does NOT cover: custom Apex code reliability, integration availability, org-to-org data sync, or data recovery time after a misconfigured bulk delete. The NFR register must distinguish infrastructure availability (Salesforce's SLA) from application availability (team's responsibility) and define RPO/RTO for backup scenarios. - Security and Compliance (Trusted pillar) — Regulations impose specific technical controls. GDPR requires data maps, right-to-erasure workflows, and audit logs. HIPAA requires encryption at rest (Shield Platform Encryption or Field Encryption), audit trails (Field History Tracking or Event Monitoring), and BAA with Salesforce. PCI-DSS scopes may require tokenisation or out-of-scope data routing. Each applicable regulation should generate a named NFR with a testable acceptance criterion.
- Usability (Easy pillar) — Page load time (overlap with performance), field count per page layout (recommend ≤ 30 visible fields per layout for cognitive load), mobile readiness (percentage of workflows completable on Salesforce Mobile), accessibility compliance (WCAG 2.1 AA for public or government-facing pages).
Well-Architected Framing
Salesforce organises its Well-Architected Framework across three top-level pillars: Trusted (security, compliance, reliability), Easy (usability, process efficiency), and Adaptable (scalability, resilience, composability). Every NFR category maps to at least one pillar. Using this framing ensures NFRs survive architecture reviews and are traceable to platform guidance.
Measurability Requirement
An NFR is only useful if it can be tested. Every NFR must include:
- A metric (what to measure)
- A threshold (acceptable vs. unacceptable value)
- A measurement method (where, when, and how to measure)
- An environment qualifier (sandbox tier, load profile)
Example of an untestable NFR: "The system must be responsive." Example of a testable NFR: "95% of Lightning record page loads complete in under 3 seconds, measured via browser-side performance tracing in a Full sandbox with 10 concurrent users simulated."
Common Patterns
Pattern 1: Governor Limit Translation
When to use: When business stakeholders provide scale targets like "we expect 500,000 cases per year" or "50 integrations running hourly."
How it works:
- Collect business scale numbers (records/day, concurrent users, API calls/day, batch window).
- Map each to the relevant governor limit category.
- Calculate expected utilisation as a percentage of the limit.
- Flag any dimension that exceeds 50% utilisation at the 3-year horizon as an architectural constraint requiring a design decision (e.g. async processing, chunking, Platform Events).
Why not the alternative: Treating governor limits as implementation details discovered during development leads to emergency re-architecture at go-live. They are first-class architectural constraints and must appear in the NFR register.
Pattern 2: Compliance Control Decomposition
When to use: When the project operates under a named regulation (GDPR, HIPAA, PCI-DSS, SOC 2).
How it works:
- Identify each applicable regulation.
- For each regulation, list the specific technical controls it requires.
- For each control, create a named NFR with a testable acceptance criterion tied to a Salesforce feature (Shield Encryption, Event Monitoring, Field Audit Trail, Connected App policies).
- Assign an owner (Salesforce admin, security team, data officer).
Why not the alternative: Listing "must be GDPR compliant" as a single NFR is untestable and unassignable. It will be interpreted differently by every reviewer and will fail a compliance audit.
Pattern 3: Availability Responsibility Mapping
When to use: Always — for every implementation. The shared responsibility model is never optional to document.
How it works:
- List every availability concern: infrastructure uptime, custom code reliability, batch job completion, integration uptime, data recovery.
- For each concern, assign responsibility to either Salesforce (infrastructure SLA) or the customer team.
- For customer-owned concerns, define RPO (recovery point objective) and RTO (recovery time objective).
- Document how each concern will be monitored (Salesforce Health Check, custom monitoring flows, integration heartbeats).
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Performance target is vague ("fast enough") | Define SLI with percentile, threshold, and measurement method | Untestable NFRs cannot gate go-live or be used in capacity planning |
| Scale target exceeds 50% of a governor limit at 3-year horizon | Raise as architectural constraint requiring design decision now | Governor limits cannot be increased; redesign is cheaper before build |
| Regulation named but controls not enumerated | Decompose into per-control NFRs with Salesforce feature mapping | Audit-ready compliance requires control-level traceability |
| Business says "we need 99.99% uptime" | Separate infrastructure availability (the contract's figure) from application reliability (team's responsibility) | Availability is a shared responsibility; custom code, integrations, and admin errors are team-owned |
| Project lacks usability NFRs | Add layout field count limits, mobile completion targets, WCAG level | Usability regressions are caught late and expensive to fix post-launch |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner working on this task:
- Collect project scope — org edition, feature set, regulatory context, integration landscape, and 3-year user and data volume projections.
- For each of the five NFR categories (performance, scalability, availability, security/compliance, usability), draft at least two measurable NFRs using the SLI format: metric, threshold, measurement method, environment qualifier.
- Translate business scale targets into governor limit utilisation percentages. Flag any dimension exceeding 50% at the 3-year horizon as an architectural constraint.
- Map each applicable regulation to the specific Salesforce features that satisfy its controls. Create one NFR per control, not one NFR per regulation.
- Document the availability shared responsibility split: which availability concerns are covered by Salesforce's infrastructure SLA, and which are customer-owned (with RPO/RTO defined).
- Review the NFR register against the Well-Architected pillars — Trusted, Easy, Adaptable — to confirm all three are addressed.
- Validate each NFR has a test method and an assigned owner. Remove or escalate any NFR that cannot be verified in a test environment.
Review Checklist
Run through these before marking work in this area complete:
- [ ] Every NFR has a metric, threshold, measurement method, and environment qualifier
- [ ] All applicable governor limits are represented as scalability NFRs with utilisation calculations
- [ ] The availability NFR register separates Salesforce infrastructure SLA from customer-owned availability
- [ ] Each applicable regulation has been decomposed into per-control NFRs, not a single "must be compliant" statement
- [ ] Usability NFRs include page load time, layout field count limits, and mobile readiness targets
- [ ] Every NFR has an assigned owner
- [ ] No NFR uses vague adjectives (fast, secure, reliable) without a measurable threshold
Salesforce-Specific Gotchas
The full list, with sources, is in references/gotchas.md. The ones that most often invalidate an NFR register:
| Gotcha | What it does to an NFR |
|---|---|
| Per-transaction limits ignore licence count (Gotcha 4) | A "1 million records a day" NFR is valid only for an async mode; one synchronous transaction stops at 50,000 rows |
| Shared responsibility for availability (Gotcha 3) | A bad deployment that breaks a trigger is the team's outage, so it needs its own RTO and RPO |
| Full sandbox only for scale tests (Gotcha 1) | Developer (200 MB) and Developer Pro (1 GB) sandboxes cannot validate a performance NFR; the earlier "Developer Pro 200 MB" statement was wrong |
| Concurrent long-running request limit (Gotcha 6) | A throughput NFR must state concurrency and duration, not only calls per day |
Output Artifacts
| Artifact | Description |
|---|---|
| NFR Register | Structured document with one row per NFR: category, metric, threshold, measurement method, environment, owner, status |
| Governor Limit Translation Table | Business scale targets mapped to Salesforce limit categories with utilisation percentages at launch and 3-year horizon |
| Availability Responsibility Matrix | Per-concern split between Salesforce infrastructure SLA and customer-owned availability, with RPO/RTO for customer-owned items |
| Compliance Control Checklist | Per-regulation breakdown of required controls mapped to Salesforce features, with testable acceptance criteria |
Related Skills
- ha-dr-architecture — use after NFR definition to design the technical solution for availability and recovery NFRs
- limits-and-scalability-planning — use to investigate specific governor limit headroom once scalability NFRs are defined
- security-architecture-review — use to validate that security and compliance NFRs are met by the org configuration
- well-architected-review — use to assess the full implementation against all three Well-Architected pillars