> ## Content Index
> Fetch the complete content index at: https://contextfirst.blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# Green APIs, Broken Handoffs
- URL: https://contextfirst.blog/integration-surface-gpr-salesforce/
- Published: 2026-08-25T13:00:00.000Z
- Updated: 2026-08-25T14:55:58.000Z
- Description: Sample payloads beat architecture slides
- Author: Iheatu Chris Wogu
- Tags: Field Notes, Engineering Management, Agentic Delivery, Learning Journey 2026

An end user does not experience "service returned 200." They experience **success toast - nothing in the account** \- while four service dashboards stay green. Article 01 mapped the front door; this note goes under the hood: where state must hand off, and why "my team's API is green" is insufficient for launch sign-off.

**Here's what this piece covers:** one broken seam, commit `bbba7ea` (2026-04-07), the integration surface map pattern, and three gates I would enforce as a lead.

Part of [Field Notes: agentic delivery](https://contextfirst.blog/field-notes-agentic-delivery/).

---

## 1\. The leadership problem

Modern product surfaces are not one application. They are a **graph of backends** \- identity, records, entitlement, partner data, CRM - with the client calling peers directly. No single BFF wraps the handoffs.

When two services look healthy in isolation, production still fails at the **seam**: idempotency on retry, pending records syncing downstream, entitlement codes propagating after the upstream step completes.

**Wrong:** "Service A talks to the CRM."  
**Right:** "Here is the sequence for complete → write → profile sync → support handoff - and the three failure modes we found when we read sample payloads."

The anti-pattern is **endpoint checklist theater** \- every service "integrated" while the path still fails.

---

## 2\. What the git history shows

Five days after the MVP map landed, commit `bbba7ea` (2026-04-07) added an **integration corpus**: architecture notes, handoff design, an executive one-pager, and **`data-dump.md` \- 987 lines** of sample payloads.

The data dump was the learning beat. Specs said fields aligned; dumps showed nulls, wrong enums, and timing gaps between upstream record state and CRM create.

flowchart LR subgraph user\["User action"\] O\[Complete primary step\] R\[Write entitlement\] end subgraph services\["Services touched"\] E\[Records service\] G\[Entitlement service\] S\[CRM\] end O --> E R --> G G --> S E -.->|record state| G G -.->|profile sync| S

Specs lie politely. Payloads do not:

```java
record SyncPayload(String externalId, String status, String entitlementCode) {}

static Optional<String> silentFailure(SyncPayload p) {
  if (p.externalId() == null) return Optional.of("null externalId");
  if (!"ACTIVE".equals(p.status())) return Optional.of("unexpected status: " + p.status());
  if (p.entitlementCode() == null || p.entitlementCode().isBlank())
    return Optional.of("missing entitlementCode");
  return Optional.empty();
}
```

---

## 3\. What I learned

Three lessons I still reuse on launch programs:

**A write is a chain, not a POST.** Create account → attach upstream record → write entitlement → read back the account. A green POST on `/register` proves nothing about read-back.

**The client calls peers directly.** There is no integration team hiding behind one API. Seam ownership must be named per hop - foreshadow [integration tests are chains](./04-integration-tests-are-chains.md).

**Environment parity blocks more than frontend bugs.** CRM sandbox access, pending queues, and field-level security stopped Phase 2 seam work for weeks while UI looked fine.

| Path step                  | Owning concern             | External system   |
| -------------------------- | -------------------------- | ----------------- |
| Primary action complete    | Records service            | Upstream provider |
| Write from upstream record | Entitlement + records seam | \-                |
| Result visible in account  | Entitlement read-back      | \-                |
| Support escalation         | Entitlement → CRM          | CRM               |
| Partner / service lookup   | Org + geo services         | Mixed third-party |

---

## 4\. Named pattern: integration surface map

> **Integration surface map** \- who owns each hop, what the contract is, what breaks silently at the seam.

Not a system-context poster on a wall. A **living map** tied to workflow IDs and sample payloads:

flowchart TD M\[Integration surface map\] --> H1\[Hop owner\] M --> H2\[Contract + sample payload\] M --> H3\[Silent failure mode\] H3 --> W\[Workflow ID in SIT suite\]

This map drove how we sequenced **63 SIT workflows** \- team scope first, seams second, end-to-end paths third ([article 05](./05-sit-63-workflows.md)).

---

## 5\. What I'd do as a lead

1. **Require an integration map for every launch** \- not just an architecture slide. Include sample payloads early.
2. **Gate Phase 2 SIT on seam owners**, not feature owners alone. "Not our service" is not an exit criterion.
3. **Keep a watch list** for pending writes and entitlement ripple defects - they re-emerge at CRM handoffs (later: [blocker matrix](./23-cubsit-blocker-matrix.md)).

---

### Further reading

- [Fifty pages, one map](./01-mapping-dtc-launch.md) \- master flow (`59334b2`)
- [Prove the path, not the POST](./04-integration-tests-are-chains.md)
- Planning anchor: commit `bbba7ea` · 2026-04-07

---

![Iheatu Chris Wogu](https://avatars.githubusercontent.com/u/3457705?s=176&v=4)

## About the author

**Iheatu Chris Wogu** is an engineering manager focused on launch programs, honest engineering metrics, and **engineering-led, agent-accelerated** delivery - researching where work queues up when agents widen dev output, then building proof, gates, and measurement that scale.

Field notes live on [First Context](https://contextfirst.blog/). Values treatise: [engineering manager values](https://contextfirst.blog/engineering-manager-values/).

**LinkedIn:** [linkedin.com/in/iheatu-chris-wogu](https://www.linkedin.com/in/iheatu-chris-wogu/?ref=contextfirst.blog)