R4.3 · Make the dashboard critical path the first mediation domain
| Theme | R4 · API mediation |
| Domain | Integration and API architecture |
| Status | Proposed |
| Needs client validation | Yes |
| Anchored in | The API landscape — PIE-APIM and GB-APIM, ~4,200 operations · the experience map — 42 APIs on the target homepage · the API Mediation proposal slides 3 and 4 |
| Open questions | Takes a position on 30 and 31; depends on 29 |
| Deliverables | D2.5 area 3 · D2.1 · D3.1 |
| Reinforces | R3.1 — the same boundary question, one tier down |
Concern
The proposal argues a question the estate has already answered, and does not answer the one that is actually open.
"Centralized vs federated" is the wrong axis. Slide 3 is a fourteen-row comparative study posing the two as a binary across control, consistency, scalability, governance, flexibility, cost and use case. Slide 4 then answers it correctly — both, Inter centralized and Intra federated — and buries that answer under the comparison.
The estate already federates, deliberately and in production. The API landscape enumerates two gateways: PIE-APIM shared across 15+ BU tenants with 2,889 operations, and GB-APIM dedicated to Group Benefits with 1,311 operations across 342 APIs — dedicated for a stated reason, the Akamai GTM flow and high-volume claims and member APIs. zOS Connect is exposed through PIE-APIM as a mainframe adapter rather than as a peer gateway. That is hub-and-spoke with a reasoned exception, carrying roughly 4,200 operations today. The comparative study mentions none of it.
The genuine decision is where the Inter/Intra boundary sits, and it gets one sentence."Coarse-grained, enterprise-level cross-cutting concerns" centrally, "domain or LOB-specific considerations" delegated. There is no rule for adjudicating a capability that could plausibly sit on either side — so the boundary is relitigated per API, by whoever is in the room.
Orchestration collides with a component that already exists. Orchestration is listed as an Inter-layer traffic-management capability; Transformation and Integration appear on both the External Ingress and Internal gateways. Aggregating several backend calls into one response is precisely what the MVP's Integration API does. Two readings, both consequential, and the deck does not say which is intended:
| If the Inter layer orchestrates | If it does not |
|---|---|
| The Integration API is partly redundant, and the composition boundary moves into a centrally governed, centrally deployed component | The layer is transport plus policy; the Integration API stays, and the proposal's "reduced duplication" benefit never reaches the composition tier |
| A dashboard card change becomes an enterprise gateway change — at a chokepoint the deck itself annotates "Deploy (manual)" from a management plane it labels "ClickOps" | Cross-BU aggregation logic stays unarbitrated between six lines of business |
The first reading is a release-cadence collision across six lines of business with independent release trains. The answer determines whether the Integration API is target-state or interim — which changes what WS 3 sequences and what it costs.
Migration is absent, and it is the whole cost. No strangler sequence, no coexistence model, no dual-ingress period, no per-tenant cutover ordering, no deprecation policy, and no position on the GB-APIM exception. Fronting or migrating ~4,200 operations across 15+ tenants — each with APIM products, subscription keys and ACLs — is a multi-year programme. The Unified Portal needs eight APIs on a login critical path now, and the experience map maps 42 onto the target homepage. Those are very different problems, and the second does not have to wait for the first.
Recommendation
Invert the sequencing. Prove the model on the dashboard critical path before rolling it across the estate. Five commitments:
When protected aggregation is introduced, scope the first mediation domain to that dashboard fan-out — the eight login critical-path APIs, extended to the experience map's 42 — and prove the model there: mandatory customer delegation, mandatory rate limiting against the FCC ceiling (R4.1), a published latency budget and redaction on the aggregation path (R4.2). R1.1 lets the navigation-first portal proceed through OIDC SSO without pretending those API controls already exist. The bounded slice begins when customer data is added to the shared surface.
Write the boundary rule, not the boundary. A capability belongs in the Inter layer when it is enterprise-uniform and its variation across lines of business would be a defect; in the Intra layer when variation is legitimate. Then apply it to the contested capabilities — orchestration, transformation, resiliency — and record the result. Without the rule, the boundary moves every time an API is onboarded.
Rule on orchestration explicitly, because the Integration API's future depends on it and because R3.1 constrains the answer: whatever composes has to sit below the web shell and be consumable by a native client. An Inter layer that orchestrates satisfies that; one that does not leaves the Integration API in place, and the composition boundary argument is unchanged.
State the coexistence position per gateway, with a deprecation date or an explicit permanent exception for GB-APIM. "Centralized" that does not say what happens to a production gateway serving a third of the API surface is proposing a migration it has not costed.
Re-run the comparative study against the options the client's own later material frames. The architecture decision deck compares single BFF, federated GraphQL and CQRS over an event backbone. The mediation proposal's own current-state slide already names GraphQL-based APIs and event-driven architecture as things Manulife runs today. Those are the same decision at two altitudes, eighteen months apart, and nobody has put them on one page.
What it changes
It makes the portal a proof rather than a dependent. Today the Unified Portal would be a consumer of an enterprise programme with no date. Scoped as the first mediation domain, it becomes the evidence base — real latency percentiles, a real token-exchange contract, a real enforced rate limit — that the rollout otherwise has to assume.
It turns two open questions into decisions with an owner. Open questions 30 and 31 — replace/front/rename, and does it orchestrate — are currently Validation items. A first domain forces both within its scope rather than across 4,200 operations.
It changes what WS 3 prices. Whether the Integration API is target-state or interim is the difference between sequencing a component and sequencing its replacement.
What we are not recommending
Rejecting the two-tier model. Inter centralized, Intra federated is the correct shape for an estate with six lines of business, two gateways and ~4,200 operations. The concern is the missing boundary rule and the missing migration, not the topology.
An enterprise migration as a precondition for the portal. The dependency runs the other way. A portal that waits for 4,200 operations to be mediated does not ship.
Making the mediation layer permanently portal-scoped. The first domain is a proving ground, not the end state. What makes it a first domain rather than a special case is that the boundary rule and the coexistence position are written before it starts.
Ruling on orchestration ourselves. It is a client decision with a named owner — open question 31, Chief Architect. We supply the criterion and the consequence; the ruling is Manulife's.
Dependencies and open questions
- Open question 29 — whether the proposal is live, endorsed and funded. Everything here is conditional on it.
- Open question 30 — replace, front or rename PIE-APIM and GB-APIM. This page argues the answer must be stated per gateway rather than implied.
- Open question 31 — does the mediation layer orchestrate. This page argues it must be ruled on before WS 3 prices the Integration API.
- Open question 8 — the North Star of record. The proposal's co-author is that question's named owner, and a proposal from that office unreferenced by the four documents that followed it is evidence for the "no agreed North Star" finding rather than against it.
- CR-39 — the proposal's standing, and any migration or coexistence plan that exists.