Between Day 1 and the final platform cutover, ACME operates two claims platforms, two enrollment systems and two provider masters, serving one combined membership of 2,220,000. Regulators, providers and members must not be able to tell. This document defines the integration layer that makes that possible, the interfaces it carries, how errors are detected and reconciled, and — equally deliberately — how the layer is designed to be removed when the coexistence period ends. Approved September 25, 2023, before closing.
Everything built here is temporary, and that is a design input rather than an apology. The integration layer exists for a defined period ending at core administration cutover. Software built without a decommissioning date accumulates dependencies until removing it becomes its own project — and the most expensive outcome available to this program is a "temporary" integration layer still running in Year 3, quietly load-bearing, with nobody willing to switch it off. The layer is designed to be deleted, and Section 8 is how.
Table of Contents
Part I — The Decision
Part II — The Build
- Interface Inventory
- X12 and the EDI Reality
- Reconciliation and Error Handling
- Non-Functional Requirements
Part III — The End
1. Why an Integration Layer and Not Point-to-Point
The disposition matrix establishes that most coexistence periods on this program sit between nine and twenty-four months, with core administration and its dependants running the full twelve. That duration is what selects the architecture.
| Option | Right when | Assessment here |
|---|---|---|
| Point-to-point interfaces | Two or three systems, short duration | Rejected. Interface count grows roughly as the square of the endpoints. Fourteen interfaces across eight systems becomes unmaintainable, and every change touches several. |
| Manual process / dual entry | Coexistence under three months, low volume | Rejected. Volume and duration both rule it out, and dual entry across two member masters manufactures exactly the identity problem the program is trying to solve. |
| Integration layer with a canonical model | Nine to twenty-four months, multiple endpoints | Chosen. Adapters scale linearly with endpoints. Change is localized. Reconciliation happens in one place. |
| API facade over the retiring platform | Legacy system must look modern to many consumers | Partially adopted — a read facade over the target's core admin, inside the layer rather than instead of it. |
| Strangler fig | Incremental replacement over years | Rejected. A multi-year pattern applied to a twelve-month coexistence adds ceremony without benefit. |
| Data virtualization | Read-only federation is sufficient | Rejected. This program writes across the boundary, not merely reads. |
This is the section that answers the challenge every integration architect eventually receives: "why are we spending money on middleware for systems we are retiring?" Because the retirement is twelve months away against an eighteen-month contractual wall, and in that window the combined entity must adjudicate claims, enroll members, pay providers and file with regulators across two estates. A tactical bridge built for three months and then operated for eighteen becomes the most fragile component in the program — and it fails during cutover, when every person who understands it is already fully occupied.
2. The Canonical Model
Each endpoint translates once, into a neutral internal representation, rather than into every other endpoint's format.
| Canonical entity | Definition and source of truth during coexistence |
|---|---|
| Member | Identity, demographics, enterprise identifier. Source of truth is the EMPI, not either platform. |
| Coverage | Enrollment periods, plan, group, effective dating. Union across both books; never overwritten. |
| Provider | Identity, NPI, locations, network participation. Single provider master post-migration. |
| Claim | Header and line detail, adjudication status, payment reference |
| Accumulator | ⚠ Deductible and out-of-pocket balances. See 2.2 — the hardest entity on this list. |
| Authorization | Utilization management decisions, effective windows |
2.1 Why canonical rather than direct translation
Eight endpoints translating directly to one another would need up to fifty-six mappings. Through a canonical model, each endpoint needs one adapter in and one out — sixteen. More importantly, a change to one system's format touches its own adapter and nothing else.
The canonical model's real value is not the arithmetic; it is that it forces an explicit decision about meaning. The two organizations do not define "coverage period" identically, do not treat a mid-month termination the same way, and do not agree on what makes a claim "final." Point-to-point mapping lets those disagreements hide inside individual interfaces, where they are discovered one at a time in production. A canonical model forces the disagreement into the open at design time, which is uncomfortable, slower, and the entire point.
2.2 Accumulators — the entity that breaks naive designs
Deductible and out-of-pocket accumulators are the hardest thing to run across two platforms, and they are the one a member notices immediately. A member who meets their deductible under claims adjudicated on the target's platform, then has a claim processed on ACME's, must not be asked to meet it twice. Accumulators are cumulative running balances, not static attributes — so a stale synchronization does not degrade gracefully, it produces a wrong member liability, a wrong provider payment, and a call to member services from someone who was charged money they did not owe. Accumulator synchronization is therefore near-real-time and reconciled daily, unlike every other entity in the layer.
3. What the Layer Is Not
| Not | Reasoning |
|---|---|
| A system of record | The layer moves and translates. It never becomes the authoritative source for anything — that is how temporary infrastructure becomes permanent. |
| A place for business logic | Adjudication rules, benefit logic and pricing stay in the platforms. Logic in the layer must be migrated when the layer dies. |
| A data store | ⚠ Staging for in-flight processing only, with defined retention. Nothing accumulates. |
| A strategic platform | It has an end date. Building it as a long-term capability would be a different, larger, out-of-scope program. |
| The EMPI | The layer consumes the enterprise identifier; it does not perform matching. Identity resolution is a separate capability that outlives the layer. |
The second row is the one that gets violated, always for good reasons, and always under time pressure. A small transformation is needed; the layer is the convenient place; nobody has time to change a platform. Repeat that a dozen times and the layer holds business rules nobody documented, which means it cannot be switched off at cutover without something breaking that nobody can name. The rule is enforced at design review, because it cannot be enforced retroactively.
4. Interface Inventory
| Ref | Interface | Pattern | Frequency | Direction | Notes |
|---|---|---|---|---|---|
| IF-01 | Enrollment — target to ACME | X12 834 | Daily | → | Drives EMPI ingestion. The highest-volume identity path. |
| IF-02 | Enterprise member identifier broadcast | API | Near real time | ↔ | EMPI publishes the enterprise ID to both platforms as matches resolve |
| IF-03 | Eligibility inquiry / response | X12 270/271 | Real time | ↔ | ⚠ Provider-facing. Latency is visible at the point of care. |
| IF-04 | Claims — target platform to ACME | X12 837 | Daily batch | → | Institutional, professional and dental |
| IF-05 | Remittance advice | X12 835 | Payment cycle | ← | Must reconcile to the paying platform, not the receiving one |
| IF-06 | Accumulator synchronization | API | Near real time | ↔ | Hardest Bidirectional running balances. See 2.2. |
| IF-07 | Provider master distribution | Batch | Daily | → | Single provider master feeds both platforms after AD-09 migration |
| IF-08 | Authorization status | API | Near real time | ↔ | UM decisions must be visible to whichever platform adjudicates the claim |
| IF-09 | Care management member feed | Batch | Daily | → | Feeds the preserved platform (AD-07) for the combined population |
| IF-10 | Premium billing and payment | X12 820 | Monthly | ↔ | Group-level; aligned to billing cycles |
| IF-11 | Financial posting to general ledger | Batch | Daily | → | Both platforms post to one ledger from month six |
| IF-12 | Member correspondence and ID cards | File | Daily | → | Single print vendor; both platforms as sources |
| IF-13 | Data warehouse ingestion | Batch | Daily | → | Both platforms feed the new warehouse (AD-20) from build completion |
| IF-14 | Write-back to the retiring platform | API | Near real time | ← | Hardest Keeps the target platform current during parallel run. See 4.1. |
4.1 The two hard ones, and why they are hard for the same reason
IF-06 and IF-14 are the difficult interfaces because they write into a system that is being retired, and both directions must stay correct simultaneously. Everything else in the inventory moves data toward the surviving platform, where a failure means something is missing and someone notices. These two keep the departing platform accurate while it is still adjudicating live claims — so a failure means the retiring platform makes a correct-looking decision on stale data. Nothing alerts, because from that platform's point of view nothing went wrong. It is the only class of failure in this architecture that is silent on both sides, which is why both interfaces carry daily reconciliation rather than exception-only monitoring.
⚠ There is a tempting simplification here that the program explicitly rejected: stop writing back, freeze the target platform, and run everything on ACME's. That is cutover, not coexistence — and it cannot happen until identity resolution completes. The write-back interface exists precisely because the cutover date is not under the architecture's control.
5. X12 and the EDI Reality
Five of the fourteen interfaces are X12 transaction sets rather than APIs, and that is not a legacy compromise — it is what the ecosystem actually runs on. Providers, clearinghouses and employer groups exchange X12; they do not consume bespoke APIs.
| Transaction | Purpose | What makes it non-trivial |
|---|---|---|
| 834 | Enrollment and maintenance | Full-file versus change-file semantics differ between trading partners; a misread produces mass terminations |
| 837 | Claim submission | Institutional, professional and dental are separate variants with separate rules |
| 835 | Remittance advice | Must reconcile to the payment actually issued, across two paying systems |
| 270/271 | Eligibility inquiry and response | ⚠ Real-time and provider-facing. Timeout behavior is a member access issue, not a technical one. |
| 820 | Premium payment | Group-level reconciliation against billing |
| 997 / 999 | Functional acknowledgment | ⭐ Acknowledgment is not acceptance — see below |
| TA1 | Interchange acknowledgment | Envelope-level; fails before content is ever examined |
The distinction that catches teams new to EDI: a 999 acknowledgment means the file was syntactically valid, not that the receiving system accepted or loaded it. A file can pass structural validation cleanly and still be rejected downstream on business rules, or load partially, or load into the wrong group. A pipeline that treats "999 received" as success will report green while enrollment silently fails — which is why every EDI interface in this inventory carries a business-level control total in addition to its acknowledgment, and why X12 assurance is contracted to a specialist rather than absorbed into general testing.
⚠ Trading partner re-registration is externally paced. Every provider, clearinghouse and vendor exchanging X12 with the target must be re-registered against the surviving entity, at their speed rather than the program's. This is why the clearinghouse interface (IF-04) and its vendor contract retire two months after core administration rather than with it.
6. Reconciliation and Error Handling
Every interface carries a control total. A success flag is not a control. "The job ran" and "the job moved the right data" are different assertions, and only the second one is worth reporting. During coexistence, the two platforms must agree on counts and amounts daily — because a discrepancy detected on day one is an interface defect, and the same discrepancy detected at cutover is a reconciliation project.
| Control | Implementation |
|---|---|
| Record counts | Sent, received, accepted, rejected — reconciled per run, per interface |
| Financial control totals | Claim amounts and payment amounts balanced across the boundary daily |
| Membership reconciliation | Active member count agrees between platforms and the EMPI daily |
| Accumulator balance check | ⚠ Daily balance comparison for any member with activity on both platforms |
| Aged exception queue | Rejected records tracked to resolution with an age. ⚠ Exceptions that merely accumulate are not being managed. |
| Replay capability | Every interface can reprocess a defined window without duplicating what already posted |
| Idempotency | Reprocessing the same message twice produces one result, not two |
Idempotency and replay are listed last and are the ones that determine whether an incident is a bad afternoon or a bad quarter. Interfaces fail; that is expected and survivable. What is not survivable is being unable to reprocess safely — because then every failure becomes a manual reconciliation, performed under time pressure, against a live claims platform. The capability to safely rerun is worth more than the effort spent making failures rare.
7. Non-Functional Requirements
| Requirement | Provision |
|---|---|
| Volume | Sized for combined membership of 2,220,000 with headroom for the annual open enrollment peak, which is several times the daily average |
| Eligibility latency | Real-time response for 270/271. ⚠ A slow eligibility response is a provider standing in front of a member. |
| Batch windows | Overnight processing must complete before the business day in the earliest operating time zone |
| Protected health information | Encrypted in transit and at rest; ⚠ no member-level data processed outside the United States, per DOI conditions |
| Audit | Every message logged with lineage sufficient to answer "where did this value come from" for a regulator |
| Recovery | Tier 1 — the layer is essential, though not Tier 0: a short outage delays rather than destroys |
| Environments | Development, test and a production-like environment with de-identified data for the offshore test team |
8. Designed for Decommissioning
The layer's retirement is specified now, while it is being designed, rather than discovered later when someone asks whether it can be switched off.
| Design provision | Purpose at end of life |
|---|---|
| No business logic in the layer | Nothing to migrate out. If the rule lives in a platform, retiring the layer moves nothing. |
| No persistent data store | Nothing to archive or extract. Staging clears on a defined retention. |
| Interface-level shutdown | ⭐ Each interface retires independently as its dependency completes. The layer thins out rather than being switched off in one act. |
| Documented consumer register | Every consumer of every interface is recorded, so "who breaks if this stops" is answerable without archaeology |
| No downstream direct dependencies | Nothing may connect to the layer except through a registered interface. Undocumented consumers are what make removal impossible. |
| Decommissioning acceptance | An interface is retired only when its consumers confirm they no longer call it — evidenced by traffic at zero, not by assertion |
The retirement sequence mirrors the TSA exit deliberately: independent shutdowns with evidenced criteria, not a single event. As each disposition completes — provider master consolidated, ledger migrated, core administration cut over — the interfaces serving it go quiet and are removed. By the time the last one closes, the layer is already mostly gone. That is what "temporary" has to mean operationally: not that the team intends to remove it, but that removal is a sequence of small, evidenced steps rather than a project nobody has budget for.
The failure this section is written against is specific and common. An integration layer built for a transition is still running years later, because three undocumented consumers connected to it directly, one business rule was quietly added under deadline pressure, and nobody can now prove what stops working if it is switched off. It becomes permanent infrastructure that was never designed, never funded and never owned — and the eventual project to remove it costs more than building it did. Zero traffic, a registered consumer list, and no logic inside are what prevent that, and all three are cheap now and impossible to retrofit.
Related artifacts: 7 — Due Diligence Findings (DD-06) · 20 — Application Disposition Matrix · 22 — TSA Schedule & Exit Plan · 23 — Data Migration & EMPI Strategy · 24 — Cloud Migration Strategy · 26 — Quality Plan · 39 — Interface Build & Cutover Log