DEV Community: René Knierim

Design Salesforce Like a Distributed System

René Knierim — Mon, 22 Jun 2026 11:06:02 +0000

Distributed systems engineers don't get to reach across service boundaries whenever it's convenient. The network stops them. A microservice that needs data owned by another service can't just query it. It has to ask, wait, and handle failure. That friction is annoying. It's also the thing that enforces discipline: every team knows exactly where its responsibility ends, because the boundary is physical.

Salesforce gives you no such friction. Every object in your org, every Account, every Order, every custom object owned by another team, is one SOQL query away. Any Apex class can read it. Any trigger can write to it. Any Flow can fire on it. There is no network. There is no boundary. Nothing stops one domain from reaching into another's territory, and nothing makes that reach-in visible until something breaks.

That's the core problem this article addresses: how to design a Salesforce org with the discipline distributed systems engineers are forced to have, in an environment that will never force it on you. Platform Events and a principled trigger architecture are the tools. Bounded contexts, facts vs commands, and choreography or orchestration are the concepts. The prize is the same thing distributed systems get from their hard boundaries: teams that can ship independently without breaking each other.

This article is opinionated, grounded in real patterns from a production org, and the goal is that it shifts how you think about who's allowed to touch what, not just how to get work done async.
It is also not an argument that every Salesforce org should adopt a distributed systems pattern. Rather, this is a thought experiment exploring what changes when we analyze Salesforce from a distributed systems lens.

1. What Salesforce doesn't force on you (and why that's dangerous)

In a distributed system, the boundary between services is enforced by physics. Service B cannot read Service A's database directly. If it needs data, it calls an API, subscribes to an event stream, or maintains its own projection. These patterns (APIs, events, read models) didn't emerge from clever design thinking. They emerged because there was literally no other option.

The result is that distributed systems engineers develop a reflex: before touching anything, ask "do I own this?" If the answer is no, the question becomes "what's the sanctioned channel for getting what I need?"

Salesforce developers rarely develop this reflex, because the platform never punishes them for not having it. The consequence plays out slowly. In year one, one team writes a trigger on Contact and it works fine. In year two, three teams have logic in the same trigger handler. In year five, no one team can change the Contact object without coordinating with four others, running a full regression suite, and hoping nothing breaks in production. The org has become a non-distributed monolith: all the coupling of a distributed system with none of the boundaries, and no network to make the coupling visible.

Distributed systems thinking is the antidote. Not the mechanics (you don't need service meshes or gRPC), but the mindset: treat domain boundaries as if they were network boundaries, even though they aren't. Refuse cross-domain reach-ins the same way a service refuses direct database access from a neighbour. Use events as the only sanctioned channel for cross-domain communication.

The difference from the distributed world is that on Salesforce you have one significant advantage: the data is already local. You don't need to copy data across service boundaries, because there are no service boundaries at the database level. Every subscriber can re-query the source data directly. It's a SOQL call away. This changes the shape of event design considerably, as we'll get to in §7.

2. Domain bleed: what coupling without a boundary looks like

Distributed systems literature warns about the "distributed monolith": services so entangled they must deploy together, with all the pain of distribution and none of the independence. In Salesforce, you get a mirror-image problem: a non-distributed monolith. One schema, one automation surface, every team in everyone else's business, and no network boundary to make the coupling visible or enforce a fix.

Domain bleed is when one domain's logic executes inside another domain's territory. In Salesforce it looks like this:

Concrete symptoms, all of which you have seen:

A trigger nobody owns. AccountTrigger (or the one handler class) has commits from five teams. Touching it for a Billing change risks a Sales regression. Code review needs three squads.
Automation firing across domains. A Billing flow triggered by a field change on Opportunity, which Sales owns. Sales refactors a picklist; Billing breaks in production; nobody connected the two.
SOQL reaching three domains deep. A Support class queries Case → Contact → Account → Opportunity → OpportunityLineItem, encoding assumptions about four domains' models. Any of them refactoring breaks the query.
Validation rules encoding someone else's invariants. A rule on Contact enforcing a Marketing constraint that fires for every team that ever inserts a contact, including integration users that know nothing about it.
Shared fields with implicit contracts. A field added "just for Marketing" that automation, reports, and tests across the org now silently depend on.

The result is the same coupling a distributed system avoids by construction. Things that should be independent become one fragile thing, concentrated in a single org with a single deploy. You can't ship one domain without regression-testing the others. There is no slice any team fully owns. Velocity collapses as the org ages, and everyone blames "Salesforce technical debt" when the real diagnosis is missing boundaries.

Here's the critical distinction: the shared database is not the bleed. Co-located data is your advantage, not your problem. Distributed systems would kill for it. The bleed is control flow and ownership crossing boundaries: one domain reaching in to query, fire on, or write to another's objects. A distributed system can't do that because the network stops it. In Salesforce, you have to stop it yourself. Events are how you do it.

3. There are two kinds of event-driven Salesforce, and triggers are one of them

Before Platform Events: Salesforce already had an event-driven primitive that every Apex developer uses every day. Triggers are synchronous events. A record changes; the platform fires a before/after trigger; your code runs. The pattern is event-driven at its core.

The problem is ownership. And this is where the two models diverge sharply.

The trigger ownership problem

When a trigger is owned by everyone, it's owned by nobody. The classic symptom: a single AccountTrigger.cls (or one handler class dispatching to a dozen unrelated features) with commits from Sales, Fulfillment, Finance, and Support teams. The result:

Every team coupling to one file means nobody can deploy safely alone. The trigger becomes a bottleneck: a coordination tax for every change, regardless of which domain is touching it.

The old pattern, a TriggerFactory loading handlers from custom settings metadata, improved things by registering handlers per-object. But the fundamental problem remained: multiple teams could still register multiple handlers for the same object, and the execution order and interactions between them were implicit.

Trigger Actions: single responsibility, metadata-driven composition

A prime example of a trigger frame work that solves this issue at the architecture level is Mitch Spano's Trigger Actions framework. Each action is a focused, single-responsibility class that implements one interface:

// One class, one concern, one owner
public class TA_Order_Placed implements TriggerAction.AfterInsert {
    public void afterInsert(List<SObject> triggerNew) {
        // only Fulfillment domain logic here
    }
}

Actions are composed via metadata (Trigger_Action__mdt), not code. The trigger file itself becomes trivial, a one-liner that hands off to the framework:

trigger OrderTrigger on Order (after insert, after update, after delete) {
    new MetadataTriggerHandler().run();
}

What this buys you:

	Legacy `TriggerFactory`	Trigger Actions
Ownership	Multiple handlers, shared registration	One class per concern, clear owner
Composition	Code changes to add/remove	Metadata record, no deploy to wire up
Testing	Handler class tests mixed concerns	Each action tested in isolation
Bypass	Shared disable switch	Per-action bypass via custom permission
Order of execution	Implicit / registration order	Explicit order field on metadata

The metadata-driven composition is the key unlock. Sales can add a TA_Order_Placed action for Order without touching any file owned by Fulfillment. Fulfillment can add its own Order action independently. The trigger file never changes; it's infrastructure, not logic.

Async events: Platform Events

Platform Events are the asynchronous counterpart. Where trigger actions fire synchronously in the DML transaction, Platform Events cross transaction boundaries: publish now, process later, survive failures independently.

The right mental model for on-platform work:

Synchronous (trigger actions): "This just happened in my domain. Process it now, in this transaction."

Asynchronous (Platform Events): "This happened in my domain. Other domains should know about it, at their own pace, in their own transaction, on their own failure boundary."

Both are event-driven. The difference is timing, ownership, and what happens when something fails.

The property that makes it all work: the producer doesn't know its consumers

Here is the single most important thing about messaging, and the reason it cuts coupling where a direct call cannot. It's worth stating on its own because everything downstream depends on it.

When you call something (an Apex method, a @future, a queueable, a REST callout), the caller has to name the callee. The dependency points from producer to consumer. If a second consumer needs to react, you go back and edit the producer to call it too. The producer accumulates knowledge of everyone who depends on it, and every new reaction is a change to the thing that fired the event. That's true even when the call is asynchronous. A @future method is still point-to-point; async timing doesn't decouple anything, it just moves the same hard-wired call off the synchronous path.

Publish/subscribe inverts that arrow. The producer names an event, not a consumer. It announces "this happened" into the bus and is done. It does not know who is listening, and must not care. Consumers register their own interest by subscribing. The dependency now points from consumer to event contract, not from producer to consumer:

Two consequences fall out of this, and both are things a direct call (synchronous or asynchronous) simply cannot give you:

N consumers, zero producer changes. One published fact can fan out to one subscriber or fifty. Adding the fifty-first means deploying the new subscriber. The producer never learns it exists, never recompiles, never gets re-tested. In a point-to-point world, every new reaction is a change to the producer. In pub/sub, new reactions are purely additive and live entirely in the consumer's domain.
The dependency direction is reversed, and that's the whole game. "Who depends on whom" is the question that decides whether you can deploy independently. With a direct call, Sales depends on Fulfillment (it has to know Fulfillment exists to call it). With an event, Fulfillment depends on Sales's event contract (a stable, published fact) and Sales depends on nobody. The domain that owns the data is now ignorant of, and immune to, everyone reacting to it.

This is why "fire an async job" is not the same as "publish an event," even though both run later. The async job still couples the producer to a named consumer. The event doesn't. Decoupling comes from the inverted dependency, not from the asynchrony.

4. The cure: notify, don't reach in

Replace every cross-domain reach-in with a published fact. The domain that owns the data publishes "this happened." Domains that care subscribe and react in their own territory, on their own automation, on their own deploy cadence.

Nothing crosses a boundary except a fact. Fulfillment no longer fires on Order; it reacts to OrderPlaced__e and writes to its own Shipment__c. Finance no longer reaches into Sales's object graph; it subscribes to the same fact and manages its own Invoice__c. Sales can refactor everything behind Order as long as the published fact stays stable. You have drawn a bounded-context border inside one org, using events as the only sanctioned channel across it.

This is the reframe the generic posts miss. The bus isn't a data pipe here. It's a membrane: facts pass through, reach-ins don't. And the data stays exactly where it was, one query away, for whoever legitimately owns the context that needs it.

5. A cautionary tale: the order-handoff anti-pattern

Here is what domain bleed looks like when it wears an event-driven costume.

Imagine an order-to-fulfillment flow that uses platform events to chain processing steps: OrderHandoff_STEP1__e → OrderHandoff_STEP2__e → OrderHandoff_SHIPMENT__e → OrderHandoff_STEP4__e → ... Each step publishes the next event from its finally block:

// OrderHandoff_SHIPMENT handler (in the Sales domain)
} finally {
    if (triggerNext) {
        publishEvent('OrderHandoff_STEP4__e', !hasError);
    }
}

