TPA Platform Blueprint Plan

01Executive summary

We will build TPA, a separate product from OptimaX, for Third Party Administrators and for insurance companies that outsource medical administration in Saudi Arabia. The Saudi market currently has very few licensed medical TPAs. Our OptimaX team already runs pre-authorization and claims adjudication through NPHIES, plus provider and client portals, in production. That experience is the main head start. It is also the main risk, because an insurer's workflows assume the system owns the risk, the premium and the policy, and a TPA owns none of those.

Recommended approach

• Architecture: .NET modular monolith for the core business domains, with independently scalable background workers (adjudication, NPHIES gateway, batch intake, notifications, documents, SLA timers) connected through a message broker. Split into services only where load or release cadence justifies it. ARCHITECTURE DECISION REQUIRED
• Configuration over code: benefits, adjudication edits, authorization rules, tariffs, SLAs and fee models are versioned, effective-dated data scoped to Insurance Company, so onboarding IC number 12 is a configuration project, not a release.
• MVP: one pilot TPA, 1–3 insurance companies, full eligibility → pre-authorization → claim → adjudication → settlement-instruction loop through NPHIES and the provider portal, with client portal, core reports, roles and audit. Proposed elapsed time to first production go-live: 12–15 months with a team of about 28 (proposed estimate, depends on discovery answers).
• Working method: discovery questions first, then vision and scope, then architecture and BRD, then the gap analysis and a final consistency review. Development starts only after management approves the blueprint.

02Insurance company ERP vs TPA ERP

The single most important distinction in the blueprint. Every module will be checked against this table in the final review so that no insurer-only feature leaks into the TPA product.

03What we reuse from OptimaX

Based on a read-only review of E:\SALAMA\OptimaX_Unified (Angular Salama_OptimaX, API Salama_OptimaX_Api). Here "reuse" means domain knowledge, screens, stored-procedure logic and shared libraries used as a starting point. TPA is a new codebase, built for many insurers and high volume from the start. The OptimaX databases could not be reached during the review, so the table structures and claim status values still need checking. BUSINESS CONFIRMATION REQUIRED

04Module map and phase allocation

All 43 modules from the brief (A–AQ), grouped into ten business domains. Phase badges are the proposed allocation; reasons for the MVP items are in section 15.

05Multi-insurance-company design

Reference scenario used throughout the BRD and architecture: one TPA, 15 insurance companies, all sending claims through NPHIES, millions of claims and claim lines.

flowchart LR
  subgraph PRV["Healthcare providers"]
    P1["NPHIES-integrated hospitals and clinics"]
    P2["Non-NPHIES providers"]
  end
  NPH["NPHIES national platform"]
  subgraph TPA["TPA platform"]
    GW["NPHIES integration gateway"]
    PP["Provider portal"]
    CORE["TPA core: members, benefits, authorization, claims, settlement"]
    CP["Client portal"]
    MP["Member app and portal"]
    BI["Reporting and data warehouse"]
  end
  subgraph ICS["Insurance companies"]
    IC1["IC-001"]
    IC2["IC-002"]
    ICN["IC-015"]
  end
  P1 -->|"eligibility, preauth, claims"| NPH
  NPH --> GW
  P2 --> PP
  GW --> CORE
  PP --> CORE
  ICS -->|"policies, schemes, members, funding"| CORE
  CORE -->|"approvals, statements, invoices, reports"| ICS
  CP --> CORE
  MP --> CORE
  CORE --> BI
  

Fig. 1 · TPA ecosystem with multiple insurance companies

Noisy-neighbour protection

One IC's spike must not breach another IC's SLA. The plan: queues partitioned by IC, a fair scheduler that gives each IC a guaranteed share of adjudication workers, per-IC and per-provider rate limits at the gateway, separate priority lanes (real-time eligibility and pre-authorization ahead of batch claims), and autoscaling worker pools. Large ICs can later get dedicated worker pools or database shards without code change. ARCHITECTURE DECISION REQUIRED

Deployment model: the product is sold to multiple TPAs. Proposed: a dedicated deployment per TPA customer (simpler data residency and regulator conversations), with a TenantId kept in the schema so a shared SaaS model remains possible. ARCHITECTURE DECISION REQUIRED

06NPHIES integration architecture

