From 97d1829f91a65689e3f98a0a6dba06b5cb44d28d Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Wed, 6 May 2026 14:17:32 +0530 Subject: [PATCH 1/5] init: scaffold full 5-layer IPP context library structure --- .github/CODEOWNERS | 1 + layer-01/README.md | 10 ++++ layer-01/acord-patterns/README.md | 8 +++ layer-01/platform-systems/README.md | 29 ++++++++++ .../platform-system-template_v2_0.md | 43 ++++++++++++++ layer-01/reusable-features/README.md | 8 +++ layer-01/standard-decisions/README.md | 6 ++ layer-02/README.md | 9 +++ layer-02/beacon-fe-wl/README.md | 13 +++++ layer-02/jh-rop-linkout/README.md | 13 +++++ layer-02/sahara-iul/README.md | 13 +++++ layer-03/README.md | 11 ++++ layer-03/linkout/README.md | 11 ++++ layer-03/native-carrier-admin/README.md | 9 +++ layer-03/native-direct-admin/README.md | 7 +++ layer-03/native-ethos-admin/README.md | 10 ++++ layer-03/native-shadow-admin/README.md | 9 +++ layer-04/README.md | 56 +++++++++++++++++++ layer-05/README.md | 31 ++++++++++ layer-05/child-prd-templates/.gitkeep | 0 20 files changed, 297 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 layer-01/README.md create mode 100644 layer-01/acord-patterns/README.md create mode 100644 layer-01/platform-systems/README.md create mode 100644 layer-01/platform-systems/platform-system-template_v2_0.md create mode 100644 layer-01/reusable-features/README.md create mode 100644 layer-01/standard-decisions/README.md create mode 100644 layer-02/README.md create mode 100644 layer-02/beacon-fe-wl/README.md create mode 100644 layer-02/jh-rop-linkout/README.md create mode 100644 layer-02/sahara-iul/README.md create mode 100644 layer-03/README.md create mode 100644 layer-03/linkout/README.md create mode 100644 layer-03/native-carrier-admin/README.md create mode 100644 layer-03/native-direct-admin/README.md create mode 100644 layer-03/native-ethos-admin/README.md create mode 100644 layer-03/native-shadow-admin/README.md create mode 100644 layer-04/README.md create mode 100644 layer-05/README.md create mode 100644 layer-05/child-prd-templates/.gitkeep diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..2c1ec16 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @getethos/ipp diff --git a/layer-01/README.md b/layer-01/README.md new file mode 100644 index 0000000..8948360 --- /dev/null +++ b/layer-01/README.md @@ -0,0 +1,10 @@ +# Layer 01 — Platform Knowledge + +Loaded by every agent, on every product. + +| Folder | What belongs here | +|--------|-------------------| +| platform-systems/ | One file per platform system. Use platform-system-template_v2_0.md as scaffold. | +| acord-patterns/ | Standard ACORD transaction patterns — TX103, TX1203, TX1228, TX111. | +| standard-decisions/ | Platform-level decisions true on every product. | +| reusable-features/ | Feature specs shared across products — IDV, Flexible Billing, eSignature, Product Bundling. | diff --git a/layer-01/acord-patterns/README.md b/layer-01/acord-patterns/README.md new file mode 100644 index 0000000..9f1221d --- /dev/null +++ b/layer-01/acord-patterns/README.md @@ -0,0 +1,8 @@ +# ACORD Patterns + +| Transaction | Description | File | Status | +|-------------|-------------|------|--------| +| TX103 | New business submission — outbound to carrier | tx103_v2_0.md | Outstanding | +| TX1203 | Policy status / UW decision — inbound from carrier | tx1203_v2_0.md | Outstanding | +| TX1228 | Premium / billing — inbound from carrier | tx1228_v2_0.md | Outstanding | +| TX111 | Cancellation / lapse — bidirectional | tx111_v2_0.md | Outstanding | diff --git a/layer-01/platform-systems/README.md b/layer-01/platform-systems/README.md new file mode 100644 index 0000000..2527ec0 --- /dev/null +++ b/layer-01/platform-systems/README.md @@ -0,0 +1,29 @@ +# Platform Systems + +| System | File | IPP Role | Status | +|--------|------|----------|--------| +| Policy Configuration Service (PCS) | pcs_v2_0.md | IPP owns | Outstanding | +| Product Routing Service (PRS) | prs_v2_0.md | IPP owns | Outstanding | +| Document Generation Service | doc-gen_v2_0.md | IPP owns | Outstanding | +| eSignature Service | esignature-service_v2_0.md | IPP owns | Draft | +| ACORD Feed Framework | acord-feed-framework_v2_0.md | IPP owns | Outstanding | +| Carrier Data Feeds | carrier-data-feeds_v2_0.md | IPP owns | Outstanding | +| DTC Application Funnel | dtc-funnel_v2_0.md | IPP integrates | Outstanding | +| Agent Assisted App Funnel | agent-assist-funnel_v2_0.md | IPP integrates | Outstanding | +| Microsite Funnel | microsite-funnel_v2_0.md | IPP integrates | Outstanding | +| LOB.com | lob_v2_0.md | IPP integrates | Outstanding | +| Agent Portal | agent-portal_v2_0.md | IPP integrates | Outstanding | +| Member Portal | member-portal_v2_0.md | IPP integrates | Outstanding | +| Main App (policy flow) | main-app_v2_0.md | IPP integrates | Outstanding | +| Policy Admin System (PAS2) | pas2_v2_0.md | IPP integrates | Outstanding | +| Underwriting (UW 2.0) | uw2_v2_0.md | IPP integrates | Outstanding | +| Payment Platform / Stripe | payments-stripe_v2_0.md | IPP integrates | Outstanding | +| Profile Service | profile-service_v2_0.md | IPP integrates | Outstanding | +| Iterable | iterable_v2_0.md | IPP integrates | Outstanding | +| NetSuite | netsuite_v2_0.md | IPP integrates | Outstanding | +| Commission Feeds / Validation | commission-feeds_v2_0.md | IPP integrates | Outstanding | +| OTP Service | otp-service_v2_0.md | PRT owns | Outstanding | +| Partnerships System | partnerships_v2_0.md | PRT owns | Outstanding | +| Error Classification Pipeline | error-classification_v2_0.md | IPP integrates | Needs Validation | + +Note — Error Classification Pipeline: Confirmed as built (Pankaj). Rules and logic require validation before documenting as confirmed behavior. diff --git a/layer-01/platform-systems/platform-system-template_v2_0.md b/layer-01/platform-systems/platform-system-template_v2_0.md new file mode 100644 index 0000000..543b48a --- /dev/null +++ b/layer-01/platform-systems/platform-system-template_v2_0.md @@ -0,0 +1,43 @@ +# [System Name] — Platform System Context + +**Version:** v2.0 +**Last updated:** YYYY-MM-DD +**Context owner:** [Name] +**IPP relationship:** [IPP owns / IPP integrates / PRT owns] +**Status:** [Outstanding / Draft / In Review / Certified] + +## 1. System Overview +None documented. + +## 2. IPP Touchpoints +None documented. + +## 3. Key Behaviors +None documented. + +## 4. ACORD Transactions +None documented. + +## 5. Data Inputs / Outputs +None documented. + +## 6. Standard Decisions +None documented. + +## 7. Known Constraints +None documented. + +## 8. Carrier-Specific Variations +None documented. + +## 9. Needs Validation +None. + +## 10. Source Documents +| Document | Type | Date | Notes | +|----------|------|------|-------| + +## 11. Change Log +| Version | Date | Author | Summary | +|---------|------|--------|---------| +| v2.0 | YYYY-MM-DD | | Initial draft | diff --git a/layer-01/reusable-features/README.md b/layer-01/reusable-features/README.md new file mode 100644 index 0000000..34e2544 --- /dev/null +++ b/layer-01/reusable-features/README.md @@ -0,0 +1,8 @@ +# Reusable Features + +| Feature | File | Status | +|---------|------|--------| +| Identity Verification (IDV) | idv-standard_v2_0.md | Outstanding | +| Flexible Billing | flexible-billing_v2_0.md | Outstanding | +| eSignature | esignature_v2_0.md | Draft | +| Product Bundling | product-bundling_v2_0.md | Outstanding | diff --git a/layer-01/standard-decisions/README.md b/layer-01/standard-decisions/README.md new file mode 100644 index 0000000..142ca7c --- /dev/null +++ b/layer-01/standard-decisions/README.md @@ -0,0 +1,6 @@ +# Standard Decisions + +| File | Coverage | Status | +|------|----------|--------| +| standard-decisions_v2_0.md | NY exclusion, no replacements at P0, JIT contracting, Stripe, TX103 | Outstanding | +| codenames_v2_0.md | Project codename registry — active and retired | Outstanding | diff --git a/layer-02/README.md b/layer-02/README.md new file mode 100644 index 0000000..d9b15c1 --- /dev/null +++ b/layer-02/README.md @@ -0,0 +1,9 @@ +# Layer 02 — Product Contexts + +First stop when a new initiative begins. One folder per shipped product. + +| Product | Folder | Integration Model | PAS Model | Status | +|---------|--------|-------------------|-----------|--------| +| Sahara IUL | sahara-iul/ | Native | Carrier Administration | Outstanding | +| Beacon FE WL | beacon-fe-wl/ | Native | Ethos Administration | Outstanding | +| JH ROP Linkout | jh-rop-linkout/ | Linkout | N/A | Outstanding | diff --git a/layer-02/beacon-fe-wl/README.md b/layer-02/beacon-fe-wl/README.md new file mode 100644 index 0000000..f56079e --- /dev/null +++ b/layer-02/beacon-fe-wl/README.md @@ -0,0 +1,13 @@ +# Beacon FE WL — Product Context + +**Integration model:** Native | **PAS model:** Ethos Administration | **Product type:** Final Expense Whole Life + +Reference product for new FE WL carriers. Load this folder first. + +| File | Status | +|------|--------| +| master_context_v2_0.md | Outstanding | +| carrier_notes_v2_0.md | Outstanding | +| key_decisions_v2_0.md | Outstanding | +| lessons_learned_v2_0.md | Outstanding | +| product_performance_v2_0.md | Outstanding | diff --git a/layer-02/jh-rop-linkout/README.md b/layer-02/jh-rop-linkout/README.md new file mode 100644 index 0000000..0dc9a1b --- /dev/null +++ b/layer-02/jh-rop-linkout/README.md @@ -0,0 +1,13 @@ +# JH ROP Linkout — Product Context + +**Integration model:** Linkout | **PAS model:** N/A | **Product type:** Return of Premium Term + +Reference product for Linkout integrations. + +| File | Status | +|------|--------| +| master_context_v2_0.md | Outstanding | +| carrier_notes_v2_0.md | Outstanding | +| key_decisions_v2_0.md | Outstanding | +| lessons_learned_v2_0.md | Outstanding | +| product_performance_v2_0.md | Outstanding | diff --git a/layer-02/sahara-iul/README.md b/layer-02/sahara-iul/README.md new file mode 100644 index 0000000..173cb94 --- /dev/null +++ b/layer-02/sahara-iul/README.md @@ -0,0 +1,13 @@ +# Sahara IUL — Product Context + +**Integration model:** Native | **PAS model:** Carrier Administration | **Product type:** IUL + +Reference product for new IUL carriers. Load this folder first. + +| File | Status | +|------|--------| +| master_context_v2_0.md | Outstanding | +| carrier_notes_v2_0.md | Outstanding | +| key_decisions_v2_0.md | Outstanding | +| lessons_learned_v2_0.md | Outstanding | +| product_performance_v2_0.md | Outstanding | diff --git a/layer-03/README.md b/layer-03/README.md new file mode 100644 index 0000000..72c3a97 --- /dev/null +++ b/layer-03/README.md @@ -0,0 +1,11 @@ +# Layer 03 — Integration Playbooks + +Selected once product type is confirmed from Layer 02. + +| PAS Model | Folder | When to use | +|-----------|--------|-------------| +| Ethos Administration | native-ethos-admin/ | Term and WL. Ethos PAS owns all post-activation. Preferred. | +| Shadow Administration | native-shadow-admin/ | Same as Ethos Admin plus TX103 flows to carrier financials. | +| Carrier Administration | native-carrier-admin/ | IUL. TX103 submission; carrier owns post-activation. | +| Direct Admin Integration | native-direct-admin/ | Legacy — do not replicate. Reference only. | +| Linkout | linkout/ | Ethos owns quoting only. Carrier handles UW, application, policy admin. | diff --git a/layer-03/linkout/README.md b/layer-03/linkout/README.md new file mode 100644 index 0000000..50ccdb4 --- /dev/null +++ b/layer-03/linkout/README.md @@ -0,0 +1,11 @@ +# Linkout Integration Playbook + +**When to use:** Ethos owns quoting only. Carrier handles UW, application, and policy admin. +**PRD scope:** Quoting and URL param spec, attribution and analytics, inforce feed, commission feed. +**Example product:** JH ROP + +| File | Status | +|------|--------| +| playbook_v2_0.md | Outstanding | +| data-feed-architecture_v2_0.md | Outstanding | +| raci_v2_0.md | Outstanding | diff --git a/layer-03/native-carrier-admin/README.md b/layer-03/native-carrier-admin/README.md new file mode 100644 index 0000000..421fed4 --- /dev/null +++ b/layer-03/native-carrier-admin/README.md @@ -0,0 +1,9 @@ +# Native — Carrier Administration Playbook + +**When to use:** IUL. TX103 submission; carrier owns post-activation. Ethos ingests TX1203 and premium feeds. + +| File | Status | +|------|--------| +| playbook_v2_0.md | Outstanding | +| data-feed-architecture_v2_0.md | Outstanding | +| raci_v2_0.md | Outstanding | diff --git a/layer-03/native-direct-admin/README.md b/layer-03/native-direct-admin/README.md new file mode 100644 index 0000000..40188fc --- /dev/null +++ b/layer-03/native-direct-admin/README.md @@ -0,0 +1,7 @@ +# Native — Direct Admin Integration Playbook + +Legacy — do not replicate. Custom multi-feed pipeline, high maintenance. Reference only. + +| File | Status | +|------|--------| +| playbook_v2_0.md | Outstanding — reference only | diff --git a/layer-03/native-ethos-admin/README.md b/layer-03/native-ethos-admin/README.md new file mode 100644 index 0000000..00960a3 --- /dev/null +++ b/layer-03/native-ethos-admin/README.md @@ -0,0 +1,10 @@ +# Native — Ethos Administration Playbook + +**When to use:** Term and WL. Ethos PAS owns all post-activation. Preferred model. +**ACORD:** TX103 outbound, TX1203 inbound UW, TX111 cancellation. + +| File | Status | +|------|--------| +| playbook_v2_0.md | Outstanding | +| data-feed-architecture_v2_0.md | Outstanding | +| raci_v2_0.md | Outstanding | diff --git a/layer-03/native-shadow-admin/README.md b/layer-03/native-shadow-admin/README.md new file mode 100644 index 0000000..c6a329e --- /dev/null +++ b/layer-03/native-shadow-admin/README.md @@ -0,0 +1,9 @@ +# Native — Shadow Administration Playbook + +**When to use:** Same as Ethos Admin but TX103 also flows to carrier financials/actuarial. + +| File | Status | +|------|--------| +| playbook_v2_0.md | Outstanding | +| data-feed-architecture_v2_0.md | Outstanding | +| raci_v2_0.md | Outstanding | diff --git a/layer-04/README.md b/layer-04/README.md new file mode 100644 index 0000000..cceecef --- /dev/null +++ b/layer-04/README.md @@ -0,0 +1,56 @@ +# Layer 04 — Role Context + +Assembled by IPP, handed off before build begins. + +## Draft Child PRD roles (7) + +| Role | PRD | +|------|-----| +| Engineering | ERD Writer PRD | +| Compliance | TPA Controls PRD | +| Marketing / CX | Lifecycle Comms PRD | +| Underwriting | UW Foundations PRD | +| PRT | Agent Contracting PRD | +| Analytics | Analytics PRD | +| Policy Admin | PAS2 Implementation PRD | + +## Structured Brief roles (7) + +| Role | Brief | +|------|-------| +| Designer / UX | Agent Assisted App Experience brief | +| TPM | Project plan and stakeholder brief | +| Finance | Unit economics brief | +| Insurance Team | Product design and filing brief | +| Legal | TPA and carrier contract brief | +| Go-to-Market | CX, Sales and partner training brief | +| CX Ops | Error identification and escalation brief | + +## Core PRDs — all native products +1. Agent Assisted App Experience +2. Identity Verification (IDV) +3. UW Foundations +4. UW Refinement +5. Policy Admin — Pre Activation +6. Policy Admin — Post Activation +7. Agent Portal / Journey +8. Lifecycle / Marketing Comms +9. Agent Contracting and Appointments +10. Agent Comp System +11. Analytics +12. Compliance / TPA Controls +13. Data Feeds + +## Conditional PRDs + +| PRD | Trigger | +|-----|---------| +| Consumer (DTC) App Experience | If DTC in scope | +| Illustration | IUL only | +| Flexible Billing | If applicable | +| Post-Activation Increases | P1 — confirm before including | + +## Archived +| PRD | Note | +|-----|------| +| Claims | Explored in Beacon, not implemented. Do not include. | diff --git a/layer-05/README.md b/layer-05/README.md new file mode 100644 index 0000000..baa72d7 --- /dev/null +++ b/layer-05/README.md @@ -0,0 +1,31 @@ +# Layer 05 — PRD Templates + +Used by the PRD Writer once all upstream layers are loaded. + +| File | Description | Status | +|------|-------------|--------| +| master-prd-template_v2_0.md | Master PRD with standard sections and RACI scaffold | Outstanding | +| product-type-triggers_v2_0.md | Maps product type and PAS model to which child PRDs fire | Outstanding | +| context-template_v2_0.md | Filled post-launch to seed Layer 02 for the next product | Outstanding | + +## Child PRD Templates + +| Template | Role | +|----------|------| +| erd-writer_v2_0.md | Engineering | +| tpa-controls_v2_0.md | Compliance | +| lifecycle-comms_v2_0.md | Marketing / CX | +| uw-foundations_v2_0.md | Underwriting | +| uw-refinement_v2_0.md | Underwriting | +| agent-contracting_v2_0.md | PRT | +| analytics_v2_0.md | Analytics | +| policy-admin-pre-activation_v2_0.md | Policy Admin | +| policy-admin-post-activation_v2_0.md | Policy Admin | +| agent-portal_v2_0.md | Engineering / Product | +| agent-comp_v2_0.md | PRT / Finance | +| data-feeds_v2_0.md | Engineering | +| idv_v2_0.md | Engineering / Compliance | +| dtc-app-experience_v2_0.md | Conditional — DTC only | +| illustration_v2_0.md | Conditional — IUL only | +| flexible-billing_v2_0.md | Conditional — if applicable | +| post-activation-increases_v2_0.md | Conditional — P1, confirm before including | diff --git a/layer-05/child-prd-templates/.gitkeep b/layer-05/child-prd-templates/.gitkeep new file mode 100644 index 0000000..e69de29 From 2de4ddf8c32ae657ae40ef1bea88a91e0f48f97f Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Wed, 6 May 2026 15:17:45 +0530 Subject: [PATCH 2/5] feat: add L1 platform overviews for PCS and PRS (v2.0) --- layer-01/platform-systems/pcs_v2_0.md | 112 ++++++++++++++++++++++++++ layer-01/platform-systems/prs_v2_0.md | 105 ++++++++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 layer-01/platform-systems/pcs_v2_0.md create mode 100644 layer-01/platform-systems/prs_v2_0.md diff --git a/layer-01/platform-systems/pcs_v2_0.md b/layer-01/platform-systems/pcs_v2_0.md new file mode 100644 index 0000000..8ca5dea --- /dev/null +++ b/layer-01/platform-systems/pcs_v2_0.md @@ -0,0 +1,112 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: Product Configuration Service (PCS) +owner_product: IPP Product (Tanuj) +owner_engineering: MIC Engineering +last_updated: 2026-04-27 +status: active +source: Product_Configuration_PRD.md (Jon Ruelle, March 2023) + Ethos_Product_Configuration_Tables_Working_Document_v2.0 (Tanuj, active through April 2026) +template_version: 2.0 +--- + +# Product Configuration Service (PCS) + +## What it is + +PCS is the centralized, config-driven system that stores all product rules, parameters, and form assignments for every insurance product Ethos sells. It exists to replace scattered carrier-specific logic that was previously embedded across the main app monolith. The north star: adding a new product configuration populates a large amount of functionality in downstream systems automatically, without requiring code changes. PCS sits at the foundation of the Ethos platform — its outputs drive eligibility gating, quoting, underwriting routing, document generation, and ACORD transaction submission. + +## Ownership + +| Responsibility | Owner | Notes | +|---|---|---| +| Product requirements, configuration rules, and data maintenance | IPP Product (Tanuj) | Primary active maintainer of the working document | +| Build & maintenance of the PCS service | MIC Engineering | | +| Original PCS excel sheet author | Jon Ruelle | Created original PCS working document and founding PRD (March 2023) | + +## Inputs required + +| Input | Provided by | Notes | +|---|---|---| +| Carrier identity and NAIC code | Insurance Team / Carrier | NAIC code used as Carrier Code; Ameritas internal name must not be changed | +| Product type and market segment | IPP Product | Determines which PCS entities are required | +| UW method (IC / RUW / External / Guaranteed Issue) | Insurance Team / UW | Drives coverage configuration and eligibility rules | +| State approval dates | Insurance Team / Compliance | Required before State Approvals entity can be populated | +| Coverage parameters | Insurance Team / UW | Populates Coverage entity | +| Form assignments and form numbers | IPP Product + Compliance | Required to populate Forms and Form Control entities | +| Rate/PPU version identifiers | Insurance Team / Actuarial | Populates Product Variation and Investments entities | +| Channel assignments | IPP Product | Consumer / Partner / Recruit and Build | +| Eligibility rules | UW / Insurance Team | Populates Eligibility entity | + +## Outputs produced + +| Output | Destination | Notes | +|---|---|---| +| Coverage parameters and eligibility rules | Quoting engine + UW routing | Drives which products a customer is offered | +| Form assignments (via Form Control) | Document Generation Service | Determines which forms are included in each document packet | +| ACORD-mapped product data | TX103 submission pipeline | Carrier Code, Plan Name, Coverage Code flow into TX103 | +| State approval gates | Product routing / funnel | Controls which states a product is available | +| Investment/allocation options | IUL illustration and application | Monthly rate tables for IUL | +| Banding rules | Quoting engine | Face amount band definitions | +| Product Variation + PPU version | Pricing / rate tables | Links channel-specific coverage codes to correct rate version | + +## Product type variations + +| Product type | Behavior | Notes | +|---|---|---| +| Term — Native (Prime Model) | Full entity set | Primary product type in PCS; most mature configuration model | +| Whole Life — Native | Full entity set; no Investments entity | TruStage TAWL/GAWL and Banner SI/GI WL configured in PCS | +| IUL — Native (Carrier Admin) | Full entity set plus Investments entity | Monthly rate tables; updated every month | +| Linkout | Partial entity set | Ethos owns quoting only; form generation and policy admin are carrier-side | +| External UW products (TruStage) | Full entity set; Underwriting Method = External | Form handling differs from Prime Model products | +| Supplemental Health (Aflac Cancer) | Product, Carrier, Coverage, Eligibility, State Approvals, Forms, Form Control | First non-life product in PCS | +| Legacy products (ETP0001, ETP0004, ETP0005, ETP0006) | Present in PCS working document but NOT implemented using config | See Needs Validation | + +## Dependencies + +| System | Dependency type | Details | +|---|---|---| +| Document Generation Service | Downstream | Form Control entity defines which forms apply per product/state | +| TX103 submission pipeline | Downstream | ACORD-mapped PCS fields feed directly into TX103 | +| Quoting engine / product routing | Downstream | Coverage parameters and state approval gates drive quoting | +| IUL illustration engine | Downstream | Investments entity monthly rate tables consumed by illustration engine | +| PRS (Product Routing Service) | Adjacent | PCS/PRS boundary not yet fully defined — see Needs Validation | + +## Known constraints + +- **Ameritas carrier name must not be changed.** Internal Name `AMERITAS` in the Carrier entity — changing it causes a TX103 error. +- **Not all products are PCS-native.** Several legacy products remain implemented in the main app code base. +- **Form UUIDs must be unique.** Duplicate UUIDs have caused implementation issues on past products. +- **Compact state list is Form Control-driven, not Coverage-driven.** +- **Start/End dates are the versioning mechanism.** Overlapping or missing dates have caused production issues. +- **Monthly rate updates for IUL are high-frequency.** Ameritas Protection IUL is on its 96th+ monthly update as of April 2026. +- **TruStage products do not use the Compact state list for form control.** + +## Related PRD templates + +Product Builder workstream (Agent 10) is covered by the Product Builder child PRD in Layer 05. A dedicated PCS child PRD template does not yet exist — documented gap (Gap 5.5). + +--- + +## Needs Validation + +### P1 PRD Features — Not Confirmed as Implemented + +| # | Feature | PRD Description | Status | +|---|---------|-----------------|--------| +| NV-1 | Configuration UI | Interface for managing product/form configuration rules without editing the spreadsheet | Not confirmed — Hold | +| NV-2 | Rules hierarchy in UI | UI organizes rules using Entities, Objects, and Elements | Not confirmed — Hold | +| NV-3 | UI display format | When element has both code and value, displays as `() ` | Not confirmed — Hold | +| NV-4 | Spreadsheet export/import | Export and import product configuration file with error validation | Not confirmed — Hold | + +### PCS / PRS Boundary +The boundary between PCS routing logic (Eligibility / Coverage / State Approvals) and PRS as a separate system is not documented. Must be resolved before either platform overview is complete. + +### Legacy Products — PCS Presence vs. Implementation +ETP0001, ETP0004, ETP0005, ETP0006 appear in the PCS working document but carry the note "not implemented using config." Do not document as PCS-configured until confirmed. + +### Aflac Cancer — Active Status +Change Log (v1.85) notes Aflac Cancer content was removed August 2025 and re-added at v2.7 (November 2025). Confirm current production status before treating as fully active. + +### Downstream Dependency Map — Incomplete +Suspected but unconfirmed: PCS → PAS2, PCS → Agent Portal, PCS → Stripe/billing. diff --git a/layer-01/platform-systems/prs_v2_0.md b/layer-01/platform-systems/prs_v2_0.md new file mode 100644 index 0000000..b32748a --- /dev/null +++ b/layer-01/platform-systems/prs_v2_0.md @@ -0,0 +1,105 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: Product Routing Service (PRS) +owner_product: Pankaj Soni (IPP Product) +owner_engineering: Abhishek Singh, Shashwat Sahu, Lokesh Yadav (IPP Engineering / Microservices) +last_updated: 2026-04-24 +status: active +source: LLD, Tech Design, Runbook, Launch Plan, ERDs, Design Docs, Eligibility Criteria, Recommendation Rules CSVs — Apr 2024–Mar 2026 +template_version: 2.0 +file_version: v2.0 +--- + +# Product Routing Service (PRS) + +## What it is + +PRS is the central platform system responsible for determining which insurance product(s) a customer is eligible for and routing them to the correct product flow. PRS evaluates channel, age, TRL/PreQual score, state, citizenship status, verification results, prior policy history, underwriting outcomes, fraud flags, and carrier eligibility constraints against a versioned set of recommendation rules. It operates as a standalone microservice with its own Postgres database and replaced the Main App routing logic for the Consumer (DTC) channel. IDV is decoupled from PRS — PRS routes based on eligibility criteria only. + +## Ownership + +| Responsibility | Owner | Notes | +|---|---|---| +| Product requirements, routing rules, eligibility configuration | IPP Product (Pankaj Soni) | Routing rules authored in Google Sheet, ingested via data pipeline | +| Build, maintenance, deployment | IPP Engineering — Microservices | Abhishek Singh, Shashwat Sahu, Lokesh Yadav | +| Recommendation rules translation and pipeline | IPP Engineering | Engineering translates Product/Actuarial rules sheet into PRS config | +| Carrier eligibility API integrations | IPP Engineering | LGA eligibility API, Protective/Spirit coverage API, Choice PA status checks | +| Monitoring and incident response | IPP Engineering — Microservices | Datadog + PagerDuty via #product-routing-service-alerts | + +## Inputs required + +| Input | Provided by | Notes | +|---|---|---| +| Recommendation rules sheet (TRL/age/state/channel/citizenship matrix) | IPP Product / Actuarial | Google Sheet → CSV → Fivetran → Snowflake → Airflow → Postgres | +| Product eligibility configuration | IPP Product via PCS | PCS is source of truth for carrier-defined eligibility | +| Cross-product eligibility rules | IPP Product / Actuarial | Prior policy outcomes that render customer ineligible for other products | +| Product override configuration | IPP Product | Force-routing map with fallback sequence | +| Carrier eligibility API credentials | Carrier / IPP Engineering | LGA and Protective/Spirit real-time checks | +| PreQual / TRL score | Main App (passed as input) | Pre-calculated and passed in request DTO | +| Policy status data | Main App (passed as input) | Active / Decline / InProgress / Prior Rescinds by TaxID | +| Underwriting decisions | Main App (passed as input) | UW declined products by TaxID | +| Citizenship status, visa type, identification type | Profile Service | Read directly by PRS | + +## Outputs produced + +| Output | Destination | Notes | +|---|---|---| +| Routed product | Main App | First eligible product passing all eligibility gates | +| Ranked candidate product list | Main App | Ordered list before post-verification filtering | +| Product routing result record | PRS Postgres DB | Persisted for every decision; includes inputs_json and explainability data | +| Ineligibility reasons | PRS API + product_routing_results table | Per-product JSONB; queryable via `/api/v1/private/prs/get_ineligibility_reasons?policyId=` | +| Carrier eligibility results | PRS Postgres DB | Cached results from LGA and Protective/Spirit API calls | + +## Eligibility pipeline + +PRS evaluates eligibility in a fixed deterministic order: + +1. **Recommendation rules match** — filters to ranked candidate list by channel, age, TRL, state, citizenship +2. **Static eligibility filtering (PCS)** — age bands, state approvals, product variant mapping +3. **Verification results filtering** — IDV outcomes, fraud flags +4. **Cross-product rules** — prior policy history, UW cross-declines, prior rescind rules +5. **Carrier eligibility API checks** — real-time LGA, Protective/Spirit, Choice PA status +6. **Final routing decision** — first product passing all gates returned + +## Product type variations + +| Product type | Behavior | Notes | +|---|---|---| +| Term — Native | Full PRS pipeline | LGA, Protective/Spirit, Ameritas Choice, Ameritas SI each have distinct rules and carrier API calls | +| IUL — Native | Full PRS pipeline | IUL-specific age calculation; falls back to TAWL/GAWLN if ineligible | +| TruStage Native | PRS fallback/reroute products | No carrier API check required | +| Linkout | PRS not involved | Ethos owns quoting only; Linkout products bypass PRS entirely | +| Non-resident applicants | Citizenship dimension in recommendation rules | ITIN-based identity lookup; fallback TAWL → GAWLN | + +## Cross-product rules summary + +1. If ever declined for any Ethos product, do NOT route to Prime, Choice, SI, or IUL. +2. If declined for any non-TruStage product, TruStage products are still allowed. +3. If declined for TruStage SITL/TAWL, only route to GAWL, Beacon GI WL, or AD. + +## Active experiments (as of Apr 2026) + +| Experiment | Channel | Description | +|------------|---------|-------------| +| `spirit_launch` | Consumer | Spirit routed ahead of Prime for assigned cohort; Age 20–65, TRL 1–50 | +| `spirit_partnership_launch` | Partnership | Same as above for Partnership channel | + +--- + +## Needs Validation + +**NV-1 — IDV/DMV Service Platform Overview** +IDV is decoupled from PRS. A dedicated IDV L1 Platform Overview does not yet exist. Added to tracker as outstanding. + +**NV-2 — Protective eligibility API migration from IPS to PRS** +LGA eligibility is called directly via PRS. Protective (Spirit) coverage eligibility API migration from IPS to PRS direct is outstanding. + +**NV-3 — AuthN/AuthZ implementation** +PRS does not currently have authentication or authorization. No implementation timeline documented. + +**NV-4 — Direct PRS to Underwriting Service integration** +Long-term design calls for PRS to call Underwriting Service directly. Not yet implemented. + +**NV-5 — Prior decline data source** +PRS relies on prior decline data passed from Main App (which calls UW). Functional but remains a dependency on Main App as intermediary. From ceed0755489fa4a83e7d66506a4f39730f109dfd Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Wed, 6 May 2026 15:27:12 +0530 Subject: [PATCH 3/5] fix: replace PRS with exact source file content (v2.0) --- layer-01/platform-systems/prs_v2_0.md | 133 ++++++++++++++++++-------- 1 file changed, 94 insertions(+), 39 deletions(-) diff --git a/layer-01/platform-systems/prs_v2_0.md b/layer-01/platform-systems/prs_v2_0.md index b32748a..91d88d2 100644 --- a/layer-01/platform-systems/prs_v2_0.md +++ b/layer-01/platform-systems/prs_v2_0.md @@ -15,75 +15,130 @@ file_version: v2.0 ## What it is -PRS is the central platform system responsible for determining which insurance product(s) a customer is eligible for and routing them to the correct product flow. PRS evaluates channel, age, TRL/PreQual score, state, citizenship status, verification results, prior policy history, underwriting outcomes, fraud flags, and carrier eligibility constraints against a versioned set of recommendation rules. It operates as a standalone microservice with its own Postgres database and replaced the Main App routing logic for the Consumer (DTC) channel. IDV is decoupled from PRS — PRS routes based on eligibility criteria only. +The Product Routing Service (PRS) is the central platform system responsible for determining which insurance product(s) a customer is eligible for and routing them to the correct product flow. PRS makes this determination by evaluating a combination of customer attributes — including channel, age, TRL/PreQual score, state, citizenship status, verification results, prior policy history, underwriting outcomes, fraud flags, and carrier eligibility constraints — against a versioned set of recommendation rules and eligibility configurations. PRS is consumed by the Main App and is invoked at the product determination step of the application funnel. It operates as a standalone microservice with its own Postgres database and is independent of the Main App routing logic, which it replaced in production for the Consumer (DTC) channel. IDV (Identity Verification / DMV) is decoupled from PRS — PRS routes users based on eligibility criteria only and does not own or orchestrate identity verification. + +--- ## Ownership | Responsibility | Owner | Notes | |---|---|---| -| Product requirements, routing rules, eligibility configuration | IPP Product (Pankaj Soni) | Routing rules authored in Google Sheet, ingested via data pipeline | -| Build, maintenance, deployment | IPP Engineering — Microservices | Abhishek Singh, Shashwat Sahu, Lokesh Yadav | -| Recommendation rules translation and pipeline | IPP Engineering | Engineering translates Product/Actuarial rules sheet into PRS config | +| Product requirements, routing rules, eligibility configuration | IPP Product (Pankaj Soni) | Routing rules are authored in a Google Sheet maintained by Product/Actuarial and ingested into PRS via a data pipeline | +| Build, maintenance, deployment | IPP Engineering — Microservices Team | Abhishek Singh, Shashwat Sahu, Lokesh Yadav | +| Recommendation rules translation and pipeline | IPP Engineering | Engineering translates Product/Actuarial rules sheet into PRS config. See Inputs section. | | Carrier eligibility API integrations | IPP Engineering | LGA eligibility API, Protective/Spirit coverage API, Choice PA status checks | -| Monitoring and incident response | IPP Engineering — Microservices | Datadog + PagerDuty via #product-routing-service-alerts | +| Monitoring and incident response | IPP Engineering — Microservices | Datadog dashboards and PagerDuty alerts via #product-routing-service-alerts | + +**Ownership boundary:** IPP Product defines the routing rules, eligibility criteria, product priority order, and fallback logic in the recommendation rules Google Sheet. IPP Engineering translates those rules into PRS configuration, maintains the ingestion pipeline, and owns all carrier API integrations and service operations. + +--- ## Inputs required +The following must be defined, decided, or configured before PRS can route a new product. + | Input | Provided by | Notes | |---|---|---| -| Recommendation rules sheet (TRL/age/state/channel/citizenship matrix) | IPP Product / Actuarial | Google Sheet → CSV → Fivetran → Snowflake → Airflow → Postgres | -| Product eligibility configuration | IPP Product via PCS | PCS is source of truth for carrier-defined eligibility | -| Cross-product eligibility rules | IPP Product / Actuarial | Prior policy outcomes that render customer ineligible for other products | -| Product override configuration | IPP Product | Force-routing map with fallback sequence | -| Carrier eligibility API credentials | Carrier / IPP Engineering | LGA and Protective/Spirit real-time checks | -| PreQual / TRL score | Main App (passed as input) | Pre-calculated and passed in request DTO | -| Policy status data | Main App (passed as input) | Active / Decline / InProgress / Prior Rescinds by TaxID | -| Underwriting decisions | Main App (passed as input) | UW declined products by TaxID | -| Citizenship status, visa type, identification type | Profile Service | Read directly by PRS | +| Recommendation rules sheet (TRL/age/state/channel/citizenship matrix) | IPP Product / Actuarial | Google Sheet is the source of truth. Engineering ingests it via Python script → CSV → Fivetran → Snowflake → Airflow → Postgres. Any update requires a new versioned entry in the product_recommendation_rules table. | +| Product eligibility configuration (age bands, state approvals, productVariantId → productId mapping) | IPP Product via PCS | Product Configuration Service (PCS) is the source of truth for carrier-defined eligibility. PRS reads PCS config for age, state, and product code resolution. | +| Cross-product eligibility rules (UW cross-declines, prior rescind rules) | IPP Product / Actuarial | Defines which prior policy outcomes render a customer ineligible for other products. Provided in the recommendation rules sheet. | +| Product override configuration (override map + fallback product list in priority order) | IPP Product | Defines which products can be force-routed and their fallback sequence. Stored in the product_override_config table, versioned. | +| Carrier eligibility API credentials and endpoints (LGA, Protective/Spirit) | Carrier / IPP Engineering | Required for real-time carrier eligibility checks at the final step of the eligibility pipeline. | +| PreQual / TRL score | Main App (passed as input to PRS request) | Pre-calculated and passed from Main App to PRS in the request DTO. Not fetched by PRS directly. | +| Policy status data (Active / Decline / InProgress / Prior Rescinds by TaxID) | Main App (passed as input to PRS request) | Pre-calculated and passed from Main App. PRS does not call Main App to fetch this — previously a circular dependency, now resolved. | +| Underwriting decisions (UW declined products by TaxID) | Main App (passed as input to PRS request) | Pre-calculated and passed from Main App. | +| PA status data (for Ameritas products) | Main App (passed as input to PRS request) | Pre-calculated and passed from Main App. | +| Citizenship status, visa type, identification type (SSN/ITIN) | Profile Service | Read by PRS from Profile Service for non-resident routing. | + +--- ## Outputs produced | Output | Destination | Notes | |---|---|---| -| Routed product | Main App | First eligible product passing all eligibility gates | -| Ranked candidate product list | Main App | Ordered list before post-verification filtering | -| Product routing result record | PRS Postgres DB | Persisted for every decision; includes inputs_json and explainability data | -| Ineligibility reasons | PRS API + product_routing_results table | Per-product JSONB; queryable via `/api/v1/private/prs/get_ineligibility_reasons?policyId=` | -| Carrier eligibility results | PRS Postgres DB | Cached results from LGA and Protective/Spirit API calls | +| Routed product (single product or none) | Main App | The first eligible product in the recommendation list that passes all eligibility gates. Returned in the PRS API response. | +| Ranked candidate product list | Main App | Intermediate output: ordered list of products eligible per recommendation rules, before post-verification eligibility filtering. | +| Product routing result record | PRS Postgres DB (product_routing_results table) | Persisted for every routing decision. Includes inputs_json, routed product, and explainability data (JSONB column for ineligibility reasons per product). | +| Ineligibility reasons (Explainability) | PRS API (private endpoint) + product_routing_results table | Per-product ineligibility reason stored as JSONB. Queryable via `/api/v1/private/prs/get_ineligibility_reasons?policyId=`. Used for debugging and support. | +| Carrier eligibility results | PRS Postgres DB (carrier_eligibility_results table) | Cached results from carrier API calls (LGA, Protective/Spirit). | -## Eligibility pipeline +--- + +## How it's triggered in onboarding + +PRS is configured at **Agent 12 — Routing Config** in the IPP 17-agent onboarding workflow. At this step, IPP Product and Engineering configure: + +1. The recommendation rules for the new product in the Google Sheet (channel, age, TRL, state, citizenship matrix with product priority order and fallback sequence). +2. The product eligibility configuration in PCS (age bands, state approvals, productVariantId → productId mapping). +3. The carrier eligibility API integration in PRS (if the carrier requires a real-time API check at routing time — currently LGA and Protective/Spirit). +4. The product override configuration if the product supports forced routing. +5. A new versioned entry in the product_recommendation_rules table via the ingestion pipeline. -PRS evaluates eligibility in a fixed deterministic order: +**New product onboarding sequence for PRS:** +- Product/Actuarial provides the recommendation rules sheet for the new product. +- Engineering validates against the PCS eligibility tab and translates rules to PRS config. +- Engineering creates a new version in the active version tracker. +- Validation is run in staging against normal, edge, and negative cases. +- Version is promoted to production after QA sign-off. -1. **Recommendation rules match** — filters to ranked candidate list by channel, age, TRL, state, citizenship -2. **Static eligibility filtering (PCS)** — age bands, state approvals, product variant mapping -3. **Verification results filtering** — IDV outcomes, fraud flags -4. **Cross-product rules** — prior policy history, UW cross-declines, prior rescind rules -5. **Carrier eligibility API checks** — real-time LGA, Protective/Spirit, Choice PA status -6. **Final routing decision** — first product passing all gates returned +--- ## Product type variations | Product type | Behavior | Notes | |---|---|---| -| Term — Native | Full PRS pipeline | LGA, Protective/Spirit, Ameritas Choice, Ameritas SI each have distinct rules and carrier API calls | -| IUL — Native | Full PRS pipeline | IUL-specific age calculation; falls back to TAWL/GAWLN if ineligible | -| TruStage Native | PRS fallback/reroute products | No carrier API check required | -| Linkout | PRS not involved | Ethos owns quoting only; Linkout products bypass PRS entirely | -| Non-resident applicants | Citizenship dimension in recommendation rules | ITIN-based identity lookup; fallback TAWL → GAWLN | +| Term — Native (LGA Prime, Protective/Spirit, Ameritas Choice, Ameritas SI) | Full PRS pipeline: recommendation rules → verification → post-verification eligibility → carrier API check → routing decision | Each carrier has distinct eligibility rules and some require real-time carrier API calls. LGA requires LGA VerifyIdentity API. Protective/Spirit requires coverage API check. Choice requires PA status check. | +| IUL — Native (Ameritas IUL) | Full PRS pipeline. Routing criteria include IUL-specific age calculation (ageNearestBirthDateAmeritas). | IUL falls back to TAWL/GAWLN if ineligible. | +| TruStage Native (TAWLN, GAWLN, TSTERM) | PRS routes to TruStage products as fallback/reroute products in the DTC + Agency Admin flow. No carrier API check required. | TruStage products replaced TNU (deprecated). Non-resident fallback is TAWL → GAWLN. | +| Linkout | PRS is not involved. Ethos owns quoting only; no PAS model is configured. | Linkout products bypass PRS. | +| Non-resident applicants | Citizenship dimension added to recommendation rules. ITIN-based identity lookup supported. | Non-resident routing introduced a 5th dimension (citizenship) to the recommendation rules matrix. | + +--- + +## Eligibility pipeline + +PRS evaluates eligibility in a fixed deterministic order. The same inputs always produce the same output. + +**Step 1 — Recommendation rules match** +Filters the full product catalog to a ranked candidate list based on: channel, age, TRL/PreQual score, state, citizenship status. Source of truth is the versioned product_recommendation_rules table. Products not in the matched rule set are eliminated with reason `RemovedAfterRecommendationRule`. + +**Step 2 — Static eligibility filtering (PCS)** +Applies carrier-defined eligibility constraints from PCS: age bands, state approvals, productVariantId → productId mapping. Products failing PCS static checks are eliminated. + +**Step 3 — Verification results filtering** +Applies IDV and fraud flag outcomes. Products requiring identity verification that the applicant has not passed are eliminated. -## Cross-product rules summary +**Step 4 — Cross-product rules** +Applies prior policy history rules: UW cross-declines, prior rescind rules, active policy stacking rules. Products blocked by cross-product rules are eliminated with specific ineligibility reasons. + +**Step 5 — Carrier eligibility API checks** +For products requiring real-time carrier checks (LGA, Protective/Spirit): calls carrier eligibility API. Results are cached in carrier_eligibility_results table. + +**Step 6 — Final routing decision** +Returns the first product in the ranked list that passed all prior gates. If no product passes, returns no routed product with ineligibility reasons per product. + +--- + +## Cross-product rules summary (plain language) 1. If ever declined for any Ethos product, do NOT route to Prime, Choice, SI, or IUL. -2. If declined for any non-TruStage product, TruStage products are still allowed. -3. If declined for TruStage SITL/TAWL, only route to GAWL, Beacon GI WL, or AD. +2. If declined for any non-TruStage/non-Beacon product, TruStage and Beacon products are still allowed. +3. If declined for TruStage SITL/TAWL or Beacon SI WL, only route to GAWL, Beacon GI WL, or AD. + +--- ## Active experiments (as of Apr 2026) | Experiment | Channel | Description | -|------------|---------|-------------| -| `spirit_launch` | Consumer | Spirit routed ahead of Prime for assigned cohort; Age 20–65, TRL 1–50 | -| `spirit_partnership_launch` | Partnership | Same as above for Partnership channel | +|---|---|---| +| `spirit_launch` | Consumer | Spirit routed ahead of Prime for assigned cohort. Age 20–65, TRL 1–50. | +| `spirit_partnership_launch` | Partnership | Same structure for Partnership channel. | + +--- + +## Prior decline re-underwrite feature (confirmed live) + +Non-disclosure evidence declines (where the applicant did not disclose a condition that was later found via evidence) are eligible for re-underwrite. Disclosure-rule declines and unknowns continue to be blocked. 30-day gate confirmed for same-application scenarios. --- @@ -93,7 +148,7 @@ PRS evaluates eligibility in a fixed deterministic order: IDV is decoupled from PRS. A dedicated IDV L1 Platform Overview does not yet exist. Added to tracker as outstanding. **NV-2 — Protective eligibility API migration from IPS to PRS** -LGA eligibility is called directly via PRS. Protective (Spirit) coverage eligibility API migration from IPS to PRS direct is outstanding. +LGA eligibility is already called directly via PRS. Protective (Spirit) coverage eligibility API migration from IPS to PRS direct is outstanding. **NV-3 — AuthN/AuthZ implementation** PRS does not currently have authentication or authorization. No implementation timeline documented. From 6a6be45b556b27014cd7cf74e775fd8fd42663a7 Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Wed, 6 May 2026 15:34:39 +0530 Subject: [PATCH 4/5] feat: add exact L1 platform overviews for PCS and PRS v2.0 --- layer-01/platform-systems/pcs_v2_0.md | 150 ++++++--- layer-01/platform-systems/prs_v2_0.md | 439 ++++++++++++++++++++++++-- 2 files changed, 515 insertions(+), 74 deletions(-) diff --git a/layer-01/platform-systems/pcs_v2_0.md b/layer-01/platform-systems/pcs_v2_0.md index 8ca5dea..d328899 100644 --- a/layer-01/platform-systems/pcs_v2_0.md +++ b/layer-01/platform-systems/pcs_v2_0.md @@ -14,99 +14,157 @@ template_version: 2.0 ## What it is -PCS is the centralized, config-driven system that stores all product rules, parameters, and form assignments for every insurance product Ethos sells. It exists to replace scattered carrier-specific logic that was previously embedded across the main app monolith. The north star: adding a new product configuration populates a large amount of functionality in downstream systems automatically, without requiring code changes. PCS sits at the foundation of the Ethos platform — its outputs drive eligibility gating, quoting, underwriting routing, document generation, and ACORD transaction submission. +PCS is the centralized, config-driven system that stores all product rules, parameters, and form assignments for every insurance product Ethos sells. It exists to replace scattered carrier-specific logic (`isLgaTerm`, `isAmeritasSI`, and similar flags) that was previously embedded across the main app monolith's shared-utilities layer. The north star: adding a new product configuration populates a large amount of functionality in downstream systems automatically, without requiring code changes. PCS sits at the foundation of the Ethos platform — its outputs drive eligibility gating, quoting, underwriting routing, document generation, and ACORD transaction submission. Every entity in PCS is mapped to ACORD elements wherever applicable, enabling clean downstream TX103 and other transaction generation. ## Ownership | Responsibility | Owner | Notes | |---|---|---| -| Product requirements, configuration rules, and data maintenance | IPP Product (Tanuj) | Primary active maintainer of the working document | +| Product requirements, configuration rules, and data maintenance | IPP Product (Tanuj) | Tanuj is the primary active maintainer of the working document; all configuration changes since early 2024 are authored by Tanuj | | Build & maintenance of the PCS service | MIC Engineering | | -| Original PCS excel sheet author | Jon Ruelle | Created original PCS working document and founding PRD (March 2023) | +| Original PCS excel sheet author | Jon Ruelle | Created the original PCS working document and founding PRD (March 2023); transitioned ongoing maintenance to Tanuj | + +> Ownership boundary: IPP Product defines what belongs in each configuration entity — which products exist, which coverages are valid in which states, which forms apply, what eligibility rules govern each product variation. MIC Engineering owns the service infrastructure that reads those configurations and exposes them to downstream systems. IPP Product does not require an engineering deploy to update most configuration data. ## Inputs required +Before PCS can be configured for a new product, the following must be defined and provided: + | Input | Provided by | Notes | |---|---|---| -| Carrier identity and NAIC code | Insurance Team / Carrier | NAIC code used as Carrier Code; Ameritas internal name must not be changed | -| Product type and market segment | IPP Product | Determines which PCS entities are required | +| Carrier identity and NAIC code | Insurance Team / Carrier | NAIC code used as Carrier Code; Ameritas internal name must not be changed — doing so causes a TX103 error | +| Product type and market segment | IPP Product | Determines which PCS entities are required (e.g., Investments entity is IUL-only) | | UW method (IC / RUW / External / Guaranteed Issue) | Insurance Team / UW | Drives coverage configuration and eligibility rules | -| State approval dates | Insurance Team / Compliance | Required before State Approvals entity can be populated | -| Coverage parameters | Insurance Team / UW | Populates Coverage entity | -| Form assignments and form numbers | IPP Product + Compliance | Required to populate Forms and Form Control entities | -| Rate/PPU version identifiers | Insurance Team / Actuarial | Populates Product Variation and Investments entities | -| Channel assignments | IPP Product | Consumer / Partner / Recruit and Build | -| Eligibility rules | UW / Insurance Team | Populates Eligibility entity | +| State approval dates | Insurance Team / Compliance | Required before State Approvals entity can be populated; determines which states a product can be sold in and when | +| Coverage parameters (face amount ranges, issue age bands, health classes, tobacco basis) | Insurance Team / UW | Populates Coverage entity | +| Form assignments and form numbers | IPP Product + Compliance | Required to populate Forms and Form Control entities; forms must have DocuSign template links and UUIDs | +| Rate/PPU version identifiers | Insurance Team / Actuarial | Populates Product Variation and (for IUL) Investments entities | +| Channel assignments (Consumer / Partner / Recruit and Build) | IPP Product | Determines which Product Variations are created | +| Eligibility rules (TRL score ranges, citizenship status, visa types, identification type) | UW / Insurance Team | Populates Eligibility entity | ## Outputs produced +PCS produces a structured configuration payload consumed by multiple downstream systems: + | Output | Destination | Notes | |---|---|---| -| Coverage parameters and eligibility rules | Quoting engine + UW routing | Drives which products a customer is offered | -| Form assignments (via Form Control) | Document Generation Service | Determines which forms are included in each document packet | -| ACORD-mapped product data | TX103 submission pipeline | Carrier Code, Plan Name, Coverage Code flow into TX103 | -| State approval gates | Product routing / funnel | Controls which states a product is available | -| Investment/allocation options | IUL illustration and application | Monthly rate tables for IUL | -| Banding rules | Quoting engine | Face amount band definitions | -| Product Variation + PPU version | Pricing / rate tables | Links channel-specific coverage codes to correct rate version | +| Coverage parameters and eligibility rules | Quoting engine + UW routing | Drives which products a customer is offered and what face amounts / terms are available | +| Form assignments (via Form Control) | Document Generation Service | Determines which forms are included in each document packet (authorization, application, policy combined) for a given product/state combination | +| ACORD-mapped product data | TX103 submission pipeline | Carrier Code (`@CarrierCode`), Plan Name (`@PlanName`), Coverage Code (`@ProductCode`), and other ACORD elements flow directly into TX103 and related transactions | +| State approval gates | Product routing / funnel | Controls which states a product is available for sale on any given date | +| Investment/allocation options | IUL illustration and application | IUL-specific; monthly rate tables (cap, participation rate, floor, spread) consumed by the illustration engine and presented in the application | +| Banding rules | Quoting engine | Face amount band definitions used for pricing lookups | +| Product Variation + PPU version | Pricing / rate tables | Links channel-specific coverage codes to the correct rate version | + +## How it's triggered in onboarding + +PCS configuration is part of the **Product Builder** workstream (Agent 10 in the IPP 17-agent framework). This is the step where app & policy docs and config rules are assembled. Configuration of PCS for a new product requires IPP Product to populate all relevant entities in the working document and coordinate with IPP Engineering to load the configuration into the service. + +The typical onboarding sequence for PCS: + +1. Carrier entity is confirmed or added (NAIC code, internal name, internal code) +2. Product entity is created (product code, market, type, UW method, payment modes) +3. State Approvals are populated as approval dates are received from Compliance +4. Coverage entity is built out per health class, age band, tobacco basis, and state variation +5. Eligibility rules are defined per product variation and channel +6. Banding is configured if the product uses face amount bands for pricing +7. Form Control configs are created or assigned; Forms entity is populated with all required forms, UUIDs, and priorities +8. Product Variation entity is built per channel (Consumer, Partner, Recruit and Build) with coverage codes and PPU versions +9. For IUL products: Investments entity is populated with initial rate tables + +> Note: The Agent 10 / onboarding trigger mapping is not yet confirmed against the current IPP agent framework. See Needs Validation. ## Product type variations | Product type | Behavior | Notes | |---|---|---| -| Term — Native (Prime Model) | Full entity set | Primary product type in PCS; most mature configuration model | -| Whole Life — Native | Full entity set; no Investments entity | TruStage TAWL/GAWL and Banner SI/GI WL configured in PCS | -| IUL — Native (Carrier Admin) | Full entity set plus Investments entity | Monthly rate tables; updated every month | -| Linkout | Partial entity set | Ethos owns quoting only; form generation and policy admin are carrier-side | -| External UW products (TruStage) | Full entity set; Underwriting Method = External | Form handling differs from Prime Model products | -| Supplemental Health (Aflac Cancer) | Product, Carrier, Coverage, Eligibility, State Approvals, Forms, Form Control | First non-life product in PCS | +| Term — Native (Prime Model) | Full entity set: Product, Carrier, Coverage, Eligibility, Banding, State Approvals, Forms, Form Control, Product Variation | Primary product type in PCS; most mature configuration model | +| Whole Life — Native | Full entity set; no Investments entity | TruStage TAWL/GAWL and Banner SI/GI WL are configured in PCS | +| IUL — Native (Carrier Admin) | Full entity set plus Investments entity | Investments entity is IUL-exclusive; holds monthly rate tables with start/stop dates. Ameritas Protection IUL and North American Accumulation IUL (Sahara) are both configured in PCS | +| Linkout | Partial — Product, Carrier, Coverage, State Approvals, Product Variation only | John Hancock (now expired) was configured this way. Ethos owns quoting only; form generation and policy admin are carrier-side. Form Control and Forms entities are minimal or unused | +| External UW products (TruStage) | Full entity set; Underwriting Method = External | TruStage products use External UW method; form handling differs from Prime Model products | +| Supplemental Health (Aflac Cancer) | Product, Carrier, Coverage, Eligibility, State Approvals, Forms, Form Control | Non-life product type; first non-life product in PCS | | Legacy products (ETP0001, ETP0004, ETP0005, ETP0006) | Present in PCS working document but NOT implemented using config | See Needs Validation | ## Dependencies | System | Dependency type | Details | |---|---|---| -| Document Generation Service | Downstream | Form Control entity defines which forms apply per product/state | -| TX103 submission pipeline | Downstream | ACORD-mapped PCS fields feed directly into TX103 | -| Quoting engine / product routing | Downstream | Coverage parameters and state approval gates drive quoting | -| IUL illustration engine | Downstream | Investments entity monthly rate tables consumed by illustration engine | -| PRS (Product Routing Service) | Adjacent | PCS/PRS boundary not yet fully defined — see Needs Validation | +| Document Generation Service | Downstream — consumes PCS Form Control + Forms output | Form Control entity defines which forms apply per product/state; Forms entity provides form numbers, UUIDs, packet assignments, and start/end dates | +| TX103 submission pipeline | Downstream — consumes ACORD-mapped PCS fields | Carrier Code, Plan Name, Coverage Code, and other ACORD elements from PCS feed directly into TX103 and related ACORD transactions. Ameritas carrier internal name in PCS must not be changed — a name mismatch causes a TX103 error | +| Quoting engine / product routing | Downstream — consumes Coverage, Eligibility, Banding, State Approvals | Coverage parameters (face amount ranges, issue ages, health classes) and state approval gates drive what is shown to a customer at quote time | +| IUL illustration engine | Downstream — consumes Investments entity | Monthly rate tables (cap rates, participation rates, floor/spread) from the Investments entity are consumed by the illustration engine. IUL-only dependency | +| Main app / monolith (legacy) | Predecessor — PCS replaces embedded logic | Prior to PCS, product rules were hardcoded as carrier-specific flags (`isLgaTerm`, `isAmeritasSI`) in shared-utilities. PCS migration is ongoing — not all products have been fully migrated | +| PRS (Product Routing Service) | Adjacent — boundary not yet defined | PRS handles applicant routing to products. The boundary between PCS configuration data and PRS routing logic is not yet documented. See Needs Validation | ## Known constraints -- **Ameritas carrier name must not be changed.** Internal Name `AMERITAS` in the Carrier entity — changing it causes a TX103 error. -- **Not all products are PCS-native.** Several legacy products remain implemented in the main app code base. -- **Form UUIDs must be unique.** Duplicate UUIDs have caused implementation issues on past products. -- **Compact state list is Form Control-driven, not Coverage-driven.** -- **Start/End dates are the versioning mechanism.** Overlapping or missing dates have caused production issues. -- **Monthly rate updates for IUL are high-frequency.** Ameritas Protection IUL is on its 96th+ monthly update as of April 2026. -- **TruStage products do not use the Compact state list for form control.** +**Ameritas carrier name must not be changed.** The Internal Name field for Ameritas in the Carrier entity is `AMERITAS`. Changing this value causes a TX103 error. This is noted directly in the working document config notes. + +**Not all products are PCS-native.** Several legacy products appear in the PCS working document but remain implemented in the main app code base. Coverage rows for these products carry the note "Need to verify eligibility, legacy product, not implemented using config." Do not assume a product is PCS-driven simply because it appears in the working document. See Needs Validation for the confirmed legacy list. + +**Form UUIDs must be unique.** The Form Key field (DocuSign template ID) must be unique across all forms. The PRD specifies that loading a non-unique value must produce an error. Duplicate UUIDs have caused implementation issues on past products. + +**Compact state list is Form Control-driven, not Coverage-driven.** Which states qualify as "Compact" for a given product is defined in the Form Control entity's Compact State List — not directly in Coverage. This distinction matters when configuring state-specific form variations. + +**Start/End dates are the mechanism for versioning.** PCS does not use a separate version record to manage rate changes or form transitions. Instead, rows are time-bounded using Start Date and End Date fields. Overlapping or missing dates on coverage or form rows have caused production issues on past products. + +**Monthly rate updates for IUL are high-frequency.** The Investments entity for IUL products is updated every month. As of April 2026, the Ameritas Protection IUL is on its 96th+ monthly update (v1.96 of the working doc) and the North American Accumulation IUL (Sahara) has received updates since launch in October 2025. Rate update errors in this entity directly affect illustration accuracy. + +**Product Variation / PPU version coupling.** Coverage codes and PPU versions are tightly coupled through the Product Variation entity. Repricing a product requires new Product Variation rows with new coverage codes and PPU versions — it does not update existing rows in place. + +**TruStage products do not use the Compact state list for form control.** The working document notes explicitly: "Will not use compact states list due to how they handle Secondary Addressee." TruStage form assignments are handled differently from all other products. ## Related PRD templates -Product Builder workstream (Agent 10) is covered by the Product Builder child PRD in Layer 05. A dedicated PCS child PRD template does not yet exist — documented gap (Gap 5.5). +The Product Builder workstream (which owns PCS configuration) is covered by the **Product Builder child PRD** in Layer 05. A dedicated PCS child PRD template does not yet exist — this is a documented gap (Gap 5.5 in the evaluation log). The founding design spec is `Product_Configuration_PRD.md` (Jon Ruelle, March 2023). --- ## Needs Validation +> Items in this section are unconfirmed, planned-but-not-implemented, or P1 from the PRD. Do not promote to the main content above without explicit confirmation. + ### P1 PRD Features — Not Confirmed as Implemented +The following were specified as P1 in the founding PRD (March 2023). Per IPP standard, P1 items are commonly deferred. All four are held here pending confirmation. + | # | Feature | PRD Description | Status | |---|---------|-----------------|--------| -| NV-1 | Configuration UI | Interface for managing product/form configuration rules without editing the spreadsheet | Not confirmed — Hold | -| NV-2 | Rules hierarchy in UI | UI organizes rules using Entities, Objects, and Elements | Not confirmed — Hold | -| NV-3 | UI display format | When element has both code and value, displays as `() ` | Not confirmed — Hold | -| NV-4 | Spreadsheet export/import | Export and import product configuration file with error validation | Not confirmed — Hold | +| NV-1 | Configuration UI | An interface (similar to the Question Authoring tool) for managing product and form configuration rules without editing the spreadsheet directly | Not confirmed — Hold | +| NV-2 | Rules hierarchy in UI | UI organizes rules using Entities (#), Objects, and Elements (@) — a structured browsing/editing experience | Not confirmed — Hold | +| NV-3 | UI display format | When an element has both a code and a value, the UI displays it as `() ` | Not confirmed — Hold | +| NV-4 | Spreadsheet export/import | Ability to export and import a product configuration file into/out of a spreadsheet template, with error validation on import | Not confirmed — Hold | -### PCS / PRS Boundary -The boundary between PCS routing logic (Eligibility / Coverage / State Approvals) and PRS as a separate system is not documented. Must be resolved before either platform overview is complete. +### Onboarding Trigger — Agent Framework Mapping + +The mapping of PCS configuration work to a specific IPP agent (Agent 10 "Product Builder") is inferred from the agent's description in the IPP Framework v7. This has not been explicitly confirmed against the current agent framework definition. ### Legacy Products — PCS Presence vs. Implementation -ETP0001, ETP0004, ETP0005, ETP0006 appear in the PCS working document but carry the note "not implemented using config." Do not document as PCS-configured until confirmed. + +The following products appear in the PCS working document but carry the note "not implemented using config" on their Coverage rows. Their configuration may still live in the main app code base. Do not document these as PCS-configured until confirmed: + +- ETP0001 — Ameritas Simplified Issue Term +- ETP0004 — Simplified Issue Whole Life +- ETP0005 — Guaranteed Issue Whole Life +- ETP0006 — Guaranteed Insurance Whole Life + +### PCS / PRS Boundary + +The boundary between PCS (product configuration) and PRS (Product Routing Service) is not documented. It is unclear which routing logic lives in PCS (via Eligibility / Coverage / State Approvals entities) versus in PRS as a separate system. This gap must be resolved before either platform overview can be considered complete. + +### Product Determination Entity + +The founding PRD described a `#ProductDetermination` entity that would route applicants to the correct product based on age and TRL score. The PRD explicitly noted "additional analysis required." This entity does not appear in the current working document. It is unclear whether this routing logic was implemented as a PCS entity, implemented elsewhere, or deferred entirely. ### Aflac Cancer — Active Status -Change Log (v1.85) notes Aflac Cancer content was removed August 2025 and re-added at v2.7 (November 2025). Confirm current production status before treating as fully active. + +The Change Log (v1.85) notes Aflac Cancer content was removed from the working document on August 6, 2025 and moved to a separate stage PCS sheet, then re-added at v2.7 (November 2025). Current production status of Aflac Cancer in PCS should be confirmed before documenting it as a fully active product in the product type variations table above. ### Downstream Dependency Map — Incomplete -Suspected but unconfirmed: PCS → PAS2, PCS → Agent Portal, PCS → Stripe/billing. + +The dependencies documented above reflect what is visible from the working document and PRD. The following downstream connections are suspected but not confirmed: + +- PCS → PAS2 (policy admin): whether Coverage/State Approval data flows to PAS2 or is managed separately +- PCS → Agent Portal: whether product availability gating in the agent portal reads from PCS directly or from a downstream system +- PCS → Stripe / billing: whether payment mode configuration in PCS feeds billing setup diff --git a/layer-01/platform-systems/prs_v2_0.md b/layer-01/platform-systems/prs_v2_0.md index 91d88d2..e8e0c5c 100644 --- a/layer-01/platform-systems/prs_v2_0.md +++ b/layer-01/platform-systems/prs_v2_0.md @@ -89,9 +89,9 @@ PRS is configured at **Agent 12 — Routing Config** in the IPP 17-agent onboard |---|---|---| | Term — Native (LGA Prime, Protective/Spirit, Ameritas Choice, Ameritas SI) | Full PRS pipeline: recommendation rules → verification → post-verification eligibility → carrier API check → routing decision | Each carrier has distinct eligibility rules and some require real-time carrier API calls. LGA requires LGA VerifyIdentity API. Protective/Spirit requires coverage API check. Choice requires PA status check. | | IUL — Native (Ameritas IUL) | Full PRS pipeline. Routing criteria include IUL-specific age calculation (ageNearestBirthDateAmeritas). | IUL falls back to TAWL/GAWLN if ineligible. | -| TruStage Native (TAWLN, GAWLN, TSTERM) | PRS routes to TruStage products as fallback/reroute products in the DTC + Agency Admin flow. No carrier API check required. | TruStage products replaced TNU (deprecated). Non-resident fallback is TAWL → GAWLN. | +| TruStage Native (TAWLN, GAWLN, TSTERM) | PRS routes to TruStage products as fallback/reroute products in the DTC + Agency Admin flow. No carrier API check required. | TruStage products replaced TNU (deprecated). Non-resident fallback is TAWL → GAWLN. For non-residents in AA flow with Choice as initial product, TAWL is offered (TSTERM not eligible for non-residents). | | Linkout | PRS is not involved. Ethos owns quoting only; no PAS model is configured. | Linkout products bypass PRS. | -| Non-resident applicants | Citizenship dimension added to recommendation rules. ITIN-based identity lookup supported. | Non-resident routing introduced a 5th dimension (citizenship) to the recommendation rules matrix. | +| Non-resident applicants | Citizenship dimension added to recommendation rules. ITIN-based identity lookup supported. Fallback products are TAWL → GAWLN (TNU fully removed from non-resident flows). | Non-resident routing introduced a 5th dimension (citizenship) to the recommendation rules matrix. | --- @@ -103,58 +103,441 @@ PRS evaluates eligibility in a fixed deterministic order. The same inputs always Filters the full product catalog to a ranked candidate list based on: channel, age, TRL/PreQual score, state, citizenship status. Source of truth is the versioned product_recommendation_rules table. Products not in the matched rule set are eliminated with reason `RemovedAfterRecommendationRule`. **Step 2 — Static eligibility filtering (PCS)** -Applies carrier-defined eligibility constraints from PCS: age bands, state approvals, productVariantId → productId mapping. Products failing PCS static checks are eliminated. +Applies carrier-defined eligibility from PCS: citizenship status, visa type, identification type, document type, age bands, state approvals. Products failing these checks are eliminated with the corresponding IneligibilityReason (e.g., `AgeIneligible`, `StateIneligible`, `CitizenshipStatusIneligible`). -**Step 3 — Verification results filtering** -Applies IDV and fraud flag outcomes. Products requiring identity verification that the applicant has not passed are eliminated. +**Step 3 — Force remove / product override** +If the request specifies products to exclude (`ForceRemovedProduct`) or a product override, PRS applies the override configuration at this step. Override products bypass recommendation rules and use the product_override_config table instead. -**Step 4 — Cross-product rules** -Applies prior policy history rules: UW cross-declines, prior rescind rules, active policy stacking rules. Products blocked by cross-product rules are eliminated with specific ineligibility reasons. +**Step 4 — UW and cross-product eligibility** +Removes products where the customer has prior UW declines or is cross-ineligible (e.g., if declined for Ameritas SI, also ineligible for Ameritas Choice without re-running UW). Reason: `UwDeclinedOrUwIneligibleProduct` or `CrossIneligibleProduct`. -**Step 5 — Carrier eligibility API checks** -For products requiring real-time carrier checks (LGA, Protective/Spirit): calls carrier eligibility API. Results are cached in carrier_eligibility_results table. +**Step 5 — User and carrier eligibility checks** +Database-based checks: active/declined/in-progress/prior rescind policy history, PA status (Ameritas products), fraud flag, agent contracting status (AA flow). Reason: `FailedUserAndCarrierEligibilityCheck`, `IneligibleAgentContract`. -**Step 6 — Final routing decision** -Returns the first product in the ranked list that passed all prior gates. If no product passes, returns no routed product with ineligibility reasons per product. +**Step 6 — Carrier API eligibility (final gate)** +For products requiring a real-time carrier check (LGA, Protective/Spirit): calls carrier eligibility API. If carrier returns ineligible, product is removed and routing falls back to the next eligible product. If carrier API is down, fallback behavior applies (see Known Constraints). Reason: `CarrierEligibilityCallIneligible`. + +**Step 7 — Routing decision** +The first product in the ranked list that has passed all prior steps is returned as the routed product. If a product override was requested, the override product is returned if it passes all eligibility gates; otherwise the next eligible fallback product is returned. If no product qualifies, no product is returned. --- -## Cross-product rules summary (plain language) +## Age calculation -1. If ever declined for any Ethos product, do NOT route to Prime, Choice, SI, or IUL. -2. If declined for any non-TruStage/non-Beacon product, TruStage and Beacon products are still allowed. -3. If declined for TruStage SITL/TAWL or Beacon SI WL, only route to GAWL, Beacon GI WL, or AD. +Age calculation in PRS is handled by a centralized age calculation library shared across platform services. Each carrier uses a different age calculation method defined by their underwriting rules: + +| Method | Used for | Behavior | +|---|---|---| +| `ageNearestBirthDate` | Choice (Ameritas), SI (Ameritas), TruStage | Rounds to nearest year. Rounds up if next birthday is within 6 months. | +| `ageNearestBirthDateAmeritas` | IUL (Ameritas) | Uses Ameritas-specific rounding: subtracts 182/183 days depending on year length. | +| `ageNearestBirthDateLGA` | Term (LGA Prime) | Follows LGA-specific rounding rules per LGA alignment spreadsheet. | +| `ageNearestBirthDateProtective` | Term (Protective/Spirit) | Age Nearest Birthday per Protective Life rules. | +| `ageFromBirthDate` | Quoter only | Standard calendar age. Not used in product determination. | + +--- + +## Product override support + +PRS supports forced product routing via a product override request parameter. Approach 4 (finalized) uses a product override map table: + +- The override map defines the overridden product and its ordered fallback products. +- The table is versioned so returning users with an in-progress application continue on the version active when they started. +- PRS fetches eligible products from PCS for carrier eligibility (age, TRL for LGA, state), filters out ineligible/in-progress products, intersects with the override map, then runs the full final eligibility checks on the intersected list. +- Stacking between LGA and Protective/Spirit is supported via a `stacking=true` query parameter, which skips the cross-product issuance check for those two carriers only. + +**Current override fallback examples:** +| Overridden Product | Fallback Sequence | +|---|---| +| Choice (ID 14) | TNU → (deprecated, now TAWL) | +| LGA Term (ID 1) | Spirit, TAWL | + +--- + +## Recommendation rules pipeline + +The recommendation rules Google Sheet is the source of truth for all routing decisions. The pipeline to load rules into PRS: + +1. Product/Actuarial updates the Google Sheet. +2. Engineering runs the Python translation script (`product_recommendations_generate_sf_raw_csv.py`) to generate a CSV per channel. +3. CSV is uploaded to Google Drive and synced to Snowflake via Fivetran. +4. Airflow DAG (`product_routing_data_load_dag`) loads the new version into the Postgres `product_recommendation` table. +5. PRS consumes the new version for new users. Existing in-progress users continue on their version. + +**Rollback:** Controlled via an environment variable (Doppler) pointing to the active recommendation rules version. Rollback = revert the env variable to the prior version via ArgoCD or infra change. + +**Rule sheet structure:** Multiple CSV tabs by channel (Consumer, Partnership, Consumer Experimentation, Partnership Experimentation without TNU, Cross-product Rules, Product Override Config, Summary). + +--- + +## Explainability + +PRS stores a per-product ineligibility reason for every routing decision in the `explanation_tracker` column (JSONB) of the `product_routing_results` table. This enables debugging, support, and analytics without requiring PRS engineering involvement. + +**IneligibilityReasons tracked:** + +| Reason | Description | +|---|---| +| `VisaTypeIneligible` | User's visa type not supported for this product | +| `CitizenshipStatusIneligible` | Citizenship status not supported | +| `IdentificationTypeIneligible` | ITIN provided where only SSN accepted | +| `DocumentTypeIneligible` | Document type not supported | +| `AgeIneligible` | Age outside product age band | +| `StateIneligible` | State not approved for this product | +| `PreQualScoreIneligible` | TRL score below product threshold | +| `ForceRemovedProduct` | Product explicitly excluded by caller | +| `UwDeclinedOrUwIneligibleProduct` | Prior UW decline for this product | +| `CrossIneligibleProduct` | Cross-product ineligibility rule applied | +| `IneligibleAgentContract` | Agent not contracted to sell this carrier (AA flow) | +| `FailedUserAndCarrierEligibilityCheck` | Failed database-based user/carrier eligibility check | +| `RemovedAfterRecommendationRule` | Product not in matched recommendation rule set | +| `Spirit5MCoverageExceeding` | Customer's total Protective/Spirit coverage ≥ $5M | +| `RemovedAfterProductOverrideRule` | All other products excluded due to product override | +| `CarrierEligibilityCallIneligible` | Carrier API returned ineligible | + +**Note:** Products not routed through PRS (MOO_AD, John Hancock, John Hancock ROP) cannot be given explainability reasons. + +**Explainability endpoint:** `GET /api/v1/private/prs/get_ineligibility_reasons?policyId={id}` (requires VPN). --- -## Active experiments (as of Apr 2026) +## Dependencies -| Experiment | Channel | Description | +| System | Dependency type | Details | |---|---|---| -| `spirit_launch` | Consumer | Spirit routed ahead of Prime for assigned cohort. Age 20–65, TRL 1–50. | -| `spirit_partnership_launch` | Partnership | Same structure for Partnership channel. | +| Product Configuration Service (PCS) | Upstream — PRS reads PCS | Source of truth for carrier eligibility config: age bands, state approvals, productVariantId → productId mapping, citizenship/visa/document eligibility. | +| Main App | Caller — Main App calls PRS | Main App invokes PRS at product determination step. Also pre-calculates and passes: PreQual score, policy status data (Active/Decline/InProgress/Prior Rescinds), UW decisions, PA status, in-progress product list. | +| Profile Service | Upstream — PRS reads Profile Service | Used to fetch citizenship status, visa type, identification type (SSN/ITIN), and profile data for non-resident routing. | +| LGA Eligibility API | Upstream — PRS calls LGA directly | Real-time carrier eligibility check for LGA Prime. LGA Verification API is called directly by PRS. | +| Protective/Spirit Coverage API | Upstream — PRS calls via IPS | Real-time coverage check for Protective/Spirit. Currently hosted in IPS. Outstanding: migrate Protective API call to PRS directly (same pattern as LGA). | +| Underwriting Service | Upstream — Main App passes UW decisions | Prior decline decisions are retrieved via Main App → UW. PRS receives the pre-calculated UW decision in the request DTO. In-flight: a queryable decline-reason data store (per Re-Underwrite Eligibility PRD) will allow PRS to retrieve prior decline source classification directly — see Prior Decline Re-Underwrite section. | +| Policy Admin (PA) | Upstream — Main App passes PA data | PA data passed from Main App covers **active policies only** (UNISSUED, IN_FORCE, LATE_OFFER_PERIOD status checks, used for Ameritas Choice/SI). Declined policy data is handled separately via Main App → UW path. | +| IDV Service | Decoupled — PRS does not call IDV | IDV (identity verification / DMV) is fully decoupled from PRS. PRS routes based on eligibility criteria only. IDV is handled as a separate step in the application funnel. | +| Postgres (PRS DB) | Internal — PRS data store | Tables: product_recommendation_rules, user_eligibilities, carrier_eligibility_results, product_routing_results, product_override_config, active_version_tracker. | +| Snowflake / Fivetran / Airflow | Upstream — recommendation rules pipeline | Rules pipeline: Google Sheet → CSV → Google Drive → Fivetran → Snowflake → Airflow → PRS Postgres. | +| Optimizely | Upstream — feature flags | Feature flags used for PRS cut-over and treatment rollouts. | +| Datadog | Monitoring | Client-side metrics, service APM, SLO dashboard, slow query alerts. Alerts channel: #product-routing-service-alerts. PagerDuty: product-routing-service. | --- -## Prior decline re-underwrite feature (confirmed live) +## Known constraints + +**1. No AuthN/AuthZ on PRS (as of last review)** +PRS does not currently have authentication or authorization controls in place. This is a known security gap documented in the Runbook. + +**2. Protective/Spirit coverage API still routed via IPS** +LGA carrier eligibility is called directly by PRS. The outstanding item is Protective/Spirit — the coverage API call currently routes through IPS. The target state is for PRS to call Protective directly, consistent with the LGA pattern. + +**3. Carrier API outage behavior** +If LGA or Protective/Spirit coverage API is down: route to the other carrier. If both are down: process as normal using full max coverage (no API-based restriction applied). If a carrier API returns coverage < $100K: route to the other carrier. If both return < $100K: randomly assign to either carrier. + +**4. Multiple recommendation rules matching due to age calculation differences** +Different carriers use different age calculation methods (absolute vs. nearest year). This can cause an applicant near an age boundary to simultaneously match rules for two different products. Resolved by a priority-based rule matching system. Current product priority order (source: Product/Actuarial): (1) LGA Prime, (2) Ameritas Choice, (3) Ameritas Simplified Issue Term, (4) TruStage umbrella. + +**5. TNU fully deprecated** +TNU (TruStage Native Umbrella legacy routing) has been removed from all flows — both DTC and non-resident. TruStage products (TSTERM, TAWL, GAWLN) are the current fallback products. TSTERM is not eligible for non-resident applicants; TAWL → GAWLN is the non-resident fallback sequence. -Non-disclosure evidence declines (where the applicant did not disclose a condition that was later found via evidence) are eligible for re-underwrite. Disclosure-rule declines and unknowns continue to be blocked. 30-day gate confirmed for same-application scenarios. +**6. Product overrides skip recommendation rules but not eligibility** +When a product override is requested, PRS skips recommendation rules and uses the product_override_config table instead. All post-verification eligibility checks still apply to overridden products. Overridden products have their own fallback sequence defined in the override config. + +**7. Stacking parameter** +Stacking between LGA and Protective/Spirit is supported via `?stacking=true` parameter. This skips the cross-product issuance check for those two carriers only. It does not apply to any other product combination. + +**8. Amplitude anomaly dashboard alerts not active** +Amplitude-based product determination anomaly alerts are not currently functional. Datadog is the active monitoring system for all PRS-related performance, errors, and alerting. + +**9. Rollback requires env variable change** +PRS does not support instant self-serve rollback. Rolling back recommendation rules requires updating the active version environment variable via ArgoCD or an infra change. Rollback of the service itself uses the Optimizely feature flag. + +--- + +## Related PRD templates + +- Agent Contracting PRD (PRT) — covers contracting eligibility used by PRS in AA flow +- UW Foundations PRD (Underwriting) — covers UW decision data passed to PRS +- ERD Writer PRD (Engineering) — covers PRS data model and API contract + +--- + +## Prior decline re-underwrite eligibility + +> Source: PRD — Re-Underwrite Eligibility for Prior Declines (Non-Disclosure Evidence Only). Owner: Ashwin Pattan. Status: Live (Apr 2026). + +### What it is + +Today, any prior UW decline automatically blocks a repeat applicant from all products. This PRD introduces a re-underwrite eligibility gate that distinguishes between two decline types — allowing re-application only when the prior decline was driven by non-disclosure evidence (external signals that can change over time), while keeping disclosure-related declines permanently ineligible for re-underwrite. + +### Decline source classification + +Every prior decline is classified into one of three categories: + +| Category | Definition | Re-underwrite eligible? | +|---|---|---| +| NON_DISCLOSURE_EVIDENCE | Decline driven by external evidence signals that can change (e.g. corrected records, updated data sources, changed matching) | Yes — re-pull evidence and re-underwrite | +| DISCLOSURE_RULE | Decline driven by applicant disclosure inconsistencies | No — cap to decline immediately | +| UNKNOWN / UNCLASSIFIED | Classification could not be determined | No — conservative default; tracked via observability to reduce over time | + +### How PRS uses this + +PRS queries a new decline decision store at application start to determine re-underwrite eligibility: + +- Prior decline = NON_DISCLOSURE_EVIDENCE → underwrite as normal; ignore the prior non-disclosure decline; cap as normal for health and tobacco. +- Prior decline = DISCLOSURE_RULE or UNKNOWN → cap to decline. +- No prior decline → proceed as today (no change). +- Prior decline is less than 30 days old → not eligible for re-underwrite even if category is NON_DISCLOSURE_EVIDENCE (prevents mid-interview routing conflicts). + +### Decline decision store + +A new queryable store holds decision snapshots for PRS retrieval at application start. + +| Field | Notes | +|---|---| +| identity_id | Applicant identity key | +| application_id / policy_id | Policy reference | +| SSN BIndex | For fast retrieval | +| timestamp | Decision time | +| decision_outcome | approve / decline | +| decline_source_classification | NON_DISCLOSURE_EVIDENCE / DISCLOSURE_RULE / UNKNOWN | +| raw decline codes / rule identifiers | For audit and observability | +| evidence metadata | Non-PII where possible | +| version | Rule engine + model config version at time of decision | + +Retrieval target: <200ms p95 latency. If the store is unavailable, PRS defaults to ineligible (safe fallback). + +### Impact on cross-product rules + +This change modifies the current blanket prior-decline blocking behavior in the cross-product rules (see Tab 5 — Cross-product rules above). Non-disclosure evidence declines become eligible for re-underwrite regardless of prior cross-product restrictions, subject to normal evidence repull and full UW evaluation. Disclosure-rule declines and unknowns continue to be blocked as today. + +### Pending decisions (as of Apr 2026) + +This feature is confirmed live. The following items remain open and will govern edge case behavior as they are resolved: + +1. Canonical identity key for same applicant across attempts (SSN + DOB + name match definition TBD). +2. Broader cooldown policy — 30-day gate confirmed for same-application scenarios; multi-attempt cooldown rules TBD. +3. Handling of multiple prior declines — most recent vs. any prior decline. +4. Expected time window for evidence to change materially enough to justify re-underwrite. --- ## Needs Validation +The following items are confirmed as not yet implemented or are pending further input. Do not promote to confirmed content above without explicit sign-off. + **NV-1 — IDV/DMV Service Platform Overview** -IDV is decoupled from PRS. A dedicated IDV L1 Platform Overview does not yet exist. Added to tracker as outstanding. +IDV is decoupled from PRS. The IDV service does not yet have a Layer 01 platform overview file in the context library. A dedicated IDV L1 Platform Overview will be created from the IPP perspective. Until that file exists, any new product requiring identity verification has no platform-level documentation to reference for the IDV path. Added to tracker as outstanding. **NV-2 — Protective eligibility API migration from IPS to PRS** -LGA eligibility is already called directly via PRS. Protective (Spirit) coverage eligibility API migration from IPS to PRS direct is outstanding. +LGA eligibility is already called directly via PRS. The outstanding action item is to migrate the Protective (Spirit) coverage eligibility API from IPS into PRS direct — so that PRS owns all carrier eligibility calls rather than routing through IPS for Protective. **NV-3 — AuthN/AuthZ implementation** -PRS does not currently have authentication or authorization. No implementation timeline documented. +PRS does not currently have authentication or authorization. No implementation timeline documented in available sources. + +**NV-4 — Direct PRS → Underwriting Service integration** +The long-term design calls for PRS to call Underwriting Service directly (instead of receiving UW decisions pre-calculated from Main App). Not yet implemented. + +**NV-5 — Prior decline data source (Main App → UW)** +Active policy statuses are retrieved via Policy Admin (PA). For prior declines, PRS relies on data passed from Main App, which calls Underwriting (UW) to return prior decline decisions. This path is functional but remains a dependency on Main App as an intermediary for UW decline data. + +--- + +## Recommendation rules reference + +> Source: Product Recommendation Rules G-Sheet (always reflects latest snapshot). The G-Sheet is the source of truth — the tables below are a human-readable representation. Consult the live sheet for precise cell-level values before making routing decisions on edge cases. + +### How to read these tables + +Each cell shows the **ranked product list** for a given Age × TRL combination. Products are listed in priority order — the first eligible product is routed. All products in the list are evaluated; PRS returns the first one that passes all eligibility gates. + +**Product shorthand used in tables:** + +| Shorthand | Full name | ID | +|---|---|---| +| Prime | LGA Prime Term | 1 | +| Spirit | Protective Spirit Term | 21 | +| Choice | Ameritas Choice Term | 14 | +| SI | Ameritas Simplified Issue Term | — | +| IUL | Ameritas IUL | 15 | +| TS Term | TruStage Term Life (TSTERM) | 27 | +| GAWLN | TruStage Guaranteed Acceptance Whole Life (CUNAMUTUAL_GAWLN) | 19 | +| TAWLN | TruStage Traditional Whole Life (CUNAMUTUAL_TAWLN) | 18 | +| GAWL (Advantage) | TruStage Native Advantage Whole Life | — | + +**TRL score column headers** represent the upper bound of each band (e.g. column "51-55" means TRL score 51–55). "None" = no score returned. "DataUnavailable" / "InsufficientCredit" = no-score reasons. + +--- + +### Tab 1 — Consumer (DTC) | Citizens / Permanent Residents +**States: Compact + SC, SD, CA, FL, ND** + +> The Consumer and Partnership detailed matrices share the same structure. Both use 24 TRL columns (1–5 through InsufficientCredit) × 11 age bands. The condensed view below uses the Summary Tab breakpoints, which are the operative routing bands. See the full G-Sheet for exact per-TRL-point behavior. + +**Condensed routing view — Consumer DTC (Citizens / PR):** + +| Age (Nearest) | TRL 1–50 | TRL 51–70 | TRL 71–85 | TRL 86–99 | TRL 100 | No Score | DataUnavailable | InsufficientCredit | +|---|---|---|---|---|---|---|---|---| +| 20–44 | Prime, Spirit, TS Term | Prime, Spirit, TS Term | Choice, TS Term | TS Term | TS Term + GAWLN | TS Term + GAWLN | Choice, TS Term + GAWLN | Choice, TS Term + GAWLN | +| 45–50 | Prime, Spirit, TS Term, GAWLN | Prime, Spirit, TS Term, GAWLN | Choice, TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | +| 51–54 | Prime, Spirit, TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | +| 55–60 | Prime, Spirit, TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | +| 61–65 | Prime, Spirit, TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | Choice, TS Term, GAWLN | Choice, TS Term, GAWLN | +| 66–70 | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | TS Term, GAWLN | +| 71–75 | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | +| 76–80 | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | GAWLN | +| 81–85 | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | GAWL (Advantage) | + +> **Note — Prime vs. Spirit position:** In the detailed sheet, for TRL 1–35, Prime leads the list. For TRL 36–50, Prime and Spirit are both included. The summary above groups these for readability; consult the G-Sheet for exact TRL split points between Prime and Spirit. + +--- + +### Tab 2 — Consumer (DTC) | Non-Residents (Non-Citizen / Non-PR) +**States: Compact + SD, SC, FL, CA, ND** + +| Age (Nearest) | TRL 1–70 | TRL 71–95 | TRL 96–99 | TRL 100 | No Score | DataUnavailable | InsufficientCredit | +|---|---|---|---|---|---|---|---| +| 20–65 | Choice | Choice | TS Native | TS Native | TS Native | TS Native | TS Native | +| 66–85 | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | + +> Only Ameritas Choice and IUL are offered to Non-Resident / Non-PR applicants at initial launch. TS Term is not eligible for non-residents; fallback is TAWLN → GAWLN. + +--- + +### Tab 3 — Summary: Quick routing reference + +**DTC — Compact States (+ CA, SD, SC, FL) | Citizens / PR** + +| Age (Nearest) | TRL 1–15 | TRL 16–35 | TRL 36–50 | TRL 51–70 | TRL 71–85 | TRL 86–99 | TRL 100 | No Score | DataUnavailable | InsufficientCredit | +|---|---|---|---|---|---|---|---|---|---|---| +| 20–50 | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 51–54 | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 55–60 | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 61–65 | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 66–85 | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | + +**Partnership — Compact States (+ SD, SC, FL, CA, ND) | Citizens / PR** + +| Age (Nearest) | TRL 1–15 | TRL 16–35 | TRL 36–50 | TRL 51–70 | TRL 71–95 | TRL 96–99 | TRL 100 | No Score | DataUnavailable | InsufficientCredit | +|---|---|---|---|---|---|---|---|---|---|---| +| 20–50 | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 51–54 | LGA/Protective Prime | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 55–60 | LGA/Protective Prime | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 61–65 | LGA/Protective Prime | Ameritas Choice | Ameritas Choice | Ameritas Choice | Ameritas Choice | TS Native | TS Native | TS Native | Ameritas Choice | Ameritas Choice | +| 66–85 | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | + +**SoFi and Credit Karma — Citizens / PR** + +| Age (Nearest) | TRL 1–50 | TRL 51–70 | TRL 71–99 | TRL 100 | No Score | DataUnavailable | InsufficientCredit | +|---|---|---|---|---|---|---|---| +| 20–50 | LGA Prime | LGA Prime | Ameritas SI | TS Native | Ameritas SI | Ameritas SI | — | +| 51–54 | LGA Prime | Ameritas SI | Ameritas SI | TS Native | Ameritas SI | Ameritas SI | — | +| 55–60 | LGA Prime | Ameritas SI | Ameritas SI | TS Native | Ameritas SI | Ameritas SI | — | +| 61–65 | LGA Prime | Ameritas SI | Ameritas SI | TS Native | Ameritas SI | Ameritas SI | — | +| 66–85 | TS Native | TS Native | TS Native | TS Native | TS Native | TS Native | — | + +> SoFi + CK: PreQual / TRL restriction at 85 enabled via feature flag `prs_sofi_ck_trl_85_change` (as of March 2026). LiMu (Liberty Mutual) gets all products except Protective — triggered when partner code `af1f9` is passed. + +--- + +### Tab 4 — Experimentation tabs + +The Consumer Experimentation and Partnership Experimentation tabs use JSON cell format to encode treatment variants per Age × TRL bucket. Active live experiments: **`spirit_launch`** (Consumer) and **`spirit_partnership_launch`** (Partnership). Both are confirmed live. + +**Experiment cell structure:** +```json +{ + "prsExperimentIdentifier": "spirit_launch", + "treatment1": ["Spirit", "Prime", "Trustage_Term_Life"] +} +``` + +Experiment coverage (Consumer `spirit_launch`): Age 20–65, TRL 1–50 (all TRL bands where Prime is normally first). Ages 66+ and TRL 86+ are not part of the experiment. Treatment 1 routes Spirit ahead of Prime for the assigned cohort. + +--- + +### Tab 5 — Cross-product rules + +These rules govern whether a customer who has a prior policy with one product is eligible for another. PRS applies these at Step 4 of the eligibility pipeline. + +**Legend:** +- `x` = Not allowed (prior product blocks new product) +- Blank = Allowed (no cross-product restriction) +- `Inactive` = Product no longer sold; rule not applicable +- `No Declines` = Prior decline for this product does not block the new product +- `NA` = Rule not applicable for this product combination + +**Active products cross-decline matrix (Declined by UW — rows = prior declined product, columns = product being routed):** + +| Prior Declined Product | Prime (LGA) | Ameritas SI | Ameritas Choice | Ameritas IUL | Spirit (Protective) | TAWLN | GAWLN | +|---|---|---|---|---|---|---|---| +| LGA_TERM | x | — | x | x | x | — | — | +| AMERITAS_SI | x | — | x | x | x | — | — | +| AMERITAS_CHOICE | x | — | x | x | x | — | — | +| AMERITAS_IUL | x | — | x | x | x | TAWLN blocked | — | +| SPIRIT_TERM | x | — | x | x | x | — | — | +| CUNAMUTUAL_SITL | x | — | x | x | x | x | x | +| CUNAMUTUAL_TAWL | x | — | x | x | x | x | x | +| CUNAMUTUAL_TAWLN | x | — | x | x | x | x | — | +| CUNAMUTUAL_GAWLN | No Declines | No Declines | No Declines | No Declines | No Declines | No Declines | No Declines | + +> Full matrix includes 26 products and 25+ columns — active products shown above. Inactive products (ASSURITY_TERM, GREENHOUSE_TERM, LGA_ER, SENIORLIFE, etc.) are excluded from the condensed view. GAWLN and GAWL products are generally "No Declines" — prior decline does not block routing to guaranteed acceptance products. + +**Prior rescind rules:** Follow similar logic to declines for active Prime/Choice/IUL/SI products. TruStage products (SITL, TAWL, GAWL variants) are generally `NA` for rescind cross-blocking. Note: Engineering has not yet implemented full rescind cross-product rules — currently limited to ineligibility of the rescinded product itself. + +**Product issued / activated rules:** Having an active Prime policy does not block another Prime (stacking supported via `?stacking=true`). Having an active Choice blocks another Choice. Having an active Spirit blocks LGA and vice versa (unless stacking parameter is passed). GAWL/GAWLN always allows further routing. + +**Cross-decline rules summary (plain language):** +1. If ever declined for any Ethos product, do NOT route to Prime, Choice, SI, or IUL. +2. If declined for any non-TruStage/non-Beacon product, TruStage and Beacon products are still allowed. +3. If declined for TruStage SITL/TAWL or Beacon SI WL, only route to GAWL, Beacon GI WL, or AD. + +--- + +### Tab 6 — Product override config + +When a product override is requested, PRS skips the recommendation rules and routes using this config instead. Products and fallbacks are versioned. + +| Overridden Product | Product ID | Citizenship | Fallback (in priority order) | Fallback IDs | Channel | +|---|---|---|---|---|---| +| Choice | 14 | Citizen, Permanent Resident | TS Term → GAWLN | 27 → 19 | Consumer, Partnership | +| Choice | 14 | Non-Resident / No Visa / Null | TAWLN → GAWLN | 18 → 19 | Partnership | +| Ameritas IUL | 15 | Citizen / PR | TAWLN → GAWLN | 18 → 19 | Partnership, Consumer | +| Ameritas IUL | 15 | Non-Resident / Null | TAWLN → GAWLN | 18 → 19 | Partnership, Consumer | +| SITLB1 | 16 | Citizen / PR | GAWLN | 19 | Consumer, Partnership | +| SITLB1 | 16 | Non-Resident / Null | GAWLN | 19 | Consumer, Partnership | +| SITLB2 | 17 | Citizen / PR | GAWLN | 19 | Consumer, Partnership | +| TS Term | 27 | Citizen / PR | GAWLN | 19 | Consumer, Partnership | +| TAWLN | 18 | Citizen / PR | GAWLN | 19 | Partnership, Consumer, Final expense quoter | +| TAWLN | 18 | Non-Resident / Null | GAWLN | 19 | Partnership, Consumer, Final expense quoter | +| GAWLN | 19 | Citizen / PR | — (no fallback) | — | Partnership, Consumer | +| GAWLN | 19 | Non-Resident / Null | — (no fallback) | — | Partnership, Consumer | +| TNU (deprecated) | 20 | Citizen / PR | GAWLN | 19 | Consumer, Partnership | +| Protective (Spirit) | 21 | Citizen / PR | TS Term → GAWLN | 27 → 19 | Consumer, Partnership | +| Prime (LGA) | 1 | Citizen / PR | TS Term → GAWLN | 27 → 19 | Consumer, Partnership | +| Sammons IUL | 25 | Citizen / PR | TAWLN → GAWLN | 18 → 19 | Partnership | +| BEACON_SI_WL | 32 | Citizen / PR | BEACON_GI_WL | 33 | Partnership | +| BEACON_GI_WL | 33 | Citizen / PR | — (no fallback) | — | Partnership | + +> TNU (ID 20) remains in the override config table for legacy returning-user continuity but is deprecated from all new routing flows. + +--- + +### Non-PRS products — product override only + +The following products bypass the standard PRS recommendation rules pipeline entirely. They are accessed exclusively via product override (Direct Tile through AAA). Because they use product override, they are not present in any recommendation rules tab but do appear in the Product Override Config table (Tab 6). + +| Product | Product ID | Type | Channel | Routing path | +|---|---|---|---|---| +| John Hancock Simple Term | — | Term | Partnership | Product override via Direct Tile (AAA) | +| Ethos IUL (Indexed Universal Life) | — | IUL | Partnership | Product override via Direct Tile (AAA) | +| Beacon SI WL | 32 | Whole Life | Partnership | Product override only — fallback to Beacon GI WL (ID 33) | +| Beacon GI WL | 33 | Whole Life | Partnership | Product override only — no fallback | +| Sammons IUL | 25 | IUL | Partnership | Product override only — fallback to TAWLN → GAWLN | + +> These products do not have entries in Product Type Variations because they are never reached via normal PRS recommendation rules. All eligibility and fallback behavior is governed by the product_override_config table exclusively. + +**Products with both PRS and Direct Tile routing:** -**NV-4 — Direct PRS to Underwriting Service integration** -Long-term design calls for PRS to call Underwriting Service directly. Not yet implemented. +| Product | Type | Channel | Routing | +|---|---|---|---| +| Ameritas Choice with Living Benefits | Term | All | Both PRS and Direct Tile through AAA | +| Prime Term | Term | All | Both PRS and Direct Tile through AAA | +| TruStage TAWL | Whole Life | All | Both PRS and Direct Tile through AAA | -**NV-5 — Prior decline data source** -PRS relies on prior decline data passed from Main App (which calls UW). Functional but remains a dependency on Main App as intermediary. From 6eefb8677233ab7e02a8e4da9e885d4934eeaa2b Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Thu, 7 May 2026 16:38:30 +0530 Subject: [PATCH 5/5] feat: add L1 platform overview for Agent Assisted Application Funnel (AAA) Adds agent-assist-funnel_v2_0.md covering the full AAA flow, AOR/contracting model, compliance checks (IDV/AML/OFAC), PRS rerouting, product-specific behaviors (Prime, Choice, Ameritas IUL, Sahara), and all system dependencies. Sourced from ethos-prt context-docs. Updates README status to Draft. Co-Authored-By: Claude Sonnet 4.6 --- layer-01/platform-systems/README.md | 2 +- .../agent-assist-funnel_v2_0.md | 668 ++++++++++++++++++ 2 files changed, 669 insertions(+), 1 deletion(-) create mode 100644 layer-01/platform-systems/agent-assist-funnel_v2_0.md diff --git a/layer-01/platform-systems/README.md b/layer-01/platform-systems/README.md index 2527ec0..f3cb179 100644 --- a/layer-01/platform-systems/README.md +++ b/layer-01/platform-systems/README.md @@ -9,7 +9,7 @@ | ACORD Feed Framework | acord-feed-framework_v2_0.md | IPP owns | Outstanding | | Carrier Data Feeds | carrier-data-feeds_v2_0.md | IPP owns | Outstanding | | DTC Application Funnel | dtc-funnel_v2_0.md | IPP integrates | Outstanding | -| Agent Assisted App Funnel | agent-assist-funnel_v2_0.md | IPP integrates | Outstanding | +| Agent Assisted App Funnel | agent-assist-funnel_v2_0.md | IPP integrates | Draft | | Microsite Funnel | microsite-funnel_v2_0.md | IPP integrates | Outstanding | | LOB.com | lob_v2_0.md | IPP integrates | Outstanding | | Agent Portal | agent-portal_v2_0.md | IPP integrates | Outstanding | diff --git a/layer-01/platform-systems/agent-assist-funnel_v2_0.md b/layer-01/platform-systems/agent-assist-funnel_v2_0.md new file mode 100644 index 0000000..553f477 --- /dev/null +++ b/layer-01/platform-systems/agent-assist-funnel_v2_0.md @@ -0,0 +1,668 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: Agent Assisted Application Funnel (AAA) +owner_product: Pankaj Soni (IPP Product) +owner_engineering: IPP Engineering — Microservices / Partnerships +last_updated: 2026-05-07 +status: Draft +source: ethos-prt context-docs — channels/agent-assisted-application.md, contracting-aor/overview.md, contracting-aor/pattern.md, quoter/overview.md, agent-portal/overview.md, agent-portal/quote-and-application.md, products/prime, products/choice, products/ameritas-iul, products/sahara — Apr 2026 +template_version: 2.0 +--- + +# Agent Assisted Application Funnel (AAA) + +## What it is + +The Agent Assisted Application (AAA) is the primary application channel on the Partnerships platform. The agent drives the application end-to-end — quoting, filling the form, handling disclosures, managing IDV, AML, and OFAC checks, and submitting or routing to manual underwriting (RUW). The client participates only at specific consent and verification steps (OTP, e-sign). The guiding principle is **"agent is the product"** — the agent owns the journey and the outcome. This is distinct from Client-Initiated / MicroSite flows, where the consumer drives the application themselves. + +AAA runs across two surfaces simultaneously: +- **Agent Portal** (`agents.getethos.com`) — agent fills the form, reviews UW decisions, monitors status +- **Consumer App** — client receives OTP/e-sign link, completes identity verification, signs disclosures + +The funnel has two architectural generations: +- **Legacy AAA (consumer-first)** — built on top of the consumer application; still active for Prime, Choice, Ameritas IUL, Sahara +- **New AAA (agent-first)** — dedicated agent-first experience (PRD #47); live for GAWL, TS Term, Beacon; all other products migrating incrementally + +Available for all Partnerships products: Prime (LGA/Spirit), Choice (Ameritas), Ameritas IUL, Sahara IUL, TAWL/GAWL, Beacon SI/GI WL. + +--- + +## Ownership + +| Responsibility | Owner | Notes | +|---|---|---| +| Product requirements and funnel design | IPP Product (Pankaj Soni) | | +| Agent Portal build and maintenance | IPP Engineering — Partnerships | | +| Consumer App surface (e-sign, OTP) | IPP Engineering | Consumer-facing side of AAA | +| Agent Config Service | IPP Engineering — Microservices | Controls product enablement and priority order per agency | +| IDV / AML / OFAC compliance checks | IPP Engineering | GIACT, Persona, Twilio, TransUnion integrations | +| AOR / contracting flow | IPP Engineering — Partnerships | GCR form, DocuSign, AgentSync, carrier feeds | + +**Ownership boundary:** IPP Product defines routing rules, compliance check requirements, UW decision handling, and contracting eligibility rules. Engineering owns all service integrations, the Agent Config Service, surface-level build, and carrier feed pipelines. + +--- + +## Inputs required + +Before AAA can be configured for a new product: + +| Input | Provided by | Notes | +|---|---|---| +| Product enabled in Agent Config Service | IPP Engineering | Controls which agents/agencies see the product in the portal; drives featured product display and priority order | +| PRS recommendation rules for the product | IPP Product / Actuarial | Required before routing works in AAA; translated to PRS config via Google Sheet → CSV → Airflow pipeline | +| PCS configuration (coverage, eligibility, state approvals) | IPP Product | Required before quote or application can be generated | +| Carrier IDV / AML requirements | Insurance Team / Compliance | Determines which compliance checks apply per product | +| UW decision outcomes for the product | IPP Engineering / UW | Drives which decision states are surfaced to the agent | +| E-sign and OTP configuration | IPP Engineering | Required for activation path | +| RUW support (if applicable) | IPP Engineering | Required before agent resume of RUW-approved apps is enabled | +| AOR / contracting configuration per carrier | IPP Engineering | GCR form, DocuSign setup, SFTP or feed configuration for the carrier | +| Carrier submission cap (if applicable) | IPP Product | 3-policy cap enforced for most carriers before contracting confirmed | +| PA (Pennsylvania) appointment check configuration | IPP Engineering | Required for any product available in PA | + +--- + +## Outputs produced + +| Output | Destination | Notes | +|---|---|---| +| Started application (policy record) | Main App / PAS2 | Created when agent begins a quote or application | +| Customer record | Customers tab (Agent Portal) | Created on first entry of name, email, phone number | +| Routed product | PRS → Main App | PRS evaluates eligibility and routes to the correct product at application start | +| UW decision | Agent Portal (inline) | Surfaced at post-interview step; reasons shown where available (TruStage products do not return UW reasons; routing reasons shown instead) | +| Activated policy | PAS2 / carrier | Triggered by e-sign completion | +| TX103 (ACORD) | Carrier | New business submission sent to carrier after all pre-transmission checks pass | +| RUW submission | Underwriting Service | Triggered when UW routes to manual review | +| AOR / contracting record | Par system / Salesforce | Written agent NPN appears on carrier submissions and all policy documents after contracting confirmed | +| Analytics events | Amplitude | Funnel drop-offs, e-sign method split, reroute frequency, risk/fraud check pass/fail rates | + +--- + +## Product catalog and entry points + +### Products available in AAA (as of May 2026) + +| Product | Carrier | Coverage | Issue Age | Instant Decision | AAA Architecture | Quote Pattern | +|---|---|---|---|---|---|---| +| Term Life — Prime (LGA) | Banner Life (Legal & General America) | $100K–$2M (age-banded) | 20–65 | ~90% | Legacy | Separate quote + app | +| Term Life — Prime (Spirit) | Protective Life Insurance Company | $100K–$2M (age-banded) | 20–65 | ~90% | Legacy | Separate quote + app | +| Term With Living Benefits — Choice | Ameritas Life Insurance Corp | $50K–$1M (age-banded) | 20–65 | 90% | Legacy | Separate quote + app | +| Ethos Protection IUL (Ameritas IUL) | Ameritas Life Insurance Corp | $25K–$1M (age-banded) | 20–65 | 60%+ | Legacy | Combined quote + app | +| Accumulation IUL (Sahara) | North American Company / SFG | $25K–$2M (age-banded) | 18–65 | ~80% | Legacy | Combined quote + app | +| Final Expense Whole Life (TAWL) | MEMBERS Life Insurance Co. | $5K–$100K | 20–85 | 100% | New AAA | Separate quote + app | +| Guaranteed Acceptance Whole Life (GAWL) | CMFG Life Insurance Co. | $2K–$25K | 45–80 | 100% | New AAA | Separate quote + app | +| Beacon Simplified Issue WL (SIWL) | Banner Life Insurance Co. | $2K–$50K | 45–85 | 100% | New AAA | Separate quote + app | +| Beacon Guaranteed Issue WL (GIWL) | Banner Life Insurance Co. | $2K–$25K | 45–80 | 100% | New AAA | Separate quote + app | +| TruStage® Term Life (TS Term) | MEMBERS Life Insurance Co. | $15K–$300K | 20–69 | 100% | New AAA | Separate quote + app | + +**Not available in New York** for all products. Additional state restrictions: TAWL not available in CT; GAWL not available in WA. + +### Agent Portal — Quote & Application tab + +Products are displayed in two sections: + +**Featured section (top 3):** Determined by the Agent Config Service — the top 3 enabled products based on priority order configured per agency. Same priority logic drives shortcuts on the Home page. Each card shows: product name, description, coverage range, carrier tags, and CTA button(s). + +**All Products section:** All available products in collapsible categories (Term Life, Index Universal Life, Whole Life). Two agents at different agencies may see a different set of featured products and a different default product order. + +### CTA patterns by product + +| Pattern | Products | +|---|---| +| **Create quote** + **Start application** (separate steps) | Prime (LGA/Spirit), Choice, TAWL/GAWL, Beacon, TS Term | +| **Start quote & application** (combined, single flow) | Ameritas IUL, Sahara (Accumulation IUL) | + +--- + +## AAA Flow — Step by Step + +### Step 1 — Quote → Application Handoff + +For separate-flow products (Prime, Choice, TAWL/GAWL, Beacon, TS Term), the agent creates a quote first by entering: Sex, Birth date, Smoking status, Residence, Health class. The quote displays estimated coverage and premium. From the quote, the agent starts the application independently. + +For combined-flow products (Ameritas IUL, Sahara), the agent enters the quote form and proceeds directly into the application without a separate quote-creation step. IUL quote forms also offer multiple solve options: + +- **Ameritas IUL**: Smart Solve™ (default), Maximize Cash Value, More Solves (dropdown) +- **Sahara**: Express Solves (Max Cash Value · Maximize retirement income · Smart Solve™ · Million dollar baby · College savings alternative), Custom Solve, Import an illustration + +Both IUL products surface inline **Frequent Knockout Conditions** panels in the quoter — agents are warned before entering the full application. + +### Step 2 — Pre-Interview: Basic Client Info + +Before the main health interview, the agent completes: + +**a. Soft consent** — agent informs the client of the application process and captures soft consent before proceeding. + +**b. Basic client info** — agent enters: +- Full name, DOB, address, SSN or ITIN +- Driving license (state confirmation) +- LexisNexis prefill surfaces address and phone suggestions; partial SSN prefill available for eligible applicants + +**c. Returning user check** — if the email matches an existing Ethos user, the system prompts client verification using existing profile details. Name and DOB are pre-filled and locked (cannot be changed). Verification attempt limit is configurable. Any open application for the same profile is automatically closed when a new one is started. If verification fails: agent can start a fresh application with a new email. + +**d. Phone number selection** — agent selects from prefilled LexisNexis phone options or enters manually if no prefill is found. For returning users with an existing number, OTP is sent to verify or update it. + +### Step 3 — Pre-Interview Compliance Checks + +Three compliance checks run before the main health interview begins. All three are required before the application can proceed. + +#### ToF Fraud / Identity Check + +| Path | Trigger | Method | +|---|---|---| +| Primary | SMS Disclosure Signature qualifies | Phone OTP via Twilio | +| Fallback | Any SMS criterion fails | Document IDV via Persona (Government ID + selfie) | + +**SMS Disclosure Signature qualification** — phone OTP path is used only if ALL four criteria are met: +1. Client's phone is a mobile number (confirmed via Twilio LineType) +2. Phone is associated with the user via LexisNexis Prefill or Twilio Identity match +3. Non-documentary AML control has passed +4. No government ID upload required by UW (US Resident, or TruStage + SSN) + +If any criterion fails → document-based IDV (Persona) is triggered. + +#### AML Check + +| Product | Primary | Backup | +|---|---|---| +| Term products (Prime, Choice) | GIACT | TransUnion | +| WLFE / TruStage products (TAWL/GAWL) | TS IDV check | — | +| TruStage/TS products | Not applicable | — | + +#### OFAC Check + +Automated for all products and all users. Blocks the application with a visible reason if flagged. + +#### Foreign national handling + +If the client is a non-citizen or non-Permanent Resident, the agent selects the applicable visa/ID type and is shown guidance on required documents. IDV, AML, and UW controls differ: + +| Document Type | ToF Control | AML Control | UW Control | +|---|---|---|---| +| Eligible visa + SSN | Phone OTP (primary) | Non-doc available; Govt ID+Selfie as backup | Visa or EAD required | +| Eligible visa + ITIN | Phone OTP (primary) | Non-doc NOT available; Govt ID+Selfie only | Visa or EAD required | +| EAD only + SSN | Govt ID+Selfie (backup) | Non-doc available; Govt ID+Selfie as backup | EAD required | +| EAD only + ITIN | Govt ID+Selfie only | Non-doc NOT available; Govt ID+Selfie only | EAD required | +| No visa + No EAD + SSN | None | Not applicable — routed to TruStage | — | +| No visa + No EAD + ITIN | — | Non-doc NOT available; Govt ID+Selfie only | UW doc upload not needed | + +**Product eligibility by document type (Choice and Ameritas IUL):** + +| Document Type | Eligible? | Conditions | +|---|---|---| +| SSN + eligible US visa | Yes | — | +| SSN + EAD (no visa) | Yes | No travel outside US within 2 yrs of EAD issue; US resident ≥18 months; US-based medical care + physician visit in past 18 months | +| SSN only (no visa, no EAD) | No | Routed to TruStage | +| ITIN + eligible US visa | Yes | — | +| ITIN + EAD (no visa) | Yes | Same EAD conditions above | +| ITIN only | Yes (Choice/IUL) | Age 25–60; ≥$40K household income; US resident ≥18 months; no travel outside US; US-based medical care + physician visit in past 18 months | + +### Step 4 — AOR / Contracting Check (Agent of Record) + +Before or during the AAA flow, the platform enforces agent contracting and licensing requirements. The check point varies by product and state — it runs at **app start, waterfall routes, and submission/activation**. + +#### What AOR means + +- **Before AOR:** All Ethos policies were submitted under a single internal agent (Michael Mould). The writing agent's NPN was passed alongside but not used as AOR. +- **After AOR:** The writing agent's NPN appears in the carrier API header and on all policy documents. +- **Transition state:** Until an agent completes contracting, Ethos remains the AOR. Exception: Spirit (Protective) uses one signature (Ethos/Michael Mould) until the agent is fully contracted — they do not want two signatures. + +#### Agent eligibility categories + +| Agent type | AOR eligible? | GCR required? | +|---|---|---| +| `consumer`, `agent`, `agency` | Yes | Yes | +| `affiliate` | No | No — Ethos always AOR | +| Referral / Goosehead type | No | No — Ethos always AOR | + +#### Three-ladder contracting model + +**Ladder 1 — GCR status:** + +| Status | Meaning | +|---|---| +| Not applied | Agent hasn't started the GCR form | +| Initiated | Agent started but hasn't completed | +| Completed | GCR submitted; versioned by update date | + +**Ladder 2 — Contracting status (carrier-level):** + +| Status | Meaning | +|---|---| +| Not initiated | Default; agent has not started GCR or DocuSign | +| Started | Agent started GCR form but has not yet signed DocuSign | +| Submitted | DocuSign signed; waiting for carrier confirmation (PA at TruStage only) | +| Active | Agent is contracted and appointed in at least one state | +| Inactive | Carrier marked agent inactive; reinstatement may be possible | +| Carrier Ineligible | Carrier cannot onboard agent; blocks that carrier's products only | +| Terminated | Hard decline — agent cannot sell for that carrier | +| Needs attention | Carrier needs additional info; GCR unlocks for resubmission | +| Expired | Contracting expired by carrier | + +**Ladder 3 — Appointment status (state-level):** +Not applied → Submitted → Confirmed → Declined → Needs attention → Expired + +#### Policy submission cap + +Most carriers enforce a 3-policy cap per agent before contracting is fully confirmed: + +| Carrier / Product | Cap | +|---|---| +| LGA (Banner) — all products (Beacon + Prime share the same count) | 3 policies / agent | +| Protective (Spirit) | 3 policies / agent | +| TruStage — TAWL, SITL, GAWL | 3 policies / agent / TS product (each counted separately) | +| Ameritas IUL | 3 policies / agent | +| Ameritas Choice | No cap | + +The 4th submission is blocked at: Routing page, Quoter, AAA → Client Details, Homepage, Final Look, Thank You page, Settings. Quoting remains allowed; only "Start Application" is disabled. + +#### License verification (AgentSync / NIPR) + +License check (Life LOA) runs via AgentSync on the Final Look page for all products. AgentSync queries NIPR (refreshed daily; ~24-hour lag for new licenses). + +**AgentSync failure modes:** + +| Scenario | Behavior | +|---|---| +| Agent NPN incorrect or name/SSN mismatch | AgentSync returns error; inform agent | +| License found but wrong Line of Authority (not Life LOA) | Submission blocked | +| API failure (NIPR timeout) | Final Look: allow submission (policy → "Ready for Carrier Transmission") | +| NIPR lag (new license, 1–2 day delay) | Background job re-checks every 4–6 hours for up to 48 hours | +| NIPR down/unreachable | Submit allowed; policy → "Ready for Carrier Transmission"; background retries | +| No license confirmed after 48h | Application auto-closes; agent and client notified | + +#### Pennsylvania (PA) — pre-appointment state + +PA is the only pre-appointment state at TruStage launch. It requires formal carrier appointment before an agent can submit their first policy as AOR. Checks run at 3 points: **app start, waterfall routes, submission/activation**. + +**PA flow for Prime (LGA + Spirit):** +1. License check — not licensed in PA → cannot start AAA (can still share quote) +2. Contracting check — if not contracted: + - GCR → DocuSign for Protective first; XML feed sent to Protective (pre-appoints licensed PA agents) + - Then DocuSign for LGA/Banner; XML feed sent to LGA with state = PA +3. Appointment check — contracted but not yet appointed → PA appointment request sent to contracted carriers +4. PRS routing once appointed: agent appointed with Protective only → Spirit products only; LGA only → LGA products only; both → all Prime products available + +**Appointment confirmation by carrier:** +- TruStage: Confirmed via email +- LGA (Banner) / Spirit (Protective): Via XML SFTP feed (state = PA sent in feed); Protective pre-appoints licensed PA agents automatically +- Sahara (North American): Via TX1228 daily feed +- Ameritas IUL: Via SuranceBay +- Ameritas Choice: License check applies; appointment request sent if not appointed + +#### AML training requirement + +Required for: Ethos/Ameritas IUL, Accumulation/Sahara IUL, Beacon (Banner WL), TruStage TAWL, TruStage GAWL. +**Not required for:** LGA Prime, BGA Prime, Protective/Spirit Prime, TruStage Term, Ameritas Choice. + +Validity window: 24 months. Captured via GCR form question flow: +1. "Have you completed AML training within the previous 24 months?" → Yes/No +2. If Yes: "Did you complete on Limra?" → Yes/No + - If Yes: done + - If No: certificate upload required +3. Date selector: "When did you last complete AML training?" (stored as ``) + +If date entered is > 24 months ago: agent is blocked and instructed to complete training before continuing. + +#### State IUL training requirements (Iowa and California) + +Both states require a one-time 4-hour IUL training course before selling indexed products. Certificates do not expire. + +- **Iowa**: State-approved Indexed Product Training required for IUL products (Ameritas IUL, Sahara) +- **California (SB 263)**: Required for agents with licenses issued or renewed on or after 1/1/2024; applies to IUL products only + +#### Carrier outbound feed (contracting requests) + +| Carrier | Method | +|---|---| +| TruStage | Email | +| LGA (Banner Life) | SFTP XML (custom, not ACORD); twice daily at 3:30 AM and 3:30 PM UTC | +| Spirit (Protective) | SFTP XML — same structure as LGA | +| Sahara (North American) | TX1228 Daily Agent Contracting Feed (inbound carrier → Ethos) | +| Ameritas IUL | SuranceBay third-party flow — NOT the standard GCR/DocuSign pipeline | +| Ameritas Choice | Appointment only; not via SuranceBay or GCR/DocuSign | + +### Step 5 — Main Interview + +The agent fills all health history, lifestyle, financial, and beneficiary questions on behalf of the client. Reflexive (follow-up) questions appear inline. UW and routing reasons are surfaced at reroute decision points. For non-Sahara products, payment details can be added before RUW submission. + +**Key interview fields by product:** + +| Category | Prime / Choice | Ameritas IUL | Sahara IUL | +|---|---|---|---| +| Health questions | Standard health interview (APS for age 61+) | Standard + financial history | Knockout guide-aligned | +| Financial history | Moderate | Yes — bankruptcy/foreclosure within 7 years; multiple credit delinquencies are knockout conditions | Standard | +| Beneficiary | Yes | Yes | Yes | +| Riders | N/A | Care4Life LB, Lifetime Income Rider, Waiver, ADB | ADB, Waiver of Monthly Deductions, Flexible Benefit | +| Payment info | Before RUW submission | After illustration review | Monthly/quarterly/semi-annual/annual ACH options | +| Illustrations | N/A | Ameritas PAS system | WELiS Illustration Engine — agent and applicant both e-sign | + +### Step 6 — UW Decision + +| Decision | Description | Applies to | +|---|---|---| +| Approved as applied | Instant approval at quoted class | All products | +| OTAF | Offer To Applicant in Full — approved at applied-for terms | Prime, Choice | +| Approved with adjusted offer | Rate class change or rider modification | Prime, Choice, IUL | +| Product + AD bundle | Approved with Accidental Death rider option | Select products | +| IUL as approved | IUL approval at quoted class | Ameritas IUL, Sahara | +| IUL OTAF (upgraded/downgraded) | IUL approval at adjusted class | Ameritas IUL, Sahara | +| RUW | Referred to Underwriting — manual review required | Prime, Choice, IUL, Sahara | +| IUL → TAWL | IUL declined; rerouted to TruStage Advantage Whole Life | Ameritas IUL, Sahara | +| Hard decline | Not eligible for any Ethos product | All products | + +**Approval rates:** ~90% instant for Prime/Choice; ~60%+ for Ameritas IUL; ~80% for Sahara. +**TruStage products:** Do not return UW reasons; routing reasons shown instead. + +**Choice — Living Benefits at UW decision:** + +| Scenario | LB outcome | +|---|---| +| Table D (4) or better | All 3 riders: Critical, Chronic, Terminal Illness | +| Table E or above | Terminal Illness Rider only (Chronic + Critical declined) | +| CA, age 65+ | No Critical Illness Rider | +| CA, applicant answers "No" to UN 3001 supplement | No Critical Illness Rider; gets Chronic + Terminal | +| LB declined by UW | Terminal Illness Rider only | + +**IUL + Choice bundling (after IUL approval):** + +After Ameritas IUL underwriting approval, agents are offered the option to add a Choice term policy for the same applicant: +- No additional UW questions — IUL approval covers Choice eligibility +- If IUL goes to RUW: Choice consent screen is deferred (P1 scope) +- If IUL is declined: Choice also declined; applicant sent to TruStage +- Beneficiary, payment, and future date information are pre-filled from IUL to Choice +- Policies submitted separately; failure of one does not block the other +- Exclusions: user has an existing active Choice policy; user was previously declined for Choice; max 1 IUL + 1 Choice per person + +### Step 7 — Coverage & Payment + +After approval, the agent reviews a **coverage selector** (standardized for Prime, Choice, and other products post-RUW) and a **premium draft selection page**: + +- Activate today, or future-date up to 30 days out +- Draft dates 27–31 of any month are excluded (billing cycle constraint) +- If future date falls on or after the client's birthday, premium may increase; this must be surfaced to the agent + +**Sahara payment options (Super Solve — PRD #41, live):** +- Monthly ACH (standard) +- Annual premium payments (client pays APP annually upfront) +- Lump sum (one-time at activation; additional lump sums made directly with Ameritas post-activation) + +The agent previews all final policy details before activation. + +### Step 8 — Activation (E-Sign) + +Two activation paths: + +| Path | Who | How | +|---|---|---| +| Client e-sign | Client signs from their device | Agent sends OTP/activation link; client confirms on Consumer App | +| Agent e-sign on behalf of client | Agent signs with client present | Agent uses e-sign flow in Agent Portal | + +Both paths are tracked in analytics to monitor the split between the two methods. AOR re-validation runs at the activation step (live for IUL; part of the non-IUL bug fix for Prime and Choice). + +--- + +## RUW Activation (Post-Approval) + +RUW-approved policies require a separate activation step after the UW team generates an offer. Supported for: Choice, Prime (LGA and Spirit), Ameritas IUL, Sahara IUL. + +### Channel resume rules (by design) + +- **AAA apps:** Only the agent can resume. Client cannot resume an AAA app — ever. +- **Client-initiated apps:** Only the client can resume. Agent cannot resume a client-initiated app — ever. + +### Current state by product + +| Product | Agent Can Resume RUW-Approved AAA | Status | +|---|---|---| +| Ameritas IUL | Yes — via e-sign consent | Working | +| Sahara IUL | Yes — via e-sign consent | Working | +| LGA Prime | No | Known bug; fix in progress | +| Spirit (Protective) | No | Known bug; fix in progress | +| Ameritas Choice | No | Known bug; fix in progress | + +### RUW activation flow (IUL — current working state) + +1. RUW submission — no changes to e-sign/OTP flows at submission +2. UW team generates offer (as-applied or OTAF) via legacy admin portal +3. Agent resumes from Agent Portal +4. Agent sends OTP to client (path 1) or sends activation link to client (path 2) +5. System runs AOR re-validation +6. Policy activated + +**Bug fix in progress (non-IUL):** When shipped: +- Enables agent resume + e-sign activation for Prime and Choice +- Requires e-sign consent (OTP or send-to-client) at agent activation +- Adds AOR re-validation at the activation step +- Blocks client activation of AAA policies via member portal post-RUW + +--- + +## Compliance requirements + +| Requirement | AAA | Client-Initiated | +|---|---|---| +| AOR check | Required at submission; re-validation at activation (IUL: live; non-IUL: part of bug fix) | Not required | +| License check (Life LOA) | Required via AgentSync on Final Look | Not required | +| Appointment check (PA states) | Required before application start | Not applicable | +| ToF Fraud (IDV) | Required — phone OTP (primary) or Persona doc IDV (fallback) | Required | +| AML | GIACT/TU (Term); TS IDV (WLFE) | Client self-serves | +| OFAC | Required — automated | Required | +| AML training (agent) | Required for IUL, TAWL, GAWL, Beacon products | Not applicable | +| IUL training (Iowa / CA) | Required for IUL products; one-time | Not applicable | + +--- + +## Product-level rerouting via PRS + +PRS determines the final issued product based on UW outcomes. Routing is non-sequential — it can jump across product types. + +| Entry product | Routes out to | Trigger | +|---|---|---| +| Prime (LGA/Spirit) | Choice | Exceeds Prime TRL eligibility but within Choice range | +| Prime | TS Term Life | Moderate/high-risk outside Choice eligibility | +| Prime | TAWL/GAWL | Further fallback for applicants not eligible for term products | +| Choice | TruStage | TRL > 95 or FN with SSN only | +| Ameritas IUL | TAWL | Tables 7–10 or manual UW referral | +| Sahara IUL | TAWL | ~20% of applicants not receiving instant IUL approval | +| TAWL | GAWL | TAWL not available or applicant not eligible | + +--- + +## Product-specific AAA behaviors + +### Prime (LGA + Spirit) + +- **Coverage (age-banded):** Age 20–50: $100K–$2M; Age 51–60: $100K–$1M; Age 61–65: $100K–$500K +- **Term lengths:** 10–40 years (varies by age band and tobacco status) +- **UW classes:** Preferred Plus, Preferred, Standard, Table ratings (non-tobacco); Standard, Table ratings (tobacco) +- **APS/EHR:** Required for applicants age 61+ +- **Conversion (Banner Life only):** Client may convert to Life Step UL — the only conversion option across Ethos term products. Not available on Protective policies. +- **BGA Term (LGA only — Q2 2026 launch):** Expanded TRL eligibility, lower PPU pricing, max issue age 60, coverage up to $3M for age 20–50. Available only to BGA-configured agencies. +- **RUW bug:** Agent resume of RUW-approved AAA apps not working for Prime. Fix in progress. + +### Choice (Ameritas) + +- **Coverage (age-banded):** Age 20–50: $50K–$1M; Age 51–60: $50K–$500K; Age 61–65: $50K–$350K +- **Term lengths:** 10–40 years (varies by age and tobacco status) +- **UW classes:** Preferred Plus through Standard; Table ratings 1–10 (non-tobacco); Standard, Table ratings 1–10 (tobacco) +- **Living Benefits at no cost:** Critical, Chronic, and Terminal Illness riders included; requires Table D (4) or better for Chronic/Critical +- **LB acceleration:** 90% of death benefit; APV (Actuarial Present Value) basis — not lien-based +- **State-specific rider structure:** Single combined rider for most states; three separate riders in CA; state-specific filings for FL, SD, SC +- **IUL + Choice bundling:** After IUL UW approval, agent offered Choice for same applicant (no additional UW required) +- **DTC excluded:** Partnerships-only; Ameritas not approved for DTC term + LB +- **SoFi/CreditKarma excluded:** Continue routing to form 3029 without LB +- **No agent appointment change:** No additional appointment beyond standard Ameritas contracting +- **RUW bug:** Agent resume of RUW-approved AAA apps not working. Fix in progress. + +### Ameritas IUL (Ethos Protection IUL) + +- **Coverage (age-banded):** Age 20–50: $25K–$1M; Age 51–60: $25K–$500K; Age 61–65: $25K–$350K +- **Design:** Protection-first, level-to-endow configuration +- **Illustrations:** Ameritas PAS illustration system; not WELiS +- **Riders:** Care4Life ADB (Critical/Chronic/Terminal); Lifetime Income Rider (not available in WA); Overloan Protection; Waiver of Specified Premium; ADB (at cost) +- **Super Solve (PRD #41 — live):** Annual and lump sum payment modes added in addition to monthly +- **Contracting:** AOR flow active but uses SuranceBay (third-party), NOT the standard GCR/DocuSign pipeline +- **Training:** AML + Iowa/CA IUL training required +- **Non-PA states:** Agent can submit before contracting confirmed; TX103 held in "Ready for Carrier Transmission" until contracting confirmed +- **RUW activation:** Working — agent resumes, e-sign consent, AOR re-validation at activation + +### Sahara (Accumulation IUL — North American / SFG) + +- **Coverage (age-banded):** Age 18–50: $25K–$2M; Age 51–60: $25K–$1M; Age 61–65: $25K–$250K +- **Design:** Accumulation-first; Min-Non-MEC-DB, Option B to A — maximizes cash value +- **Illustrations:** WELiS Illustration Calculation Engine; both agent and applicant e-sign the illustration AND the application +- **Riders:** ADB (Critical/Chronic/Terminal); Protected Death Benefit; Overloan Protection; Return of Premium DB Endorsement; Life Perks Rider; Waiver of Monthly Deductions; Flexible Benefit Rider; ADB Rider (not available in CA) +- **Not available in:** NY, CA, OR +- **Agency contracting:** Carrier → Ethos → Agency → Agent (not standard carrier → Ethos → Agent). Each agency requires an `sfgAgencyID` from SFG before any agents can sell Sahara. This is a one-time manual process outside Ethos systems. +- **Compensation:** Instant True-up (ITU) basis; 12-month advance pay cap of $10,000; rolling target premium across multiple years +- **Billing feeds:** TX508 (initial premium), TX1203 (inforce daily), TX1228 (daily agent contracting) +- **Primary distribution:** FFL (Family First Life) and GFI (Global Financial Impact) +- **Training:** AML + Iowa/CA IUL training required +- **RUW activation:** Working — agent resumes, e-sign consent, AOR re-validation at activation + +--- + +## Agent Portal — system context + +| Component | Description | +|---|---| +| Agent Config Service | Stores per-agent and per-agency configuration — product eligibility, product priority order, feature flags, integration settings. Controls featured product display. | +| Partnerships API | Core API layer connecting enterprise onboarding flows, Salesforce, and the portal | +| AgentSync | NPN verification and NIPR licensing data integration | +| Par system | Core backend; source of truth for AOR and controlled policy status | +| Salesforce (SFDC) | Stores contracting status; feeds to Par system | +| DocuSign | Carrier contracting form signing — triggers commission unblock on agent signature | +| Retool | Partner Ops tool — update contracting status, disable commission blocks, manage PA appointments manually | +| Ironclad | Metadata storage for signed contracting forms (timestamp, PDF copy) | + +**Portal navigation relevant to AAA:** + +| Nav item | Description | +|---|---| +| Quote & Application | Product selector; entry point for starting quotes and applications | +| Customers | Full list of leads, quotes, and policy records; CRM-lite with notes and tasks | +| Settings → Carrier Contracting | Agent's per-carrier contracting status, appointment states, and action items | + +--- + +## Dependencies + +| System | Dependency type | Details | +|---|---|---| +| Agent Config Service | Upstream | Controls product enablement and priority order per agency | +| PCS (Product Configuration Service) | Upstream | Coverage, eligibility, state approvals — required before quote or application | +| PRS (Product Routing Service) | Upstream | Routes applicant to correct product at application start; determines final issued product | +| Main App | Runtime | AAA application data flows into and is managed by Main App | +| Consumer App | Runtime — client surface | Client receives OTP/e-sign link; completes IDV, disclosures, activation | +| LexisNexis | Upstream — prefill | Address, phone, partial SSN prefill at pre-interview step | +| Persona | Upstream — document IDV | Government ID + selfie when phone OTP path is not available | +| GIACT / TransUnion | Upstream — AML | Non-documentary AML control for Term products | +| Twilio | Upstream — OTP / LineType | Phone OTP delivery; mobile number type verification | +| AgentSync / NIPR | Upstream — license verification | Life LOA confirmation; 24h NIPR refresh lag | +| DocuSign | Upstream — contracting | Carrier contracting form signing; commission unblock trigger | +| WELiS | Upstream — illustrations (Sahara) | IUL illustration calculation engine for Sahara/North American products | +| Ameritas PAS | Upstream — illustrations (Ameritas IUL) | Illustration system for Ethos Protection IUL | +| PAS2 (Policy Admin System) | Downstream — policy activation | Activated policy data flows to PAS2 | +| Underwriting Service | Downstream — RUW | RUW submission routed to UW team for manual review | +| Par system | Downstream — AOR | Source of truth for AOR and controlled policy status | +| Salesforce | Downstream — contracting | Contracting status stored; feeds to Par system | +| Optimizely | Runtime — feature flags | Used for AAA migration rollouts and treatment experiments | +| Amplitude | Downstream — analytics | Funnel events, e-sign split, reroute frequency, fraud check pass/fail rates | +| Stripe | Downstream — initial premium | Initial premium charged via Stripe after activation | + +--- + +## Known constraints + +**1. Legacy AAA architecture for most products.** +Prime, Choice, Ameritas IUL, and Sahara remain on the consumer-first legacy AAA. The agent-first migration (PRD #47) is incremental. New products should target the new AAA experience. + +**2. Non-IUL agent resume of RUW-approved apps is broken.** +Prime (LGA + Spirit) and Choice agents cannot resume RUW-approved AAA apps from the portal. Clients are using the member portal as a workaround — this is incorrect behavior. Fix is in progress. When shipped: enables agent resume, adds e-sign consent at activation, adds AOR re-validation, and blocks client activation of AAA policies post-RUW. + +**3. Client cannot resume an AAA app.** +By design. Any AAA app started by an agent must be resumed by the agent. There is no client-resume path for AAA. Conversely, agents cannot resume client-initiated apps. + +**4. Draft date exclusions.** +Dates 27–31 of any month are excluded from premium draft selection (billing cycle constraint). New products must account for this in activation UX. + +**5. Birthday premium increase.** +If the activation future date falls on or after the client's next birthday, the premium may increase. This must be surfaced to the agent in the coverage/payment step. + +**6. SMS Disclosure qualification is a 4-criteria gate.** +Failure of any single criterion routes to document IDV (Persona), which has higher drop-off. Foreign national flows have limited or no phone OTP path depending on document type. + +**7. AOR re-validation at activation (non-IUL).** +Once the non-IUL bug fix ships, AOR re-validation will be required at the activation step — consistent with the IUL flow. Products going live before the fix ships should plan for this requirement. + +**8. Sahara requires agency-level contracting with SFG before any agents can sell.** +The agency must obtain an `sfgAgencyID` from SFG/North American directly. This is a one-time manual process outside Ethos systems. It is a prerequisite for the AOR flow to work for any agent at that agency. + +**9. Ameritas IUL uses SuranceBay (non-standard contracting pipeline).** +Ameritas IUL contracting is not integrated into the standard GCR/DocuSign pipeline. End-to-end AOR standardization for Ameritas IUL is not on the current roadmap. + +**10. NIPR 24-hour lag.** +New licenses may not be visible in NIPR for up to 24 hours. Background job retries every 4–6 hours for up to 48 hours. Applications auto-close if license is not confirmed after 48 hours. + +**11. Sahara not available in CA or OR.** +Ameritas IUL not available in NY. All products unavailable in NY. State restrictions must be enforced before showing products in the quoter. + +**12. IUL illustrations require dual e-sign (agent + applicant).** +For Sahara, the illustration generated via WELiS must be e-signed by both the agent and the applicant. This is a carrier compliance requirement and cannot be bypassed. + +--- + +## Needs Validation + +**NV-1 — New AAA migration timeline for remaining products.** +Prime, Choice, Ameritas IUL, and Sahara are still on the legacy consumer-first AAA. Migration timeline to the agent-first experience is not documented. Confirm with IPP Engineering before including migration ETA in downstream PRDs. + +**NV-2 — Agent Config Service entity model.** +The full configuration entity model for Agent Config Service (beyond product enablement and priority order) is not documented. A separate Layer 01 platform overview for Agent Config Service may be warranted. + +**NV-3 — Returning user verification attempt limit.** +The number of verification attempts before an agent is blocked when a returning user fails verification is configurable. Current production value is not documented here. + +**NV-4 — Non-IUL RUW bug fix ship date.** +Fix is confirmed in progress but no ship date is documented. Products depending on correct RUW agent resume behavior should confirm the fix is live before GA. + +**NV-5 — BGA Term (LGA) launch status.** +Target Q2 2026. Agency classification rules and waterfall protection are documented in `ethos-prt/reference/mlm-bga-agency-list.md`. Confirm launch status and exact TRL eligibility expansion before including in any routing documentation. + +**NV-6 — Choice LB rider structure in non-compact states (FL, SD, SC).** +State-specific filing details for FL, SD, SC are not fully documented here. Confirm form and rider structure with Compliance before configuring these states for Choice. + +--- + +## Related PRD templates + +- **Agent Assisted App Experience PRD** (Layer 04 / Layer 05) — core PRD for all native products +- **UW Foundations PRD** — UW decision outcomes passed to AAA +- **ERD Writer PRD** — AAA data model and API contract +- **Agent Contracting PRD (PRT)** — AOR check and license verification, GCR form, carrier contracting rules +- **IDV PRD** — identity verification service used in AAA compliance checks (IDV Layer 01 platform overview not yet created — see PRS NV-1) + +--- + +## Source Documents + +| Document | Repo / Location | Date | Notes | +|---|---|---|---| +| `channels/agent-assisted-application.md` | ethos-prt | 2026-04-06 | Primary source — AAA flow, compliance checks, RUW activation. Author: Kunal Anand | +| `contracting-aor/overview.md` | ethos-prt | 2026-04-09 | AOR system, GCR, carrier contracting, license verification, PA state rules | +| `contracting-aor/pattern.md` | ethos-prt | — | UI/UX patterns across AOR flows | +| `agent-portal/overview.md` | ethos-prt | 2026-03-25 | Agent Portal structure and backend services | +| `agent-portal/quote-and-application.md` | ethos-prt | 2026-03-25 | Quote & Application tab, Agent Config Service, product display logic | +| `quoter/overview.md` | ethos-prt | 2026-04-01 | Product catalog, PRS routing, solve options. Author: Kunal Anand | +| `products/prime/overview.md` | ethos-prt | 2026-05-05 | Prime (LGA/Spirit) — coverage, UW, AOR, BGA Term. Author: Kunal Anand | +| `products/choice/overview.md` | ethos-prt | 2026-04-01 | Choice — coverage, LB riders, foreign national eligibility. Author: Kunal Anand | +| `products/ameritas-iul/overview.md` | ethos-prt | 2026-04-06 | Ameritas IUL — coverage, solve options, contracting. Author: Kunal Anand | +| `products/sahara/overview.md` | ethos-prt | 2026-04-01 | Sahara IUL — coverage, agency contracting, compensation. Author: Kunal Anand | +| `channels/design-reference/aaa-shell.md` | ethos-prt | 2026-04-06 | Consumer-facing AAA shell UI patterns | + +## Change Log + +| Version | Date | Author | Summary | +|---|---|---|---| +| v2.0 | 2026-05-07 | Pankaj Soni | Full draft — sourced from ethos-prt context-docs; covers full AAA flow, AOR/contracting, all products, compliance checks, PRS rerouting |