And in the shipment step, the Sales domain directly inserts Shipment__c records, which belong to Fulfillment:

// Sales reaching into Fulfillment's territory
orderToShipmentMap.put(
    orderId,
    new Shipment__c(
        Order__c = orderId,
        CarrierCode__c = orderDetail.CarrierCode__c,
        ServiceLevel__c = orderDetail.ServiceLevel__c,
        // ... a dozen more fields from Sales's data model
    )
);
Database.insert(orderToShipmentMap.values(), false);

The platform events look modern. But look at what Sales is actually doing:

It knows Shipment__c exists in the Fulfillment domain.
It knows the exact field-level schema of that object.
It writes directly to it.
It orchestrates the entire sequence. Fulfillment has no say in when or whether its own records get created.

Sales is reaching into Fulfillment's territory. The events just move the coupling off a shared trigger file and onto the data model. This is "domain bleed in a costume." If Fulfillment adds a required validation rule to Shipment__c, Sales's handoff breaks. If Fulfillment renames a field, Sales breaks. The dependency arrow points the wrong way.

The correct design: Sales publishes OrderPlaced__e carrying just the record ID and the timestamp. Fulfillment subscribes, queries the data it needs (same database, one SOQL call away), and creates its own Shipment__c in its own transaction, on its own schedule, under its own validation rules. Fulfillment owns shipment creation. Sales just announces that an order was placed.

This is the "notify, don't reach in" principle from §4. The event should state a fact in the publisher's past tense. OrderHandoff_SHIPMENT__e is not a fact; it's a command telling a later step to create something specific in another domain. If you can name the one subscriber that's supposed to handle it, you've written a command, and the coupling is still there.

6. A well-designed example: the Support domain

By contrast, the Support domain shows what the pattern looks like when it's right.

When a case is escalated, a Trigger Action publishes a CaseEscalated event outbound. Notice what it doesn't do: it doesn't reach into any other domain, it doesn't write to any other object, and it doesn't know who the subscribers are.

public class TA_Case_Escalated implements TriggerAction.AfterUpdate {
    IEventPublisher eventPublisher;

    public void afterUpdate(List<SObject> triggerNew, List<SObject> triggerOld) {
        Map<Id, Account> accountMap = TA_Case_Queries.getInstance().getAccountMap();

        for (Case c : (List<Case>) triggerNew) {
            if (shouldPublishEvent(c, accountMap)) {
                eventPublisher.addMessage('CaseEscalated', c, c.AccountId);
            }
        }
    }

    private Boolean shouldPublishEvent(Case c, Map<Id, Account> accountMap) {
        Account account = accountMap.get(c.AccountId);
        return account != null && account.Tier__c == 'Enterprise';
    }
}

What's clean about this:

Single responsibility. One action class, one concern. The trigger file is infrastructure: it delegates to MetadataTriggerHandler and contains no logic.
Fact, not command. CaseEscalated names something true in the Support domain's past tense. It doesn't tell anyone what to do with it.
Publisher is indifferent to consumers. Support doesn't know whether an account manager, a downstream warehouse, or a notification system will react. It announces; others decide.
Domain stays in its own territory. The action queries its own data (account tier), publishes to an abstract interface (IEventPublisher), and returns. No cross-domain DML.
The event publisher interface keeps the domain agnostic of the transport layer. Whether the platform event gets bridged to Kafka, routed to a middleware, or handled purely on-platform is infrastructure's concern:

public interface IEventPublisher {
    void addMessage(String messageName, SObject record, Id correlationId);
    void publish();
}

The contrast with the order-handoff flow is instructive. Both use events. Both have Trigger Actions wiring the logic. The difference is entirely in what the event means and who controls the downstream writes.