Four clearly separated parties: provider systems, NPHIES, the TPA's NPHIES integration layer, and the TPA core. The core never speaks FHIR directly.

flowchart TD
  A["NPHIES bundle received by gateway"] --> B["Persist raw bundle, message id, timestamps"]
  B --> C{"Message id already processed?"}
  C -->|"Yes"| D["Return stored response, no reprocessing"]
  C -->|"No"| E["Read insurer and coverage from bundle"]
  E --> F{"Mapped to an InsuranceCompanyCode?"}
  F -->|"No"| G["Quarantine queue and operations alert"]
  F -->|"Yes"| H["Stamp IC code and correlation id"]
  H --> I["Publish to IC-partitioned queue"]
  I --> J["Resolve policy, scheme, member, provider contract"]
  J --> K["Validate and adjudicate with the IC rule set"]
  K --> L["Build FHIR response"]
  L --> M["Return to NPHIES directly or via poll"]
  

Fig. 2 · NPHIES → TPA → insurance company routing

The exact transaction list, the FHIR profiles, how a TPA is identified as message receiver for multiple payers, response-time limits, attachment size limits and certification steps must be taken from the current NPHIES implementation guide. EXTERNAL VALIDATION REQUIRED

Reliability controls

• Store first, process second: the raw bundle is durably saved before any business logic, so nothing received is ever lost.
• Idempotency: key on the NPHIES message identifier plus bundle identifier; duplicates return the original response.
• Correlation id: one id flows from gateway through queue, core, response and audit, and across OpenTelemetry traces.
• Retry and dead-letter: exponential backoff with jitter for outbound calls, circuit breaker on NPHIES endpoints, dead-letter queue with an operations replay screen.
• Message tracking: every inbound and outbound message with status, IC, provider, timings and error payloads, searchable by operations staff.
• Reconciliation: daily per-IC counts and amounts, NPHIES vs TPA, with exceptions listed for action.

07Claims engine

The example lifecycle in the brief mixes processing states with outcomes and financial states. The proposed model separates them: a processing status on the claim, a decision on each line (approved, partially approved, rejected, with reason codes) and a financial status (not payable, payable, in batch, paid, reconciled).

stateDiagram-v2
  [*] --> Received
  Received --> IntakeRejected: unreadable, unmapped IC, duplicate
  Received --> Registered: IC, member, provider resolved
  Registered --> Validating
  Validating --> ValidationFailed: hard edits fail
  Validating --> PendingInfo: information requested
  PendingInfo --> Validating: provider responds
  PendingInfo --> Adjudicated: no response within window
  Validating --> AutoAdjudication
  AutoAdjudication --> Adjudicated: all lines decided by rules
  AutoAdjudication --> ManualReview: pended by rule
  AutoAdjudication --> FWAHold: fraud score above threshold
  FWAHold --> ManualReview
  ManualReview --> MedicalReview: clinical question
  MedicalReview --> ManualReview
  ManualReview --> PayerApproval: above delegated authority
  PayerApproval --> ManualReview
  ManualReview --> Adjudicated
  Adjudicated --> ResponseSent
  ResponseSent --> Reconsideration: provider disputes lines
  Reconsideration --> AutoAdjudication: reprocess
  ResponseSent --> ReadyForSettlement: payable amount exists
  ResponseSent --> Closed: nothing payable, window expired
  ReadyForSettlement --> InSettlementBatch
  InSettlementBatch --> Paid: payment confirmed
  Paid --> Reconciled
  Reconciled --> Closed
  ValidationFailed --> Closed
  IntakeRejected --> [*]
  Closed --> [*]
  

Fig. 3 · Proposed claim processing lifecycle (line-level decisions and financial status tracked separately)

• Resubmission creates a new claim linked to the original (not an edit of the old one), preserving the audit trail and NPHIES semantics. EXTERNAL VALIDATION REQUIRED
• Appeal / dispute (Phase 2) is a case attached to a closed or adjudicated claim, with its own workflow and SLA, so it does not reopen the claim state machine.
• Payer Approval exists only because the TPA works under delegated authority. An insurer system would not need it.
• Cancelled (by provider) and Reversed (after payment, through a debit/credit adjustment) are also states, omitted from the figure for readability.

Pipeline stages

Target auto-adjudication rate is a business KPI set per IC, not a system constant. BUSINESS CONFIRMATION REQUIRED

