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
Part I — Context
Part II — Requirements
- Canonical Model
- Interface Catalog
- Reliability, Reconciliation and Replay
- The Two Hard Interfaces
- Retirement Requirements
- Non-Functional Requirements
Part III — Proving It
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
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
| 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
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
| 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
| 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
Business owner
K. Stallworth
Director, Enterprise Integration, ACME · workstream lead
Date: _______________
Accountable executive
S. Achebe
Chief Information Officer, ACME Health
Date: _______________
Target-side acceptance
J. Amonett
Manager, Interfaces, Cumberland Valley · counterpart
Date: _______________
Architecture governance
R. Delacroix
Integration Architect · owns FR-22 refusals
Date: _______________
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