7. The rule that flips at the boundary

Here's the question that immediately follows "publish a fact": how much do you put in the event?

The microservices world has two answers, named by Martin Fowler:

Event notification: a thin signal. "Order 0061x placed." Just an id and what changed. The subscriber goes and looks if it needs more.
Event-carried state transfer: a fat, self-contained event. Everything a consumer could need, baked in, so it never has to call back.

People argue about which is "right." The argument is unresolvable because the right answer depends on whether the subscriber can cheaply query back, and on Salesforce that answer is different inside the org versus outside it. This is the rule:

Inside the org → thin notification events. The subscriber is in the same database. Re-querying is one cheap, current, transactional SOQL call. This is the Salesforce advantage a distributed system never has: the data is already local. Stuffing state into the event would duplicate data that's right there and instantly stale. So on-platform, publish OrderPlaced__e carrying little more than the record id and the change; let the Fulfillment trigger query the source data itself. Communication, not duplication.

At the external boundary → fat, self-contained facts. The moment the consumer is outside Salesforce, re-querying is expensive and coupling: a callback over the API, an auth handshake, latency, rate limits, and a hard dependency on Salesforce being up. So the events you publish outward should carry the full business fact: everything a downstream system needs to act without calling back.

A common pattern is a single outbound platform event (OutboundEvent__e) that acts as a generic envelope: on-platform triggers add messages via an event publisher interface, which serializes the payload and routes it outward (e.g. through a middleware layer to Kafka). The fat-vs-thin distinction maps cleanly onto that: inside the org, thin signals on domain-specific events; at the outbound envelope boundary, fat self-contained payloads.

And this is where your earlier instinct finally becomes correct: the read model, the projection, the materialized copy all belong downstream, outside Salesforce, fed by the fat boundary events. Not because projections are wrong, but because that is the place where data locality genuinely breaks and a local copy genuinely earns its keep. Inside the org you'd never build one. Across the boundary, you must.

So the same system uses both styles, and choosing by location dissolves the whole thin-vs-fat debate:

	Inside the org	At the external boundary
Subscriber can re-query?	Yes, cheap SOQL	No, expensive callback
Event style	Thin notification	Fat, self-contained fact
Carry full state?	No, it's already local	Yes, consumer can't fetch it
Build a projection?	Never, data is co-located	Yes, downstream where locality breaks
Event's job	Communication + ownership	Communication + data transfer

If you take one thing from this article, take this table. It's where Salesforce's data-locality advantage changes the rules, and where the distributed-systems playbook applies unchanged.

8. Facts, not commands (the bleed wears a costume)

Domain bleed has a sneaky form that survives even after you've "gone event-driven." It's the command disguised as an event:

// Bleed in a costume. Not an event.
CreateShipment__e evt = new CreateShipment__e(OrderId__c = orderId);
EventBus.publish(evt);

CreateShipment__e is not a fact. It's the publisher reaching across a boundary to tell one specific subscriber what to do, just routed through the bus so it looks decoupled. The publisher still knows the shipment step exists, still knows what it should do, still breaks when that domain changes. You've moved the bleed onto the event bus, not removed it.

A real fact names something true in the publisher's domain, in the past tense, and is indifferent to who reacts:

// A fact. Past tense. Publisher's domain. Reaches into no one.
OrderPlaced__e evt = new OrderPlaced__e(
    OrderId__c   = order.Id,
    AccountId__c = order.AccountId,
    PlacedAt__c  = System.now()
);
EventBus.publish(evt);

The litmus test:

A fact says "X happened." A command says "service Y, do Z." If you can name the one subscriber that's supposed to handle it, you've written a command, and the coupling you were trying to cut is still there, now harder to see.

It's the name, not the transport

Here's the crucial point, and it's where a lot of advice goes wrong: a Platform Event can legitimately carry either a fact or a command. Nothing about the platform forces the distinction. The same EventBus.publish() call ships both. The difference lives entirely in how you name and shape the message, and in whether you're honest about which one it is.

You don't need a separate piece of infrastructure (a queue product, a second bus) to carry commands. That's the import error again: borrowing "facts go on the event bus, commands go on a queue" from architectures where those are physically different systems. On Salesforce, both are just Platform Events. What keeps the line honest is naming discipline, not a second transport:

	Fact	Command
