Golden Vine Integration Golden Path

The short version

Golden Vine Integration Golden Path is an evidence-driven Platform Engineering and Developer Experience case study. I built an enterprise integration as the first developer, documented the friction and failure modes I hit doing it, used those observations to develop a Golden Path and Dojo enablement model, and then tested that model with a second, independent integration.

The objective was never just "get two integrations working." It was to determine, with evidence rather than opinion, what complexity should stay with the application developer, what should become a reusable platform capability, what should be taught rather than automated, and whether any of those decisions actually improved the experience for the next developer.

→ View the project on GitHub — the site below tells the story: problem, reasoning, leadership, teaching, evolution, and outcome. The repository holds the evidence: code, ADRs, experiments, friction logs, observation logs, Dojo material, and both integrations.

Golden Vine Winery is a fictional company, built for this portfolio project. It is not a real client engagement and isn't affiliated with any current or former employer.

The shape of it

Developer #1 → Observation → Enablement → Golden Path / Dojo → Developer #2 → Second Observation

I deliberately didn't design a Golden Path up front. The first integration — a real Salesforce Platform Event, fired when a distributor reaches the right stage in Salesforce, received over the Pub/Sub API and used to open a ServiceNow Incident — was built by hand, against a real Salesforce Developer Edition org and a real ServiceNow developer instance, with a running log of every point of friction along the way: authentication setup, secrets, API discovery, schema surprises, and eventually, failure behavior.

Developer #1: build it, then break it on purpose

Once the happy path worked end to end, I went looking for the failure modes rather than waiting for them to show up in production: duplicate event delivery, a process crashing mid-write to ServiceNow, and silent loss — an event that never produces an Incident and leaves no trail. Each was reproduced directly, not assumed.

That raised the real question: could I actually guarantee exactly one ServiceNow Incident per business event? I tested two candidates against the real systems instead of reasoning about them from documentation. ServiceNow enforcing uniqueness on its own — five separate attempts, plus confirming no conditional-write API exists to fall back on — never worked. A durable, integration-owned ledger of "who owns this operation right now" closed every sequential crash I could reproduce, but a genuinely concurrent race — an original owner that's still running, not actually dead, competing with a recovery attempt — defeated it, deterministically, every time.

That wasn't a failed effort; it was the answer. ADR 0005 adopts a two-tier reliability contract: every integration gets a baseline of recoverable at-least-once processing paired with audit-based detection of any resulting gap or duplicate — honest about not being exactly-once, but never silent about a failure. A stronger, exactly-once guarantee is available only to a target that's been proven, by experiment, to enforce uniqueness itself. ServiceNow hadn't earned that yet.

A human review, not an auto-conversion

Friction logs don't translate themselves into Golden Path requirements. A Phase 2 Observation Review — a deliberate, human-led checkpoint, not an automated rollup — worked through the accumulated friction and reliability evidence and reached 15 numbered findings about what should become reusable platform capability, what should be taught, what should stay a developer or business decision, and what needed further investigation before either.

Enablement: what actually got extracted

Two packages came out of that review: golden-path-reliability (durable operation ownership) and golden-path-salesforce-transport (Salesforce Pub/Sub transport), pulled out of the first integration's own code with their global-config coupling replaced by explicit parameters. Nothing else was extracted — one integration isn't enough evidence to generalize a ServiceNow-specific interface, so that wasn't attempted.

Developer #2: does any of this actually transfer?

The second, independent integration — Salesforce to a document workspace in SharePoint — was built live against a real Microsoft 365 tenant, not simulated. Both extracted packages dropped in with zero code changes and worked against a target they'd never seen: normal processing, concurrent-processing protection, and full stale-operation recovery, all independently verified against the real SharePoint site.

One thing didn't transfer and had to be solved fresh: SharePoint has no equivalent of ServiceNow's correlation_id field, so business-operation identity for that target needed its own answer. And a follow-up experiment turned up something genuinely new: the exact slow-owner race that produced a real ServiceNow duplicate 3 times out of 3 produced zero duplicates against SharePoint, 3 times out of 3 — SharePoint's own conflictBehavior: "fail" closes a race ServiceNow never could (ADR 0009). That's a narrower claim than "the platform guarantees exactly-once" — and a stronger one, because it's earned by direct, repeated experiment against the real system rather than assumed from a vendor's documentation.

Six things worth remembering

1. Business-operation identity belongs to the business, not the platform. What counts as "the same operation," and what counts as a duplicate, is a business decision the platform must never invent on a developer's behalf.
2. Transport complexity can be platform-owned; business intent can't be hidden inside it. Connection setup and replay mechanics are plumbing nobody benefits from re-deriving. Recovery thresholds and what counts as an acceptable delay are not — hiding them behind a simpler-looking interface doesn't remove the decision, it just moves it somewhere the developer can no longer see it being made.
3. Recovery capability is different from recovery authority. Being technically able to reclaim and recover a stale operation doesn't mean the platform is authorized to decide when. That decision belongs to whoever owns the risk of getting it wrong.
4. Reliability claims have to be demonstrated experimentally. Every claim in this project — ServiceNow's uniqueness behavior, SharePoint's, the durable ledger's crash boundaries — was tested against real systems, repeatedly, not reasoned about from docs.
5. Incomplete evidence stays visibly incomplete. Absence of evidence is not evidence of absence. An inconclusive result becomes a visible, unhealthy state — never a silent success, and never grounds for a mutating action on its own.
6. Developers are encouraged to challenge the Golden Path — with evidence. A developer who deviates and brings back real evidence has produced a useful signal for the next iteration, not a compliance violation.

"It's a Golden Path, not a gold watch."

The Golden Path doesn't guarantee that a given implementation satisfies a customer's requirements. It provides evidence-backed implementation, documented behavior, runnable experiments that established that behavior, and known limitations. The developer consuming it still has to determine whether those characteristics actually satisfy their customer's requirements, in their own architecture — the platform gives them a better-tested route and real guardrails, but it doesn't relieve them of engineering judgment, and it doesn't promise the route goes exactly where every customer needs to end up.

Where it stands

Both integrations run against real, live systems (Salesforce, ServiceNow, and Microsoft 365/SharePoint), with GitHub Actions running lint, build, test, and a dependency audit on every change. Infrastructure as Code was deliberately not adopted — ADR 0010 found no real infrastructure to point it at, and every integration's platform configuration independently reached the same "keep this manual" conclusion on its own evidence. The Dojo cycle is still running: the Golden Path is expected to keep changing as new integrations expose assumptions the current one doesn't yet know it's making.

→ See the evidence on GitHub — ADRs in docs/decisions/, the full friction and observation logs in docs/devex/, the Dojo philosophy and walkthroughs in docs/golden-path/, and both integrations under services/.