08Benefit engine and rule engine

Benefits must be configurable without code changes. Rules split into what business users configure and what developers build once as reusable rule types.

Rule engine options to evaluate: a home-grown decision-table engine compiled to expression trees, the open-source Microsoft RulesEngine (JSON rules), or NRules. Every rule set is versioned, effective-dated, IC-scoped, testable against sample claims before activation and protected by maker–checker approval. ARCHITECTURE DECISION REQUIRED

09Financial and settlement boundary

The TPA does not own insurance risk. It owns the calculation, instruction, tracking and reconciliation of money that belongs to insurers or self-funded clients, plus its own fee revenue.

sequenceDiagram
  participant P as Provider
  participant T as TPA platform
  participant I as Insurance company
  participant B as Bank
  T->>T: Group payable lines by IC, provider, cycle
  T->>I: Settlement batch and funding request
  alt Model A, insurer pays
    I->>B: Execute payments from instruction file
    B-->>I: Bank confirmation
    I-->>T: Payment confirmation file
  else Model B, TPA-managed claim fund
    I->>B: Fund TPA claim account for IC
    T->>B: Execute payments
    B-->>T: Bank confirmation
  end
  T->>P: Remittance advice and payment notice
  T->>T: Reconcile line, claim, provider, IC ledger
  T->>I: Periodic IC statement and TPA fee invoice
  

Fig. 4 · Provider settlement with the two candidate funding models

Which funding model each IC uses, whether self-funded corporate (ASO) schemes are in scope, and whether TPA fees are netted from the fund are commercial decisions to confirm during discovery. BUSINESS CONFIRMATION REQUIRED

10Technical architecture

flowchart TB
  subgraph CH["Channels"]
    WEB["Angular portals: TPA operations, provider, client, member"]
    MOB["Mobile app"]
    EXT["IC and partner APIs"]
  end
  NPH["NPHIES"]
  APIGW["API gateway: WAF, rate limits per IC and provider"]
  IDP["Identity provider: OIDC, OAuth2, MFA"]
  subgraph CORE["TPA core, .NET modular monolith"]
    M1["Payer, client, policy reference"]
    M2["Members and enrollment"]
    M3["Providers, network, tariffs"]
    M4["Benefit and rule engine"]
    M5["Authorization and claims"]
    M6["Settlement and billing"]
  end
  subgraph WK["Background workers, scaled independently"]
    W1["Adjudication workers"]
    W2["Batch and file intake"]
    W3["Notification service"]
    W4["Document service and virus scan"]
    W5["SLA timers and escalation"]
  end
  NGW["NPHIES integration gateway"]
  MQ["Message broker: per-IC queues, dead-letter"]
  RDS["Redis cache"]
  SQL[("SQL Server OLTP, partitioned, readable replicas")]
  OBJ[("Object storage for documents")]
  SRCH[("Search index")]
  DW[("Reporting database and warehouse")]
  OBS["Observability: OpenTelemetry logs, metrics, traces"]
  WEB --> APIGW
  MOB --> APIGW
  EXT --> APIGW
  APIGW --> IDP
  APIGW --> CORE
  NPH --- NGW
  NGW --> MQ
  CORE --> MQ
  MQ --> WK
  CORE --> SQL
  WK --> SQL
  CORE --> RDS
  W4 --> OBJ
  SQL -->|"CDC"| DW
  SQL -->|"CDC"| SRCH
  CORE -.-> OBS
  WK -.-> OBS
  

Fig. 5 · High-level system architecture

Hosting must be inside Saudi Arabia. On-premises, a Saudi-region cloud, or a hybrid are all candidates; the choice drives the broker, gateway and storage products above. ARCHITECTURE DECISION REQUIRED EXTERNAL VALIDATION REQUIRED

11Scalability and performance

The goal is to grow from one million to a billion-plus claims by adding capacity and moving data, not by redesigning the product. The decisions that make this possible are taken at MVP even though the later stages are not built then.

flowchart LR
  H["Hot: current and previous year, monthly partitions"] --> W["Warm: older years, read-only compressed filegroups"]
  W --> C["Cold archive: past retention threshold, restorable"]
  H -->|"CDC"| D["Warehouse: IC-level and consolidated reporting"]
  W -->|"CDC history"| D
  