Name	Past tense: `OrderPlaced__e`	Imperative: `RecalculateDiscount__e`
Answers	"What happened?"	"What should be done?"
Knows the recipient?	No, indifferent to who reacts	Yes, aimed at a specific handler
Consumers	Zero to many	Exactly one (it's a directed instruction)
Coupling	Publisher depends on no one	Publisher depends on the handler existing

Commands aren't evil; they're necessary. Sometimes you genuinely do need to instruct one specific handler to do one specific thing. The mistake is dressing a command up in fact's clothing (a thin event that looks decoupled but names exactly one intended subscriber) and then believing you've cut the coupling. If it's a command, name it like one: imperative, owned by the caller, pointed at a known handler, so the coupling is at least visible and you can decide whether it belongs. The danger isn't commands on the bus; it's commands pretending to be facts.

9. Who owns the cross-boundary flow? Choreography or orchestration

Once you've drawn borders, some business processes still span them, and you have to decide how they're coordinated. The cheap version of this debate is "choreography good, orchestration bad." It's wrong, and on Salesforce you can fall into the failure mode of either one.

Default to choreography. Facts on the bus; whoever cares reacts. Loosely coupled, scales by addition. Right for "a thing happened, others may want to know."
Reach for orchestration deliberately, when a process spans domains and must complete, needs ordering or end-to-end visibility, or has to be undoable (compensation).

The sentence to tattoo on the team:

Someone has to own the multi-step transaction. Pick the owner on purpose.

The order-handoff anti-pattern from §5 illustrates this. Several steps chained via platform events, each step publishing the next, with no single owner tracking whether the whole thing succeeded. It's "Lambda pinball": an emergent chain nobody owns end-to-end, impossible to trace holistically, with no clean answer to "did the handoff finish, and how do we compensate if a middle step failed?" Per-step observability and error logging helps, but that's a bandage on a structural problem.

The fix is not a central god-orchestrator micromanaging anemic domains. It's a local coordinator: a state machine that owns the process, issues commands, and tracks completion, while the business logic stays in the domain handlers. For long-running, undoable processes you want a saga, where each step registers a compensating action so a half-finished process rolls back cleanly.

One honest caveat: the elegant "just use a local in-process engine" advice from the JVM world assumes a free-form runtime. On Salesforce your coordination primitives are Flow, Platform Events, and async Apex, all under governor limits, so you own the process explicitly within that async model.

The two anti-patterns, both reachable on-platform:

Events that are secretly commands → hidden coupling, no owner.
An orchestrator babysitting steps that are really independent reactions → a bottleneck for nothing.

10. Splitting the monorepo into domains

The architecture above only pays off if you can actually enforce the boundaries it describes. Domain isolation in a Salesforce org isn't just about code style - it's a deployment question.

A repo that takes this seriously reflects it in directory structure. Rather than one flat src/ folder where every team drops files, you organize by bounded context:

src/
├── domain-core/              # Shared infrastructure (trigger       # Event bus infrastructure (platform event objects, routing metadata)
├── domain-sales/             # Leads, opportunities, orders
│   ├── lead-management/
│   ├── opportunity/
│   └── order/
├── domain-fulfillment/       # Shipments, inventory, logistics
│   ├── shipment/
│   ├── inventory/
│   └── logistics/
├── domain-finance/           # Invoicing, billing, payments
├── domain-support/           # Case management
└── _common-modules/          # Cross-cutting UI components and utilities

Each domain is a candidate for its own unlocked package (2GP). A domain can refactor its internals freely as long as the events it publishes stay compatible.

Deployment decoupling is the one that changes how fast your org can move - and it's only reachable once cross-domain communication goes through facts instead of reach-ins.

In a bled org, the deployment unit is the whole org. With events as the only sanctioned cross-domain channel, each domain can become its own independently-shippable unit. Fulfillment deploys on Tuesday. Sales deploys on Thursday. Neither regression-tests the other, because neither reaches into the other's objects.

11. The field guide: Platform Event mechanics that actually decide success

Everything above is design. This is the part where the platform's specific behaviour makes or breaks it. These are fact-checked against current Salesforce documentation, because half the lore floating around is stale.

Publish behaviour, and a footgun

When you define an event you choose when it publishes:

Publish Immediately (default): fires when the publish() call executes, regardless of whether the transaction commits. A subscriber can receive the event before - or even when - the publishing transaction rolls back. Great for fire-regardless and logging-style events; a footgun if the subscriber expects committed data, because you can emit OrderPlaced for an order that then never existed. It counts against a separate limit of 150 EventBus.publish() calls per transaction (Limits.getPublishImmediateDML()).
Publish After Commit: publishes only after the transaction commits successfully, not at all if it fails. Use it when the subscriber will go query the data you just wrote (which, given thin events, is most of the time on-platform). It counts as one DML statement each (Limits.getDMLStatements()).

That distinction interacts directly with §7: thin notification events usually want Publish After Commit, because the subscriber's whole plan is to re-query, and re-querying a rolled-back record is a bug. If you're using a generic outbound envelope event to bridge to external systems, PublishAfterCommit is the right default for exactly this reason.

A successful publish is a successful enqueue, not a delivery

High-volume events (the default for new events since API v45.0) publish asynchronously. After publish() returns success, the request is queued; the actual publish happens when resources free up, and in rare cases the async publish can fail after your synchronous call already returned "success." If you need certainty of the final result, use Apex Publish Callbacks. Don't treat a green publish() as proof of delivery.

Subscribers, and who pays the delivery bill

You get a genuinely broad set of subscriber types: Apex triggers, Flows/processes, empApi (an LWC CometD client, for live UI), Pub/Sub API (gRPC over HTTP/2, the modern external path), and CometD (legacy). Worth knowing: Apex triggers, processes, and flows don't count against the event delivery allocation - only CometD-style clients do, and for empApi it's metered per channel, per browser session.

Durability - the bus is not an event store

Retention: high-volume events live in the bus for 72 hours; the older standard-volume events (definable only before Spring '19, now being retired) for 24 hours. Then purged.
Max message size: 1 MB. Fat events still have a ceiling - another reason the fat ones belong at the boundary, carrying a business fact, not a kitchen sink.
No SOQL/SOSL on events, no reports, no list views. If you need to see that an event fired, you persist a trace yourself. Events are shouted, not stored.

This is the deepest reason §7's projections live downstream: the platform deliberately doesn't durably store events, so your long-term, replayable, queryable copy belongs on a real log (Kafka/Redpanda) that is built for retention - outside Salesforce.

Scaling out: it's broadcast, not consumer groups

The intuitive Kafka model: add consumers, partitions distribute, each message processed once - does not apply to external Salesforce subscribers. Per Salesforce's own docs, if you start multiple Pub/Sub API subscriptions for the same org and topic, each stream is independent and the same events are delivered to every subscriber. Scale a gRPC connector from one pod to three and you get every event three times, not a third each. The burden is deduplication (on the EventUuid / id field), not partition assignment. To actually parallelise, consume once and fan the work onto a real log with real consumer groups.
The one place you get competing-consumer semantics is on-platform: Apex parallel subscribers, where one trigger runs as multiple concurrent instances and Salesforce assigns each event to exactly one, partitioned by a key (default: a hash of EventUUID, which randomises, and therefore does not preserve order). Need ordering within an entity? Set the partition key to that entity's id: ordered within a key, parallel across keys, exactly like a Kafka partition key.

Errors, retries, and the replay asymmetry

Inside an Apex subscriber you get a real retry model: throw EventBus.RetryableException and the batch is resent after an increasing delay, in original ReplayId order, up to 10 total runs (initial + 9 retries) before the subscription moves to an error state. Read the attempt count via EventBus.TriggerContext.currentContext().retries so you cap your own retries:

trigger OrderPlacedTrigger on OrderPlaced__e (after insert) {
    try {
        FulfillmentService.handle(Trigger.New);
    } catch (Exception e) {
        if (EventBus.TriggerContext.currentContext().retries < 6) {
            throw new EventBus.RetryableException(e.getMessage());
        }
        Logger.error('OrderPlaced handler exhausted retries', e);
    }
}

For partially-processed batches, checkpoint with EventBus.TriggerContext.currentContext().setResumeCheckpoint(replayId) so a retry resumes after the last success instead of redoing it - important because uncatchable limit exceptions (DML/SOQL governor limits) can't be caught, and an un-checkpointed batch's unprocessed events aren't redelivered.

The asymmetry to remember: there is no Apex API to replay an arbitrary historical event by ReplayId. From Apex you can resume a suspended subscription (from earliest, or "from tip" to skip poison events), checkpoint within a batch, or publish a new event - but arbitrary replay-by-id within the retention window is an external-subscriber capability (Pub/Sub API and CometD let you subscribe from Earliest, Latest, or a custom ReplayId). Once again: durable replay lives downstream, not in Apex.

12. The one thing the integrated platform gives you that Kafka doesn't

For all the constraints, Platform Events have a genuinely lovely property a raw Kafka setup lacks: one fact can drive backend logic and live UI at the same time, with almost no extra plumbing.

Backend: an Apex trigger on the __e reacts and runs domain logic.
Frontend: an LWC subscribes to the same channel via empApi and updates in real time.

import { subscribe, unsubscribe, onError } from 'lightning/empApi';

connectedCallback() {
    subscribe('/event/OrderPlaced__e', -1, (response) => {
        this.handleEvent(response.data.payload);
    }).then((sub) => { this.subscription = sub; });
    onError((error) => console.error('empApi error', JSON.stringify(error)));
}
disconnectedCallback() { unsubscribe(this.subscription, () => {}); }

A single OrderPlaced__e, published once, can drive backend logic (Apex), refresh an ops team's live dashboard (LWC), and hit Kafka for the rest of the company (Pub/Sub API bridge). This is the producer-knows-no-consumers property from §3 made vivid: three subscribers across two completely different runtimes - Apex and JavaScript - and the publisher knows about none of them. Add a fourth and the publisher still doesn't change. One fact, N consumers, zero coupling between them - provided the fact is a fact and not RefreshOrdersDashboard in disguise. Operationally, remember empApi is a CometD client and meters per browser session, so a thousand open dashboards is a thousand subscriptions.

13. The contras, stated plainly

This is not friction-free, and the JVM-world defaults don't all survive contact with the platform:

The bus is not a store. 72h / 24h retention, no SOQL, no native audit. Durability is your job - downstream.
No arbitrary replay from Apex. Suspend/resume and checkpoints only; true replay-by-id is external.
Fan-out, not consumer groups, for external subscribers. Scaling out means deduping, not load balancing.
Governor and async limits constrain orchestration. Local-engine sagas don't port one-to-one.
1 MB cap and limited field types. Fat events have a ceiling.
Publish-immediate footgun. Events can reference data that never committed.
Observability tax. You trade the easy end-to-end call stack for emergent flows. Eventual consistency becomes something you engineer - idempotent handlers, lag monitoring, reconciliation for any fire-and-forget fan-out with an SLA.
Trigger action discipline. Single-responsibility actions only pay off if the team enforces it. Without governance on Trigger_Action__mdt, you end up with the same chaos as the old shared handler class, just in metadata form.

Borders cost discipline. Bleed costs velocity. Pick your bill.

14. Finding the borders: event storming

Everything so far assumes you already know where the boundaries are and which facts matter. In a mature org you usually don't - the knowledge is scattered across the heads of admins, developers, and the business people who actually understand the process. Event storming is the workshop technique for getting it out of those heads and onto a wall before you write a line of Apex.

The mechanics are deliberately low-tech: a long roll of paper (or a digital whiteboard) and sticky notes in a few colours. You get the people who know the business in one room and reconstruct what actually happens, using a fixed vocabulary of colours:

Orange: domain events (facts). Something that happened, past tense: Order Placed, Shipment Dispatched, Invoice Issued. You brainstorm these first and arrange them left-to-right in time. This is the raw material for your Platform Events.
Blue: commands. The action or decision that caused an event: Place Order, Dispatch Shipment. Note the one-to-one feel - a command, when it succeeds, produces an event. This is exactly the fact-vs-command distinction from §8, discovered on the wall before it's encoded in a name.
Yellow: actors / roles. Who issues the command - a sales rep, a warehouse operator, a system integration.
Pink: external systems. Anything outside the org that emits or receives - the payment gateway, the carrier's shipping API. These pink notes are where your fat boundary events from §7 will live.
Purple: policies. "Whenever this event happens, that command should fire." Purple notes are the reactive glue - and crucially, they reveal cross-domain reach-ins. A policy that says "whenever Order Placed, create the Shipment" is the order-handoff anti-pattern from §5, caught on a sticky note.

The borders emerge on their own. As the orange events line up across the timeline, you'll see them cluster - a run of sales facts, then a run of fulfillment facts, then finance. The seams between the clusters are your bounded contexts. You didn't impose them top-down; the language did. Where the business stops using one set of nouns and starts using another is exactly where one domain ends and the next begins. Draw a vertical line there and you've found a border to defend with an event.

What event storming gives you, concretely, before any migration:

A candidate list of Platform Events - every orange note is a fact you might publish.
The bounded contexts - the clusters become your domain-* packages from §10.
The reach-ins to kill - every purple policy that crosses a cluster line is a place a domain is reaching into another's territory. Those are your refactor targets, prioritised by how much pain they cause.
A shared language - the admins and developers now describe the system the same way, which is half the battle in cutting domain bleed.

You don't need a two-day formal workshop to start. Even a 90-minute "big picture" storm of one painful flow - the order handoff, say - will surface more hidden coupling than a week of reading code, because it pulls in the people who know what the system is supposed to do, not just what it currently does.

15. How to get there without a rewrite

You don't refactor a twelve-year-old org in one go. Use branching by abstraction:

Keep internals as they are.
Define a clean set of facts at each context's edge and publish them - thin on-platform, and bridged (e.g. via Redpanda Connect) to a real log as fat boundary facts for the wider company.
Move downstream consumers onto that durable, properly-partitioned stream instead of subscribing to raw Platform Events.
Migrate trigger logic from shared handler classes to Trigger Actions, one object at a time - the metadata-driven composition means you can wire up new actions without touching the trigger file.
Peel domains into their own packages behind those stable contracts, on your own schedule.

The facts are the contract. Everything behind them is yours to modernise; everything in front sees clean borders - even while the engine room is mid-renovation.

The hardest part isn't the platform mechanics - it's the cultural shift. Publishing a fact and trusting other domains to react is slower in the short term than reaching in and doing it yourself. The order-handoff anti-pattern from §5 exists because it works - it's just not owned. Inverting it requires accepting that a domain's records are that domain's responsibility, even when another domain is the trigger for creating them. That discipline is what makes independent deployability real.

16. Takeaways

Treat domain boundaries as if they were network boundaries. Distributed systems engineers get this for free; on Salesforce you have to enforce it yourself. The discipline is identical - only the mechanism differs.
The shared database is your advantage, not your problem. Distributed systems copy data across service boundaries because they have no choice. You can re-query. Use it - keep events thin on-platform, fat only at the external boundary.
There are two kinds of event-driven Salesforce. Triggers are synchronous events; Platform Events are async. Both require the same ownership discipline; the difference is timing and failure boundaries.
Trigger ownership is an architecture decision. A trigger owned by everyone is owned by nobody. Trigger Actions with metadata-driven composition give you single responsibility, independent deploy, and explicit ordering - the same guarantees a service boundary gives a distributed system.
Domain bleed is the core failure mode - one domain reaching into another's objects, queries, and automation. Events are the membrane: facts cross boundaries, reach-ins don't.
Facts, not commands. If you can name the one subscriber meant to handle it, you've written a command. The coupling is still there, just on the bus now.
Thin inside, fat at the external boundary. Inside the org, thin notifications - the data is a query away. Outward, fat self-contained facts. That's the only place a read model projection belongs.
Pick the owner of every cross-domain flow on purpose. Default to choreography; reach for orchestration when a process must complete end-to-end and someone needs to own whether it did.
Split your repo into domains. Directory structure is the first step toward independent packages. Code isolation is the prerequisite for deployment isolation.
Know the mechanics cold - publish behaviour, async publish + callbacks, retention, broadcast vs parallel subscribers, retry/checkpoint, no-arbitrary-replay-from-Apex.
The prize is independent deployability. Distributed systems get it from service boundaries. You get it from event contracts. Same outcome, different path.

The platform is a tool, not an identity. Distributed systems engineers don't get credit for their hard boundaries - the network just forces them. The work on Salesforce is choosing to hold those same boundaries when nothing makes you.

So don't wait for a rewrite, and don't try to redraw the whole org at once. On your next change, find one place where a domain reaches across a boundary it doesn't own - one trigger, one cross-domain write, one query reaching three objects deep - and replace just that reach-in with a published fact. Draw one border. That single event is the first place your org starts behaving like the distributed system it always secretly was.

Glossary

This article borrows vocabulary from distributed systems and domain-driven design. If you came up through the admin/declarative side of Salesforce, here's the plain-English version of each term, in roughly the order it appears.

Domain / subdomain. A cohesive area of the business with its own data and rules - Sales, Fulfillment, Finance. On Salesforce, a domain is the set of objects, automation, and code one team owns. The opposite of "one big shared org where everyone edits everything."
Bounded context. The boundary around a domain inside which a word means exactly one thing. "Account" might mean a prospect in Sales and a billing entity in Finance; a bounded context is where you decide which. The seam between two contexts is exactly where you draw a border and put an event.
Domain bleed. This article's term for one domain's logic running inside another's territory - querying its objects, firing on its records, or writing its fields. The disease the whole article is about.
Coupling. How much one piece of code depends on another. Tight coupling means changing A forces you to change (and re-test) B. The goal is loose coupling - domains that can change independently.
Distributed monolith. A system split into pieces that still have to deploy together because they're too entangled - all the cost of being distributed, none of the independence. The "non-distributed monolith" is the Salesforce mirror image: one org, but the same entanglement.
Fact vs command. A fact (or domain event) states something that already happened, past tense: OrderPlaced. A command instructs a specific handler to do something: CreateShipment. Both can ride on a Platform Event - the difference is naming and intent (see §8).
Producer / consumer (publish / subscribe). The producer publishes a message and doesn't know who's listening. Consumers subscribe to declare their own interest. This is what "the producer doesn't know its consumers" means - the dependency points from consumer to event, not the other way around.
Event notification (thin) vs event-carried state transfer (fat). A thin event carries just an id and what changed; the subscriber re-queries for details. A fat event carries the whole payload so the subscriber never has to call back. Thin inside the org, fat at the external boundary (see §7).
Projection / read model. A pre-built copy of data, shaped for fast reading, kept in sync by listening to events. On-platform you almost never need one (you can just SOQL the source). Downstream of Salesforce - in Kafka, a warehouse - you build them because re-querying across the boundary is expensive.
CQRS (Command Query Responsibility Segregation). The pattern of separating the write side (commands) from the read side (queries/projections). Mentioned mainly to say: it's a downstream concern, not something you build inside the org.

Why Salesforce Debug Logs suck and how I fixed them

René Knierim — Sun, 21 Jun 2026 09:11:34 +0000

If you are a Salesforce Developer, you know the drill:

Develop
Deploy
Enable Debug Logs for a User or open Developer Console
Test
Something breaks -> inspect the Debug log
Download the Debug log and use it with the Apex Log Replayer

For me, this always felt a bit icky. Why do I have to go through a full release cycle, interact with the org, and find and download the log to even get the most basic information about what happened in the backend?

And that's one of the keywords here. Something already happened. I created an error on the Org that I might even share with other people and developers. Let alone if it is a production org that faces this issue. Every fix I deploy will affect other people and needs to go through a full release cycle, just to check again retrospectively if it is fixed.

Apex again is the odd one out in the world of programming languages. Its historic strength to develop directly against the platform turns out to be a big time consumer on complex orgs.

Debugging at Runtime

Imagine for a second you are not a Salesforce developer, but you develop in Java, Go, Kotlin, Swift or any other widely used programming language. There is no Org, no server you deploy to, nothing that generates Debug Logs for you during your dev cycle to debug issues.
Instead, you can execute those languages on your machine. And because they execute on the machine, your IDE enables you to set breakpoints and inspect every single variable. All that without going through a release cycle to a Sandbox or a Scratch org. And all that without cluttering your machine with tons and tons of old debug logs that you forgot to delete.
If this is something you have dealt with in the past and would like to experience the same comfort as developers in other languages, having a look into Nimbus might be worth your time

Nimbus is a full local Apex Runtime and Debugger. It runs your Apex code against an embedded database as if you were on a Salesforce org, with the only difference that you don't need a Sandbox or a Scratch Org to verify what you have built

Set up Nimbus in less than a minute: https://github.com/nimbus-solution/nimbus and go Pro for free

Get the VSCode and IntelliJ plugins and improve you development cycle today!

Found something that doesn't work as expected? Leave us an issue in GitHub or reach out to us directly in our Slack community

Trunk-Based Development Working for Salesforce Without a Single Org

René Knierim — Sat, 20 Jun 2026 23:54:18 +0000

I've wanted easy trunk-based development for Salesforce for years.

Short-lived branches, frequent merges, small pull requests, and CI fast enough that developers aren't afraid to commit. The same practices that engineering teams use everywhere else.

Every time I tried to make it work, I hit the same wall: Apex tests require an org.

That single dependency turns every validation run into an infrastructure problem. Before a test can execute, you need authentication, environment provisioning, metadata deployment, test execution, and cleanup. The result is feedback loops measured in minutes instead of seconds.

I got tired of waiting and built Nimbus, a local Apex runtime that executes Apex tests without an org.

This is what I learned while trying to make trunk-based development actually work for Salesforce.

Why trunk-based development is hard in Salesforce

Trunk-based development depends on fast feedback. If validation takes seconds, developers make smaller changes, merge more frequently, and keep branches short-lived. If validation takes fifteen minutes, behavior changes. Pull requests get larger, unrelated work gets batched together, and validation stops happening continuously because validation itself becomes expensive.

Salesforce has always had a structural challenge here because Apex only runs inside Salesforce.

A typical validation pipeline looks something like this:

sf org login jwt
sf org create scratch
sf project deploy start
sf apex run test
sf org delete scratch

There is nothing inherently wrong with these steps. The problem is that most of them have nothing to do with testing. They're infrastructure management. The actual validation of business logic is only one part of the process.

The longer I worked with Salesforce CI, the more obvious it became that the bottleneck wasn't Apex itself. The bottleneck was everything required to create an environment where Apex could run.

The solutions I tried first

Before building a local runtime, I tried solving the problem the same way most Salesforce teams do.

If Apex tests require an org, the obvious answer is to make org creation faster. Scratch org pools, sandbox pools, pre-provisioned environments, and reusable test orgs all sound reasonable on paper.

In practice, I found myself building infrastructure whose only purpose was making test execution possible.

A scratch org pool still needs a Dev Hub. It still needs authentication. It still needs lifecycle management. Someone has to create orgs, monitor capacity, replenish exhausted pools, rotate certificates, and investigate failures when something inevitably goes wrong.

Sandbox pools introduce a different set of problems. Now you're dealing with shared state, refresh cycles, environment drift, and coordination between teams. The CI pipeline becomes responsible not only for validating code, but also for managing a fleet of Salesforce environments.

I spent a lot of time trying to make these approaches work. They helped, but they never solved the underlying problem.

The dependency was still there.

Whether the org was created on demand, pulled from a pool, or shared across teams, every test run still depended on Salesforce infrastructure existing before validation could begin.

Eventually I realized I was optimizing around the dependency instead of removing it.

If trunk-based development was the goal, I didn't need faster orgs.

I needed no orgs.

The dependency I wanted to remove

When I started building Nimbus, the goal wasn't to create a faster CI pipeline, but the goal was simpler.

I wanted to run Apex tests without needing Salesforce infrastructure.

That meant solving many of the same problems I described in a previous article: parsing Apex, executing Apex code locally, supporting DML and SOQL, reproducing trigger behavior, implementing test isolation, and matching Salesforce runtime semantics.

A local runtime that behaves differently from Salesforce is worse than useless. If local tests pass and org tests fail, developers stop trusting the tool. Every design decision ultimately came down to one question:

"Does this behave the same way Salesforce behaves?"

Because if the answer was no, nothing else mattered.

What changes when Apex runs locally

Once tests no longer require an org, something interesting happens.

Large parts of the pipeline disappear.

The GitHub Actions workflow for one of my demo projects looks like this:

name: Apex Tests

on:
  pull_request:
    branches: [main]

jobs:
  apex-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Nimbus
        run: curl -fsSL https://install.testnimbus.dev | sh

      - name: Run Apex tests
        run: |
          nimbus test "*" \
            --coverage --coverage-report coverage.xml \
            --results-xml results.xml

No Dev Hub.

No scratch org.

No source deployment.

No org cleanup.

Nimbus produces JUnit and Cobertura reports, so existing tooling still works. Coverage gates, pull request checks, SonarQube analysis, and test reporting continue operating exactly as before.

The difference is that the tests execute directly against the source code in the repository rather than a deployed copy inside an org.

The repository becomes the source of truth

This ended up being one of the most important shifts.

Traditional Salesforce development often treats the org as the thing being tested. Code is deployed into an environment, and that environment decides whether the code works.

In most software ecosystems, the repository itself is the source of truth. The code in Git is the thing being compiled, tested, and validated.

A local runtime pushes Salesforce closer to that model.

Nimbus reads the SFDX project directly from disk and executes the code that's actually committed to source control. There is no deployment step sitting between the code and the test run.

The org stops being a development dependency and starts becoming a deployment target.

That sounds like a subtle distinction, but it changes how the workflow feels.

What changed in the inner loop

The biggest difference wasn't CI.

It was how I wrote code.

Before, a typical iteration looked like this:

Edit Apex
Deploy to an org
Wait
Run tests
Wait
Fix the bug
Repeat

With a local runtime, the loop becomes:

Edit Apex
Run tests
Fix the bug
Repeat

The difference isn't just speed.

Developer behavior changes when feedback becomes cheap.

You run tests more often. You refactor more confidently. You make smaller changes and catch mistakes earlier. Validation stops being something you do at the end of a feature because validation is no longer expensive.

The workflow starts looking much closer to what developers in other ecosystems have had for years.

What changed in CI

The CI improvements were almost a side effect of solving the local testing problem.

One of the BerlinBrew demo runs currently executes 157 tests with over 93% coverage. The GitHub Actions workflow completes in about 30 seconds, and the actual Apex execution takes roughly one second. Most of the remaining time comes from GitHub Actions startup overhead.

More importantly, the pipeline becomes dramatically simpler.

There are no org credentials to manage. There are no scratch org limits to monitor. There are no deployment failures unrelated to the code being tested.

The build focuses on validating behavior.

That's what CI should be doing in the first place.

What I learned

A few things surprised me during this journey.

The first is that most Salesforce CI time is not spent running tests. It's spent preparing an environment capable of running tests.

The second is that developers adapt their workflow to the speed of feedback. Fast feedback encourages small pull requests. Slow feedback encourages batching.

The third is that many of the challenges people associate with trunk-based development in Salesforce aren't really process problems.

Most teams already understand the benefits of smaller changes and more frequent merges. The difficult part is making validation fast enough that those practices become natural.

And finally, I learned that scratch orgs are often doing two completely different jobs at once.

They're acting as deployment targets and test environments.

Once those responsibilities are separated, a lot of complexity disappears.

Does this replace Salesforce?

No.

There are still platform features that require a real org. Nimbus is not trying to replace Salesforce.

It's trying to remove Salesforce from the parts of the development loop where Salesforce isn't adding value.

For many Apex tests, that turns out to be a much larger portion of the workflow than I originally expected.

Try it

Nimbus runs directly against existing SFDX projects.

curl -fsSL https://install.testnimbus.dev | sh
nimbus test

If you've ever wanted Salesforce development to feel more like every other modern software stack, this is the closest thing you will find.

I Built a Local Apex Runtime - Nimbus

René Knierim — Tue, 16 Jun 2026 20:22:54 +0000

Every Salesforce developer knows the wait. You change three lines of Apex, run your tests, and then go make coffee, because deploying to a scratch org and running the suite takes minutes. There is nothing useful you can do in that gap except lose your train of thought.

I got tired of that gap, so I built Nimbus. It runs Apex tests locally, with no org and no Docker, in about a second.

This post is about how it works and what surprised me along the way.

The problem with the feedback loop

Apex doesn't run anywhere except Salesforce. That is the whole premise of the platform: your code lives next to the database, the metadata, and the governor limits. It's a feature, not an accident.

It's also why the inner loop is slow. To run a single test method the usual flow is: push your code to a scratch org or sandbox, wait for the deploy, enqueue the tests, poll for results, then read the failures and start over. Every round trip is bound by the network and the org. On a real project the cycle gets long enough that you stop running tests after every edit, which is exactly when they'd be most useful.

What I wanted was the thing every other language already has. Save the file and get instant feedback.

What "local" actually requires

To run an Apex test with no org, you have to reimplement a surprising amount of the platform. You need a lexer and parser for the language, including classes, triggers, and annotations. You need an interpreter that actually executes the AST: control flow, exceptions, collections, static state, the type system. You need a database that behaves enough like Salesforce's to back DML and SOQL. You need a SOQL engine that turns Salesforce's query language into something a real database understands. And you need the platform semantics, which is the part that bites: trigger order of execution, @testSetup, test isolation, and a long list of quirks.

That last one is where most of the real work lives, and it's the part you can't shortcut. Apex is full of behavior that only matters once you've been burned by it. I'll get to some of those.

The stack

Nimbus is written in Go. The shape of it looks like this:

Apex source
   │
   ▼
 Lexer  ──►  Parser  ──►  AST
                            │
                            ▼
                      Interpreter  ◄──►  Local PostgreSQL (embedded)
                            │                    ▲
                            ▼                    │
                       SOQL engine ──────────────┘

A few of the choices behind it.

It's a tree-walking interpreter rather than a bytecode VM. Apex test suites aren't tight numeric loops; they're shaped by DML and queries. A tree-walker is much easier to get correct, and correctness is the entire point. If a local runtime gives a different answer than the org, it's worse than useless, because now it's lying to you. So I optimized for matching Salesforce's behavior, not for raw speed.

It embeds PostgreSQL, with no Docker. An early version reached for a containerized database, and that's a non-starter for a dev tool. Asking developers to run Docker just to execute a unit test is the kind of friction that quietly kills adoption. Nimbus ships a single binary with the database embedded. Nothing to install, nothing to start, nothing to clean up.

It translates SOQL to SQL on the fly. SOQL looks like SQL but it isn't. Relationship traversal like Account.Owner.Name, child subqueries like SELECT Id, (SELECT Id FROM Contacts) FROM Account, polymorphic fields, semi-joins: all of it gets rewritten into PostgreSQL at query time. This is one of the harder corners, and one of the most important to get exactly right, because SOQL shows up in nearly every Apex test.

The interesting part: platform semantics

Writing a parser is a known quantity. The difficulty, and honestly the fun, is in reproducing the parts of Apex that live in the runtime's behavior and not in any document.

Here are a few that cost me real time.

Trigger order of execution

When you insert a record, Salesforce runs the before triggers, saves, then runs the after triggers, and the context variables (Trigger.new, Trigger.oldMap, the boolean flags) have to be correct at each stage. Recursive DML inside a trigger needs to fire the next trigger. Get the ordering subtly wrong and a whole class of tests passes locally but fails on the platform, which is the worst outcome you can have.

Map case sensitivity

This one is a good story, and it doesn't have a clean ending. Apex's Map<String, V> is case sensitive. Put 'Foo' and 'foo' in the same map and you get two entries, and get('FOO') returns null. That's the platform behavior, confirmed against a live org.

The wrinkle is that a fair amount of real-world Apex leans, usually without meaning to, on case insensitive lookups, especially code keyed on field API names. And the platform itself is inconsistent about it: the describe maps like Schema.getGlobalDescribe() and fields.getMap() actually are case insensitive on the org, even though a plain Map<String, V> is not.

Id 15 vs 18 characters

Salesforce Ids come in two forms. The 15-character version is case sensitive, and the 18-character version is case insensitive with a checksum on the end. Code casts and compares them in ways that depend on which form you have. A single decision, like whether (Id) '001...15chars' expands to 18 characters, pushes dozens of tests in opposite directions depending on the codebase. There's rarely a free answer. You pick the behavior that matches the most real code and you write down the tradeoff.

JSON serialization key order

Here is one almost nobody thinks about until a test fails on it. When you call JSON.serialize on a Map<String, V>, the order the keys come out in is not arbitrary, and it is not insertion order either. On a live org, the keys come out in reverse insertion order. So a test that builds a map and then asserts on the exact serialized string is implicitly depending on that ordering, whether the author knew it or not.

Nimbus originally emitted keys in plain insertion order, which is the obvious thing to do and the wrong thing to do, and any test asserting on a serialized map string failed against it. The fix was to match the org's reverse-insertion-order behavior, verified across maps of several sizes. As a separate quirk, string concatenation on a map ('' + map) sorts the keys alphabetically instead, which is a different code path again. None of this is documented. You find it by serializing a map locally, serializing the same map on an org, and diffing the two strings.

Static state and test isolation

Each test method has to run as if nothing else ever happened: fresh static variables, a clean database, and its own transaction that rolls back when the method ends. Data created in @testSetup has to be visible to every method, but changes one method makes can't leak into the next. Reproducing that isolation model, and the static-reset rules around it, is essential to matching how Salesforce scopes a test run.

None of this is written down in a tidy spec. You learn it by running large, real, messy codebases and watching what breaks.

Does it actually work?

That's the question that matters, and the only honest way to answer it is to point it at real Apex and count.

I've been running Nimbus against well-known community libraries and full application codebases, the kind with thousands of test methods, heavy trigger frameworks, mocking libraries, and dynamic SOQL. The bar I hold it to is simple: the same pass or fail result you'd get in the org, just faster.

When a test passes in the org and fails in Nimbus, that's a bug in Nimbus. No exceptions. Each one is a case study: a missing builtin, a semantic mismatch, an edge in the SOQL translator. Tracking those down is how the runtime earns its fidelity, and the compatibility surface is large enough that this is the ongoing work.

Why local-first matters beyond speed

Speed is the headline, but it isn't the only thing you get once Apex runs on your own machine.

Because Nimbus understands Apex deeply enough to execute it, it can also back a language server. That means diagnostics, code lenses, inlay hints, and semantic tokens driven by the same engine that runs the tests.

It also makes CI simpler, which is the part I think is genuinely underrated, so it gets its own section below.

And it makes coverage something you can iterate on. Per-line coverage collected locally and instantly lets you close gaps in a tight loop, instead of deploying just to find out you missed a branch.

What this does to your pipeline

Salesforce CI is usually built around an org. A typical pipeline authenticates to the Dev Hub, spins up a scratch org, pushes the source, runs the tests, scrapes the results, and tears the org down. It works, but it's slow, it needs credentials sitting in your secrets, and scratch org limits are a real constraint when a lot of builds run at once.

If the tests run locally, all of that disappears. The pipeline just fetches a binary and runs it. There's no org to authenticate to, no scratch org to provision, no credentials beyond the Nimbus license key, and nothing to clean up afterward.

I put together a demo repo called BerlinBrew, a fictional coffee-subscription Salesforce project, to show the whole thing end to end. You can clone it and watch the pipeline run for yourself. The GitHub Actions job is short enough to read in one go. It installs Nimbus, caches the embedded PostgreSQL binaries so cold starts stay fast, and runs the suite:

- name: Install Nimbus
  run: |
    curl -fsSL https://install.testnimbus.dev | sh
    nimbus --version

- name: Run Apex tests
  env:
    NIMBUS_LICENSE_KEY: ${{ secrets.NIMBUS_LICENSE_KEY }}
  run: |
    nimbus test "*" \
      --coverage --coverage-report coverage.xml \
      --results-xml results.xml

The version is pinned in an environment variable so builds are reproducible and you bump it on purpose. The embedded Postgres binaries get cached under ~/.nimbus/pg, keyed on the Nimbus version, so a bump busts the cache automatically.

The two output files are the part that makes this drop into existing tooling without any glue. results.xml is JUnit, so any test reporter understands it. In BerlinBrew it's fed to a standard publish-test-results action that posts a check on the pull request. coverage.xml is Cobertura, so the coverage gate is just a few lines parsing lines-covered and lines-valid and failing the build under 75 percent, which is the same threshold Salesforce enforces for a production deploy:

- name: Enforce coverage threshold
  run: |
    covered=$(grep -m1 -oE 'lines-covered="[0-9]+"' coverage.xml | grep -oE '[0-9]+')
    valid=$(grep -m1 -oE 'lines-valid="[0-9]+"' coverage.xml | grep -oE '[0-9]+')
    # fail the build if covered/valid is under the threshold

One more thing the demo leans on: a CI profile. Nimbus reads a nimbus.properties file, and you can scope settings to a profile that only activates in the pipeline. BerlinBrew uses it to turn governor limits from a warning into a hard error and to run tests across four workers:

%ci.nimbus.governor.mode=strict
%ci.nimbus.test.parallel=4

So locally you get lenient, fast feedback, and in CI you get strict governor enforcement that catches the kind of limit problems you'd otherwise only discover on deploy. Same binary, different posture. None of it touches an org.

What I learned

A few things I'd tell myself at the start.

Correctness is the product. A fast runtime that lies is worse than a slow org that doesn't, and almost every design decision bent toward matching the platform's observed behavior.

The spec is a starting point, not the destination. Where the docs and the runtime disagree, the runtime wins, because people are running code that already works on the runtime.

Real codebases are the only real test suite. Hand-written sample tests find none of the interesting bugs. Pointing the thing at thousands of community tests finds all of them.

Friction is fatal for dev tools. "Install Docker first" or "spin up an org" is enough to lose people. One binary and zero setup, or it doesn't matter how clever the internals are.

Try it

Nimbus runs your existing Apex tests locally, with no org and no Docker, from a single binary. You can grab it and read the full CLI reference at testnimbus.dev.

# from your Salesforce project root
nimbus test

If you spend your day in the Apex inner loop and you're tired of the gap, point it at your codebase and tell me what breaks. The bugs you find are the roadmap. Docs and install instructions live at testnimbus.dev.