Apex Class Decomposition Pattern
Activate this skill when an Apex class has grown past the point where one class can comfortably hold all its responsibilities, when a trigger handler embeds SOQL, or when a service class has started issuing its own queries. The goal is the lightweight enterprise pattern this repo standardises on: a clear split into Trigger handler → Domain → Service → Selector, anchored by the canonical base classes in templates/apex/.
This is NOT a full fflib migration (no Application factory, Unit of Work, or interface registries) — see apex/fflib-enterprise-patterns for that. It is also NOT a trigger framework selection skill — see apex/trigger-framework for choosing between TriggerHandler styles.
The four roles
| Role |
Responsibility |
Must NOT do |
| Trigger handler |
Event dispatch — route before insert / after update / etc. to a Domain or Service method |
Hold business logic, run SOQL, do DML |
Domain (<X>Domain extends BaseDomain) |
Per-record validation and field derivation against a homogeneous Trigger.new collection |
SOQL, DML, callouts |
Service (<X>Service extends BaseService) |
Orchestration, transactions (savepoints), DML, platform events, callouts |
Issue SOQL directly (always go through a Selector) |
Selector (<X>Selector extends BaseSelector) |
All SOQL for a given SObject, named by intent (selectActiveByOwner(...)) |
DML, business rules, mutating state |
The base classes already encode the safety rails: BaseService exposes beginTransaction/rollbackTransaction/logAndRethrow, BaseSelector defaults to AccessLevel.USER_MODE, and BaseDomain operates over List<SObject> plus optional oldMap only.
Splitting signals
Split when any of these are true:
- The class is over 400 lines and trending upward.
- A single class issues SOQL, performs DML, validates per-record state, AND orchestrates cross-object work.
- The same SObject is queried from 3+ classes with copy-pasted SOQL — Selector overdue.
- Business logic lives directly inside a
trigger body or inside a handler that also runs SOQL.
- Test setup is dominated by mocking unrelated concerns (signals tangled responsibilities).
- A "Manager" / "Util" / "Helper" suffix appears and the class touches more than two SObjects.
Extension and naming rules
AccountsDomain extends BaseDomain — always plural SObject + Domain.
AccountMergeService extends BaseService — verb phrase + Service; one service = one cohesive use case.
AccountsSelector extends BaseSelector — plural SObject + Selector, one Selector per SObject.
- Trigger handlers stay in their own
<X>TriggerHandler class and own only the dispatch table.
- Cross-Service calls go through interfaces, not concrete types, so dependencies stay testable.
When NOT to split
- Throwaway one-off utilities (data fix scripts, one-time migrations).
- Prototypes still in flux where the responsibilities have not yet stabilised.
- Sub-100-line classes with a single responsibility — splitting just adds ceremony.
- Pure invocable wrappers around a single Service call.
Ordering of split (lowest risk first)
- Extract the Selector first. SOQL has the cleanest seam: move every
[SELECT ...] to <X>Selector methods named by intent. No behaviour change, easiest to verify.
- Extract the Service next. Move orchestration, DML, and savepoint handling into a
<X>Service that calls the new Selector. Use BaseService.beginTransaction() / logAndRethrow().
- Extract the Domain last. Pull per-record validation and field derivation into
<X>Domain operating on Trigger.new (and Trigger.oldMap when needed).
Reversing this order risks moving logic before its data dependencies are clear.
Stateful vs stateless
All three layers are stateless across invocations:
- Selectors take arguments, return query results, hold no caches.
- Services receive a request object (or arguments) per call and return a response — no instance fields holding mid-flight state.
- Domains hold the records they were constructed with for the duration of one trigger context only — they are not reused across transactions.
State that must persist belongs in a Custom Setting / CMDT / Platform Cache, not on a Service or Selector instance.
Anti-pattern: the "Manager" class
A class named AccountManager that opens savepoints, runs SOQL, validates per-record fields, and updates Contacts is doing all four roles at once. It is unbulkable, untestable in isolation, and a magnet for further bloat. Split immediately along the four-role boundary above.
Recommended Workflow
- Inventory the target class — count lines, list SObjects touched, mark every
[SELECT, every DML statement, every per-record loop with validation, and every callout.
- Classify each block by role (Trigger dispatch / Domain / Service / Selector) and confirm the split is justified by the signals above; if not, stop.
- Extract the Selector first — create
<X>Selector extends BaseSelector with intent-named methods, replace inline SOQL with calls to it, run tests.
- Extract the Service next — create
<X>Service extends BaseService, move DML/orchestration/savepoint handling, ensure SOQL only flows through the Selector.
- Extract the Domain last — create
<X>Domain extends BaseDomain, move per-record validation and derivation, ensure no SOQL/DML leaks in.
- Wire the trigger handler to dispatch to Domain (for
before validation/derivation) and Service (for after orchestration); keep the handler logic-free.
- Re-run the project test suite; run
scripts/check_apex_class_decomposition_pattern.py to confirm no Selector mutates and no handler still embeds SOQL.
Review Checklist
Output Artifacts
| Artifact |
Description |
| Split plan |
Mapping from old class blocks to new Domain / Service / Selector classes |
| New class shells |
<X>Domain, <X>Service, <X>Selector files extending the canonical base classes |
| Updated trigger handler |
Dispatch-only handler routing to the new layers |
| Decomposition checker run |
scripts/check_apex_class_decomposition_pattern.py clean exit |
Related Skills
apex/trigger-framework — choosing the trigger handler style
apex/fflib-enterprise-patterns — full-fat enterprise pattern (Application, UoW, mocks)
apex/apex-savepoint-and-rollback — transaction boundaries inside a Service
apex/apex-test-data-factory — testing strategy after decomposition
1---2name: apex-class-decomposition-pattern3description: "When and how to split an Apex class into Domain / Service / Selector layers using this repo's lightweight base classes (BaseDomain, BaseService, BaseSelector). Covers splitting signals, ordering of extraction, and naming conventions. NOT for a full fflib migration — use apex/fflib-enterprise-patterns. NOT for choosing a trigger handler framework — use apex/trigger-framework."4category: apex5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Scalability9tags:10 - apex11 - decomposition12 - domain13 - service14 - selector15 - architecture16 - refactoring17triggers:18 - "when to split apex class into service and selector"19 - "monolithic apex class refactor into domain service selector"20 - "trigger handler with embedded soql needs splitting"21 - "service class grew its own soql queries"22 - "how to apply enterprise patterns lightweight without fflib"23inputs:24 - Existing Apex class or trigger handler under review25 - SObject(s) the class operates on26 - Approximate line count and responsibility mix27 - Whether SOQL, DML, callouts, and per-record validation coexist28outputs:29 - Per-role split plan (Domain / Service / Selector)30 - New class names following the `<X>Domain`, `<X>Service`, `<X>Selector` convention31 - Extraction ordering (Selector first, then Service, then Domain)32 - Pointers to the matching base class under `templates/apex/`33dependencies: []34version: 1.0.035author: Pranav Nagrecha36updated: 2026-04-2837metadata:38 source: https://skillmd.com/skills/pranavnagrecha/apex-class-decomposition-pattern39---4041# Apex Class Decomposition Pattern4243Activate this skill when an Apex class has grown past the point where one class can comfortably hold all its responsibilities, when a trigger handler embeds SOQL, or when a service class has started issuing its own queries. The goal is the lightweight enterprise pattern this repo standardises on: a clear split into **Trigger handler → Domain → Service → Selector**, anchored by the canonical base classes in `templates/apex/`.4445This is NOT a full fflib migration (no Application factory, Unit of Work, or interface registries) — see `apex/fflib-enterprise-patterns` for that. It is also NOT a trigger framework selection skill — see `apex/trigger-framework` for choosing between TriggerHandler styles.4647## The four roles4849| Role | Responsibility | Must NOT do |50|---|---|---|51| Trigger handler | Event dispatch — route `before insert` / `after update` / etc. to a Domain or Service method | Hold business logic, run SOQL, do DML |52| Domain (`<X>Domain extends BaseDomain`) | Per-record validation and field derivation against a homogeneous `Trigger.new` collection | SOQL, DML, callouts |53| Service (`<X>Service extends BaseService`) | Orchestration, transactions (savepoints), DML, platform events, callouts | Issue SOQL directly (always go through a Selector) |54| Selector (`<X>Selector extends BaseSelector`) | All SOQL for a given SObject, named by intent (`selectActiveByOwner(...)`) | DML, business rules, mutating state |5556The base classes already encode the safety rails: `BaseService` exposes `beginTransaction`/`rollbackTransaction`/`logAndRethrow`, `BaseSelector` defaults to `AccessLevel.USER_MODE`, and `BaseDomain` operates over `List<SObject>` plus optional `oldMap` only.5758## Splitting signals5960Split when **any** of these are true:6162- The class is over **400 lines** and trending upward.63- A single class issues SOQL, performs DML, validates per-record state, AND orchestrates cross-object work.64- The same SObject is queried from **3+ classes** with copy-pasted SOQL — Selector overdue.65- Business logic lives directly inside a `trigger` body or inside a handler that also runs SOQL.66- Test setup is dominated by mocking unrelated concerns (signals tangled responsibilities).67- A "Manager" / "Util" / "Helper" suffix appears and the class touches more than two SObjects.6869## Extension and naming rules7071- `AccountsDomain extends BaseDomain` — always plural SObject + `Domain`.72- `AccountMergeService extends BaseService` — verb phrase + `Service`; one service = one cohesive use case.73- `AccountsSelector extends BaseSelector` — plural SObject + `Selector`, one Selector per SObject.74- Trigger handlers stay in their own `<X>TriggerHandler` class and own only the dispatch table.75- Cross-Service calls go through interfaces, not concrete types, so dependencies stay testable.7677## When NOT to split7879- Throwaway one-off utilities (data fix scripts, one-time migrations).80- Prototypes still in flux where the responsibilities have not yet stabilised.81- Sub-100-line classes with a single responsibility — splitting just adds ceremony.82- Pure invocable wrappers around a single Service call.8384## Ordering of split (lowest risk first)85861. **Extract the Selector first.** SOQL has the cleanest seam: move every `[SELECT ...]` to `<X>Selector` methods named by intent. No behaviour change, easiest to verify.872. **Extract the Service next.** Move orchestration, DML, and savepoint handling into a `<X>Service` that calls the new Selector. Use `BaseService.beginTransaction()` / `logAndRethrow()`.883. **Extract the Domain last.** Pull per-record validation and field derivation into `<X>Domain` operating on `Trigger.new` (and `Trigger.oldMap` when needed).8990Reversing this order risks moving logic before its data dependencies are clear.9192## Stateful vs stateless9394All three layers are **stateless across invocations**:9596- Selectors take arguments, return query results, hold no caches.97- Services receive a request object (or arguments) per call and return a response — no instance fields holding mid-flight state.98- Domains hold the records they were constructed with for the duration of one trigger context only — they are not reused across transactions.99100State that must persist belongs in a Custom Setting / CMDT / Platform Cache, not on a Service or Selector instance.101102## Anti-pattern: the "Manager" class103104A class named `AccountManager` that opens savepoints, runs SOQL, validates per-record fields, and updates Contacts is doing all four roles at once. It is unbulkable, untestable in isolation, and a magnet for further bloat. Split immediately along the four-role boundary above.105106## Recommended Workflow1071081. Inventory the target class — count lines, list SObjects touched, mark every `[SELECT`, every DML statement, every per-record loop with validation, and every callout.1092. Classify each block by role (Trigger dispatch / Domain / Service / Selector) and confirm the split is justified by the signals above; if not, stop.1103. Extract the Selector first — create `<X>Selector extends BaseSelector` with intent-named methods, replace inline SOQL with calls to it, run tests.1114. Extract the Service next — create `<X>Service extends BaseService`, move DML/orchestration/savepoint handling, ensure SOQL only flows through the Selector.1125. Extract the Domain last — create `<X>Domain extends BaseDomain`, move per-record validation and derivation, ensure no SOQL/DML leaks in.1136. Wire the trigger handler to dispatch to Domain (for `before` validation/derivation) and Service (for `after` orchestration); keep the handler logic-free.1147. Re-run the project test suite; run `scripts/check_apex_class_decomposition_pattern.py` to confirm no Selector mutates and no handler still embeds SOQL.115116## Review Checklist117118- [ ] Every `[SELECT` lives in a `<X>Selector` method named by intent119- [ ] No DML inside any class extending `BaseSelector`120- [ ] No SOQL/DML/callouts inside any class extending `BaseDomain`121- [ ] Trigger handler delegates only — no business rules in the handler body122- [ ] Service classes use `BaseService.beginTransaction()` for transactional work123- [ ] No "Manager" / "Util" class still bundling all four roles124- [ ] Cross-Service calls go through interfaces, not concrete classes125- [ ] All three layers remain stateless across invocations126127## Output Artifacts128129| Artifact | Description |130|---|---|131| Split plan | Mapping from old class blocks to new Domain / Service / Selector classes |132| New class shells | `<X>Domain`, `<X>Service`, `<X>Selector` files extending the canonical base classes |133| Updated trigger handler | Dispatch-only handler routing to the new layers |134| Decomposition checker run | `scripts/check_apex_class_decomposition_pattern.py` clean exit |135136## Related Skills137138- `apex/trigger-framework` — choosing the trigger handler style139- `apex/fflib-enterprise-patterns` — full-fat enterprise pattern (Application, UoW, mocks)140- `apex/apex-savepoint-and-rollback` — transaction boundaries inside a Service141- `apex/apex-test-data-factory` — testing strategy after decomposition