Fig. 6 · Hot, warm and cold data tiers (retention periods to be confirmed BUSINESS CONFIRMATION REQUIRED)

Proposed performance targets

Starting points for discussion, to be validated by load testing during the architecture POC. They are not commitments.

12Data architecture

erDiagram
  INSURANCE_COMPANY ||--o{ TPA_SERVICE_CONTRACT : "engages TPA under"
  INSURANCE_COMPANY ||--o{ POLICY : "issues"
  CLIENT ||--o{ POLICY : "holds"
  POLICY ||--o{ SCHEME : "defines"
  SCHEME ||--o{ BENEFIT : "includes"
  BENEFIT ||--o{ BENEFIT_LIMIT : "constrained by"
  SCHEME }o--|| NETWORK : "uses tier"
  POLICY ||--o{ MEMBER : "covers"
  MEMBER ||--o{ BENEFICIARY : "has dependants"
  MEMBER }o--|| SCHEME : "enrolled in"
  PROVIDER ||--o{ PROVIDER_BRANCH : "operates"
  PROVIDER ||--o{ PROVIDER_CONTRACT : "signs"
  PROVIDER_CONTRACT ||--o{ PROVIDER_TARIFF : "prices services"
  NETWORK }o--o{ PROVIDER_BRANCH : "includes"
  MEMBER ||--o{ AUTHORIZATION : "requests"
  MEMBER ||--o{ CLAIM : "receives care under"
  PROVIDER_BRANCH ||--o{ CLAIM : "submits"
  INSURANCE_COMPANY ||--o{ CLAIM : "owns"
  CLAIM ||--|{ CLAIM_LINE : "contains"
  AUTHORIZATION |o--o{ CLAIM_LINE : "authorizes"
  NPHIES_MESSAGE |o--o{ CLAIM : "carries"
  SETTLEMENT_BATCH ||--o{ CLAIM_LINE : "pays"
  SETTLEMENT_BATCH ||--o{ PAYMENT : "settled by"
  INSURANCE_COMPANY ||--o{ INVOICE : "billed TPA fees"
  

Fig. 7 · Core logical ERD (diagnosis, procedure, service, document, notification, audit, user and role entities detailed in 12_ERD.md)

13Security and compliance

14Roles and permissions

Condensed matrix. Every grant is additionally limited by data scope: the ICs, clients, providers or branches assigned to the user. The full action-level matrix goes into 13_Roles_Permissions.md.

F full · A approve within limits · E create and edit · V view · S self-scope only (own provider, own client, own record) · – none

15MVP, Phase 2 and Phase 3

16Implementation roadmap

All durations are proposed estimates for a team of about 28, assuming discovery answers arrive on time and NPHIES TPA onboarding is not blocked. Many phases overlap. The start date is illustrative.

gantt
  title Proposed MVP roadmap, illustrative dates
  dateFormat YYYY-MM-DD
  axisFormat %b %Y
  section Shape
  Discovery              :d1, 2026-11-02, 6w
  Architecture and POC   :a1, 2026-11-30, 6w
  UX and UI              :u1, 2026-12-14, 8w
  section Build
  Foundation             :f1, after a1, 8w
  Masters                :m1, after f1, 5w
  Client and member      :c1, after m1, 7w
  Provider and network   :p1, after m1, 7w
  Benefits               :b1, after c1, 7w
  Authorization          :au1, after b1, 6w
  Claims                 :cl1, after c1, 14w
  NPHIES gateway         :n1, after f1, 24w
  Portals                :po1, after p1, 14w
  Financial settlement   :fs1, after b1, 8w
  Reporting              :r1, after b1, 8w
  section Assure
  Security hardening     :s1, after cl1, 4w
  SIT and performance    :t1, after cl1, 7w
  UAT with pilot IC      :ua1, after t1, 6w
  Go-live and hypercare  :g1, after ua1, 6w
  

Fig. 8 · Proposed MVP roadmap, about 12–15 months to first go-live

17Development team

18Testing, deployment and production support

19Risks, assumptions and dependencies

20Key discovery questions

Highest-impact questions for management and the business team. The full list goes into 00_Discovery_Questions.md, the first document produced.

21Documentation package and working sequence

Produced in four stages, as the brief requires. Each stage is reviewed before the next begins. Output folder: E:\TPA\docs\, with all Mermaid sources in E:\TPA\docs\diagrams\.