Business requirements for the integration layer that keeps two claims platforms consistent while both run, and for the fourteen interfaces it carries. Issued February 13, 2024. Ten percent of the cost baseline, and the only work package on this program whose requirements include the conditions for its own removal.
This is a requirements document for something built to be deleted, and that inverts several conventions. The usual instinct in integration design — put the logic where it is convenient, keep state so recovery is easier, add a rule when a consumer asks — produces a layer that cannot be removed, because by then it is where several business decisions actually live. Every requirement below that looks like a restriction is a retirement requirement wearing different clothes: no business logic, no persistent store beyond replay, no unregistered consumers, no rule added at a consumer's request. The layer is a translator with a defined lifespan, and the requirements exist to keep it one.
Table of Contents
- Canonical Model
- Interface Catalog
- Reliability, Reconciliation and Replay
- The Two Hard Interfaces
- Retirement Requirements
- Non-Functional Requirements
1. Business Case and Objectives
| Objective | Measure | Target |
|---|---|---|
| Both platforms behave consistently while both are live | Reconciliation variance per interface | Zero unexplained |
| No member experiences the coexistence | ⚠ Member-visible incidents attributable to synchronization | Zero |
| Point-to-point integration avoided | Connections built | 14 through one layer, not n² between systems |
| The layer is removable on schedule | ⚠ Interfaces retired with zero-traffic evidence | All 14 retired by program close |
| Cost proportionate to coexistence | Build cost against coexistence duration | Justified by a 12–15 month coexistence, not by permanence |
2. Current State and Why a Layer
Between Day 1 and the final platform cutover, ACME runs two claims platforms, two enrollment systems and two provider masters, serving one combined membership. Regulators, providers and members must not be able to tell. Something has to keep those systems consistent with each other, and that something is this layer.
The obvious objection arrives immediately: why build middleware for a system you are retiring? It is a fair question and it has a bad answer and a good one. The bad answer is architectural preference — canonical models are tidy, point-to-point integration is not. That answer does not survive contact with a program under schedule pressure, and it should not.
The good answer is a duration. Coexistence here runs to roughly fifteen months, and the number is not a planning convenience — it is set by the TSA exit sequence and the migration waves beneath it. Below about nine months, tactical point-to-point bridges are the right call: cheaper, faster, and disposable before their maintenance cost accumulates. Above roughly two years, you are building a permanent integration estate whether you admit it or not. Fifteen months sits squarely in the band where a real layer with a canonical model is the lower-cost option, and it is the only interval in which that is true.
The reason is arithmetic rather than taste. Point-to-point integration cost scales with the number of connections; with six systems on each side that is a large number, and every schema change touches many of them. A canonical model turns that into one translation per system. The crossover is a function of how many changes arrive during the coexistence period, and on an integration the answer is many — every migration wave changes an endpoint.
⚠ State the duration, not the preference. The defensible version of this decision in a review is: at fifteen months and fourteen interfaces, point-to-point costs more than a canonical layer, and here is the crossover calculation. The version that loses the argument is that middleware is better practice — because for a nine-month coexistence, it is not.
Two platforms will run simultaneously for a defined period. Something has to keep them consistent, and the choice of what is a requirements decision rather than a technical preference.
| Option | When it is right | Why it is not right here |
|---|---|---|
| Point-to-point interfaces | Two or three connections, short-lived | ⚠ Fourteen connections between two platforms and a warehouse becomes unmaintainable, and every retirement touches every partner |
| Batch file exchange only | Tolerant of a day's latency | ⚠ Accumulators and eligibility are not tolerant of a day's latency |
| Refactor one platform to consume the other's model | Permanent coexistence | Rejected — refactoring under a contractual deadline, on a platform being retired |
| Data virtualization | Read-heavy, no write-back | ⚠ Two interfaces write into the retiring platform. See §7. |
| Integration layer with a canonical model | 9 to 24 months of coexistence | Selected. The coexistence period is the deciding variable. |
The defensible answer to "why build middleware for a system you are retiring" is a duration, not an architecture preference. Below roughly nine months, tactical connections are cheaper than a layer and the mess is survivable. Above about two years, the layer stops being temporary and the honest choice is a permanent platform. This program sits in the middle at twelve to fifteen months, which is long enough that point-to-point interfaces would be rebuilt as requirements changed, and short enough that a permanent integration platform would be over-engineering. ⚠ If the coexistence period moves materially, this decision is re-opened rather than defended.
3. Scope Boundaries
| In scope | Explicitly out of scope |
|---|---|
| Translation between platform models | ⚠ Business logic of any kind — see FR-04 |
| Routing, sequencing and delivery guarantees | Persistent data ownership |
| Reconciliation and control totals | Reporting — the warehouse serves that, see BRD-04 |
| Replay and error recovery | ⚠ Enrichment from a third source. If data is missing, the source system supplies it. |
| Interface retirement | Anything intended to outlive the coexistence period |
4. Canonical Model
| Ref | Priority | Requirement | Detail |
|---|---|---|---|
| FR-01 | Must | One canonical representation per entity | Member, coverage, provider, claim, authorization, accumulator. Each platform maps to and from it. |
| FR-02 | Must | Canonical model is versioned | ⚠ A change is a versioned change with a migration path, not an edit |
| FR-03 | Must | Definitions agreed before mapping | ⚠ "Member", "coverage period", "final" and "closed" are defined once and signed by both sides before any mapping is written |
| FR-04 | Must | No business logic in the layer | ⚠ It translates and routes. A rule that decides something belongs in a system of record, and a request to add one is refused and redirected. |
| FR-05 | Must | Mapping is declarative and inspectable | A reader can determine what a field becomes without reading code |
| FR-06 | Should | Unmapped fields fail loudly | ⚠ An unmapped field is an error, not a silent null |
FR-03 exists because of two issues this program has already had, and both had the same root cause. Two workstreams reported different member counts for the same population — one counting subscribers, the other covered lives. Three interface adapters were reworked after a late disagreement about what a coverage period means. Neither was a technical failure. Both were two organizations using the same word for different things and not discovering it until something downstream broke. ⚠ Two companies combining have two vocabularies, and the words that cause trouble are not the specialist ones — they are the ordinary ones everybody is confident they already understand. Forcing those definitions into the open before mapping is what the canonical model is actually for; the translation is almost a by-product.
5. Interface Catalog
Fourteen interfaces, each with a direction, a delivery expectation and a retirement trigger. The design detail is in artifact 25; the requirement here is that every one carries all three.
| Ref | Interface | Direction | Retirement trigger |
|---|---|---|---|
| IF-01 | Enrollment, target to ACME | One way | Core administration cutover |
| IF-02 | Enterprise member identifier broadcast | Broadcast | ⚠ Last consumer migrated — not before |
| IF-03 | Eligibility inquiry and response | Request/response | Core administration cutover |
| IF-04 | Claims, target platform to ACME | One way | Core administration cutover |
| IF-05 | Remittance advice | One way | Final payment cycle on the retiring platform |
| IF-06 | Accumulator synchronization | ⚠ Bidirectional | Core administration cutover. See §7. |
| IF-07 | Provider master distribution | Broadcast | Provider master consolidation |
| IF-08 | Authorization status | Request/response | ⚠ Care management is preserved — this one outlives the others |
| IF-09 | Care management member feed | One way | Permanent until care management platform decision |
| IF-10 | Premium billing and payment | One way | Billing consolidation |
| IF-11 | Financial posting to general ledger | One way | TSA general ledger exit |
| IF-12 | Member correspondence and ID cards | One way | Correspondence consolidation |
| IF-13 | Data warehouse ingestion | One way | ⚠ Permanent — see BRD-04. Not part of the temporary layer. |
| IF-14 | Write-back to the retiring platform | ⚠ Into the retiring system | Core administration cutover. See §7. |
IF-02's retirement trigger is the one that catches programs out, and it is why FR-13 requires a registered consumer list. An identifier broadcast has no natural end — it stops being needed when the last system consuming it has migrated, and nobody centrally knows what that list is unless it was recorded at connection time. The failure is not dramatic: the interface simply runs for two more years because switching it off is a risk nobody can quantify. ⚠ IF-09 and IF-13 are deliberately marked as outliving the layer, so that "all interfaces retired" cannot be quietly satisfied by forgetting them.
6. Reliability, Reconciliation and Replay
An integration layer is judged on what it does when something fails, because during coexistence something is failing somewhere most days. The requirements here assume failure as the normal case rather than the exception, which changes what they ask for.
The central obligation is reconciliation rather than delivery confirmation. Knowing a message was accepted tells you very little: the receiving system may have accepted it and applied it differently, or applied it and later reversed it, or accepted a batch in which one record silently failed validation. So FR-11 requires periodic comparison of the two sides' state, not merely acknowledgement of the traffic between them — the question is whether the systems agree, not whether the messages arrived.
Replay follows from the same reasoning. When reconciliation finds a difference, the layer must be able to re-send a specific range without re-sending everything, and re-sending must be safe. That makes idempotency a requirement rather than an implementation detail: a message applied twice must leave the same state as a message applied once, because during an incident nobody can be certain what was already processed.
⚠ The requirement that looks like over-engineering is the one that pays. Full reconciliation across two claims platforms is expensive to build and produces nothing visible while both sides agree. Its value arrives entirely on the day they do not — and on a program where a member's identity, coverage and accumulators are being resolved across two systems at once, a silent divergence is not an integration defect. It is a member receiving the wrong answer.
| Ref | Priority | Requirement | Detail |
|---|---|---|---|
| FR-07 | Must | Guaranteed delivery | No message lost. Delivery confirmed by the receiving system, not by the layer. |
| FR-08 | Must | Idempotency | ⚠ A message delivered twice produces the same result as once. Retry is the primary recovery mechanism and it is only safe if this holds. |
| FR-09 | Must | Ordered delivery where order matters | Accumulator and coverage changes are order-sensitive; provider updates are not. Stated per interface. |
| FR-10 | Must | Business-level control totals | ⚠ Every interface reconciles on counts and amounts. A syntactic acknowledgment is not acceptance — a pipeline treating it as success reports green while enrollment silently fails. |
| FR-11 | Must | Replay within a bounded window | Messages replayable for a defined period. ⚠ Bounded deliberately — an unbounded store is a data store, and a data store is not deletable. |
| FR-12 | Must | Failures alert with context | Which interface, which record, which side, what failed. Not a generic error. |
7. The Two Hard Interfaces
IF-06 and IF-14 are the two that carry disproportionate risk, and for the same reason.
| Ref | Priority | Requirement | Detail |
|---|---|---|---|
| FR-13 | Must | Accumulator synchronization is near real time | ⚠ Latency here is a wrong member liability quoted at the point of service |
| FR-14 | Must | Accumulator conflicts resolved by recomputation | ⚠ Not by last-writer-wins. Both sides' claims are summed; the balance is derived, never chosen. |
| FR-15 | Must | Write-back failures surface on both sides | ⚠ A failed write into the retiring platform must alert both systems' operators |
| FR-16 | Must | Write-back is reconciled daily | Independent comparison of what should have been written against what is present |
IF-06 and IF-14 are hard for the same reason, and it is not technical complexity. Both write into a platform that is being retired, and a retiring platform has a shrinking operational team, reduced monitoring and nobody incentivized to investigate an anomaly. So a failure on these interfaces is silent on both sides: the sending system believes it sent, and the receiving system has nobody watching. ⚠ Accumulators make it worse, because they are cumulative — a missed write does not produce one wrong answer, it produces a wrong running balance that persists and compounds until somebody reconciles. FR-16 exists because the alerting in FR-15 depends on a failure being detected, and the failure mode that matters here is the one where nothing reports an error at all.
8. Retirement Requirements
This section is the one that makes the document unusual, and it is placed here deliberately: the retirement requirements constrain the BUILD, not the shutdown. They are not a decommissioning plan to be written later. They are conditions the layer must satisfy from its first release, because a component built without them cannot be switched off afterwards at any price.
Three requirements carry that weight. Registered consumers (FR-18): nothing may consume an interface without being recorded as consuming it. The failure this prevents is the one that ends every decommissioning attempt — the layer is scheduled for shutdown, and nobody can say with confidence who is still calling it, so the shutdown is deferred pending an investigation that never concludes. A register maintained from day one costs almost nothing; reconstructing it two years later from traffic logs and institutional memory costs a quarter and produces a maybe.
Zero-traffic evidence (FR-19): the shutdown gate is not a date and not an assurance from the owning team, but a measured period of no traffic from any registered consumer. This converts "we think nothing uses it" into an observation, and it is deliberately a period rather than a moment, because seasonal and month-end consumers are exactly the ones a spot check misses.
No persistent store (FR-20): the layer may hold state in flight but may not become the system of record for anything. This is the requirement most likely to be argued against during build, always for a good local reason — caching a lookup improves latency, holding a cross-reference avoids a round trip. The moment the layer owns data nobody else has, it cannot be deleted; it has quietly become a platform, and the retirement plan becomes a migration project nobody budgeted.
⚠⚠ FR-22 refuses new business rules, and records the refusal. Every request to put a rule in the layer is individually defensible: the logic touches two systems, neither is a natural owner, and the layer sits conveniently between them. Each exception is reasonable and the aggregate is fatal — a layer holding business rules is the thing the program must keep, and it will hold them where nobody thinks to look when the rules later need changing. Recording the refusal matters as much as making it: it leaves evidence that the question was asked and answered, so the next person to ask does not have to rediscover the reasoning, and so a deliberate later decision to relax the rule is visible as a decision.
The requirements that make removal possible. They are stated as requirements rather than as an operational plan because they constrain the build, not the shutdown.
| Ref | Priority | Requirement | Detail |
|---|---|---|---|
| FR-17 | Must | Registered consumer list | ⚠ Every consumer registers at connection time. An interface with unknown consumers cannot be switched off. |
| FR-18 | Must | Traffic observable per interface per consumer | Volume by consumer, so zero traffic can be evidenced rather than assumed |
| FR-19 | Must | Retirement is evidenced by zero traffic | ⚠ A defined quiet period with no traffic from any registered consumer — not a belief that nothing uses it |
| FR-20 | Must | Interface-level shutdown | Interfaces retire individually. ⚠ The layer is not all-or-nothing. |
| FR-21 | Must | No persistent store beyond the replay window | ⚠ State makes the layer a system of record, and a system of record cannot be deleted |
| FR-22 | Must | New business rules are refused | ⚠ A change request adding logic to the layer is rejected and redirected to the owning system, with the refusal recorded |
| FR-23 | Should | Decommissioning documented per interface | What it did, what replaced it, when traffic stopped |
FR-22 is the requirement most likely to be overridden, and the override will always be reasonable at the time. A consumer needs a small derivation; the owning system's change is a two-month queue; the layer can do it this week. Each individual exception is defensible and the aggregate is fatal: after four of them the layer holds business rules nobody documented, several consumers depend on behavior only it provides, and the retirement date quietly stops being achievable. ⚠ Recording the refusals matters as much as enforcing them — it is the evidence that the boundary was defended, and it is what a Year 3 reader needs to understand why the layer could still be switched off.
The failure this whole section is written against is specific enough to describe. A "temporary" integration layer still running in Year 3, quietly load-bearing, with three undocumented consumers and one business rule added under deadline pressure — and a project to remove it that costs more than building it did. Every requirement in §8 is cheap at build time and none of them can be retrofitted. A consumer list assembled after the fact is a survey; traffic instrumentation added later has no history to prove absence.
9. Non-Functional Requirements
| Ref | Requirement | Target |
|---|---|---|
| NFR-01 | Eligibility response latency | ⚠ Within the point-of-service window. This sits in front of a pharmacy counter. |
| NFR-02 | Accumulator propagation | Near real time, measured end to end rather than at the layer boundary |
| NFR-03 | Throughput | Peak daily claim and enrollment volume with headroom for catch-up after an outage |
| NFR-04 | Availability | Tier 1. ⚠ An outage does not lose messages — it delays them. |
| NFR-05 | Security | Encrypted in transit and at rest; PHI never logged in clear |
| NFR-06 | Observability | Per-interface, per-consumer volume and error rates, retained through retirement |
10. Testing and Validation
The layer cannot be tested in isolation in any way that means much. Its correctness is a property of the conversation between two platforms, both of which are moving — one being configured, one being retired, both under change from the migration waves.
So the requirements specify testing against the pair rather than against the layer's own contract. An interface passes when the receiving system's state matches the sending system's after the exchange, verified through the same reconciliation the layer runs in production. This has the useful property of testing the reconciliation itself: a mechanism that only runs during incidents gets exercised routinely instead of being trusted on the day it is first needed.
⚠ What cannot be tested before cutover is volume under contention — both platforms live, both under production load, with the migration waves running. The requirement set handles this by degrading predictably rather than by claiming coverage: FR-24 requires the layer to shed load in a stated order and to report what it shed, so that an overload produces a known deferral rather than an unknown loss.
| Test | Owner | Criterion |
|---|---|---|
| Interface regression | P. Devarakonda | All 14 against agreed message sets. ⚠ Against de-identified data — offshore team. |
| Reconciliation | A. Feldstein | Business-level control totals per interface, not acknowledgments |
| Idempotency and replay | O. Hargrave | ⚠ Deliberate duplicate delivery produces one result. Fault-injected, not assumed. |
| Accumulator convergence | T. Calloway | Concurrent updates on both sides converge to the recomputed balance |
| Write-back failure detection | J. Amonett | ⚠ A deliberately failed write is detected on both sides within the alerting window |
| Consumer registration | R. Delacroix | An unregistered consumer is refused connection |
11. Acceptance Criteria
- Every Must requirement demonstrated.
- Canonical definitions signed by both entities before mapping was written.
- All 14 interfaces reconciling on business-level control totals.
- ⚠ Idempotency proven by deliberate duplicate delivery, not by design review.
- ⚠ A deliberately failed write-back detected on both sides. A detection path that has never fired is a hypothesis.
- Registered consumer list complete, with an unregistered connection attempt refused in test.
- Per-interface, per-consumer traffic observable and retained.
- ⚠ Zero business rules in the layer, evidenced by the refusal log rather than by assertion.
12. Constraints, Assumptions and Dependencies
The layer inherits its schedule from work it does not control. Its interfaces must exist before the migration waves that depend on them, and they must be retired after the last consumer moves — so its lifespan is bounded at both ends by other people's plans. It is the only work package on this program whose completion is defined by its own disappearance.
That creates a governance problem worth naming. A team building something designed to be deleted has no natural incentive to argue for its extension, but it also has no protection when other workstreams find it convenient. Every request to add a rule, cache a value or hold a cross-reference arrives as a small favor to a colleague under pressure, and the person best placed to refuse is the person who most wants to be helpful.
⚠ Which is why the constraint is written as a requirement rather than a principle. A principle is something a team is asked to uphold under pressure. FR-20 and FR-22 are acceptance criteria: the layer does not pass without them, and an exception has to be argued at the gate rather than agreed in a corridor. The distinction matters most at exactly the moment the pressure is highest, which is when principles lose and criteria hold.
| Type | Item | Consequence |
|---|---|---|
| Constraint | Coexistence period is 12–15 months | ⚠ The justification for the layer. If it extends materially, §2 is re-opened. |
| Constraint | The retiring platform cannot be modified | Write-back uses existing interfaces only. No changes to a system being decommissioned. |
| Constraint | Offshore testing is de-identified only | Regression runs on synthetic data; anything needing real member records is onshore |
| Assumption | Retiring platform monitoring remains staffed through cutover | ⚠ FR-15 alerting depends on somebody receiving the alert |
| Dependency | Enterprise member identifier | ⚠ IF-02 has nothing to broadcast until identity resolution produces it. BRD-01 gates this. |
| Dependency | Canonical definitions agreed | Both entities, before mapping |
| Dependency | Landing zone accepted | Met January 15, 2024 |
13. Traceability
| Requirement | Design artifact | Verified by | Evidence |
|---|---|---|---|
| FR-01 to FR-06 | 25 — Integration Architecture §2 | Mapping review | Signed canonical definitions |
| FR-07 to FR-12 | 25 — Integration Architecture §3 | Reconciliation, replay test | Control totals; duplicate-delivery result |
| FR-13 to FR-16 | 25 — §2.2 and §4.1 | Convergence and failure-detection tests | ⚠ Injected write-back failure detected both sides |
| FR-17 to FR-23 | 25 — §8; 39 — Interface Cutover Log | Registration test, traffic evidence | Consumer list; zero-traffic records; refusal log |
| NFR-01 to NFR-06 | 26 — Quality Plan | Performance and recovery testing | End-to-end latency, tested restore |
14. Sign-Off and Approval
The fourth signature is unusual and it is the one doing real work. The architect is not signing to confirm the design is sound — that is the first two signatures. He is accepting personal ownership of FR-22: the standing obligation to refuse business logic in the layer, repeatedly, against reasonable requests from colleagues under deadline pressure, for the whole coexistence period. ⚠ That obligation has no natural owner unless someone is named, and a boundary defended by nobody in particular is defended until the first time it is inconvenient.
Related artifacts: BRD-01 — Identity Resolution · BRD-02 — Core Administration · 25 — Integration Architecture · 26 — Quality Plan · 20 — Application Disposition Matrix · 28 — Risk Register