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 c4897fff388af17bb2fcf6fed265d7c4414c9532 Mon Sep 17 00:00:00 2001 From: Pankaj Soni Date: Tue, 12 May 2026 11:56:53 +0530 Subject: [PATCH 5/5] feat: add L1 platform overview for Microsite Funnel Adds context doc for the MicroSite / Share Quote client-initiated flow covering entry points, product routing, compliance rules, AOR behavior, customer tracking, lifecycle comms, dependencies, and known constraints. Also updates README to mark Microsite Funnel as Draft. Co-Authored-By: Claude Sonnet 4.6 --- layer-01/platform-systems/README.md | 4 +- .../platform-systems/microsite-funnel_v2_0.md | 413 ++++++++++++++++++ 2 files changed, 415 insertions(+), 2 deletions(-) create mode 100644 layer-01/platform-systems/microsite-funnel_v2_0.md diff --git a/layer-01/platform-systems/README.md b/layer-01/platform-systems/README.md index 2527ec0..7ca798b 100644 --- a/layer-01/platform-systems/README.md +++ b/layer-01/platform-systems/README.md @@ -9,8 +9,8 @@ | 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 | +| Agent Assisted App Funnel | agent-assist-funnel_v2_0.md | IPP integrates | Draft | +| Microsite Funnel | microsite-funnel_v2_0.md | IPP integrates | Draft | | 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 | diff --git a/layer-01/platform-systems/microsite-funnel_v2_0.md b/layer-01/platform-systems/microsite-funnel_v2_0.md new file mode 100644 index 0000000..d78f317 --- /dev/null +++ b/layer-01/platform-systems/microsite-funnel_v2_0.md @@ -0,0 +1,413 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: Microsite Funnel (Client-Initiated / Share Quote) +owner_product: Pankaj Soni (IPP Product) +owner_engineering: IPP Engineering — Partnerships +last_updated: 2026-05-12 +status: Draft +source: ethos-prt context-docs — channels/client-initiated-microsite.md, agent-portal/home-page.md, agent-portal/overview.md, quoter/overview.md, customers/customer-list.md, customers/pre-submission.md, customers/post-submission.md, contracting-aor/overview.md, lifecycle-comms.md, products/tawl-gawl, products/beacon-siwl-giwl — Apr 2026 +template_version: 2.0 +--- + +# Microsite Funnel (Client-Initiated / Share Quote) + +## What it is + +The Microsite Funnel covers two distinct self-serve entry points where the **client** drives the application themselves, as opposed to AAA where the agent drives it end-to-end: + +- **MicroSite** — client starts a fresh application from the top of the PRS waterfall, initiated by sharing a personal agent referral link +- **Share Quote** — agent creates a quote in the Agent Portal and shares it with the client; the client completes the full application on the consumer funnel + +The guiding principle is **"funnel is the product"** — optimized for self-serve simplicity and scale. The agent initiates the touchpoint but the client owns and drives the transaction. + +Both entry points run on the **legacy consumer funnel**. When the new agent-first AAA experience was built, client-initiated was deliberately kept on the existing consumer experience. Migration to a new consumer flow is a possible future direction but is not on the current roadmap. + +--- + +## Ownership + +| Responsibility | Owner | Notes | +|---|---|---| +| Product requirements and funnel design | IPP Product (Pankaj Soni) | | +| Consumer funnel build and maintenance | IPP Engineering — Partnerships | Runs on legacy consumer architecture | +| Agent Portal (share link, quote sharing) | IPP Engineering — Partnerships | Agent-side entry point | +| PRS routing | IPP Engineering — Microservices | Routes client through waterfall on MicroSite entry | +| Lifecycle comms triggering | Marketing / Iterable | Client comms sent at key funnel events | + +**Ownership boundary:** IPP Product defines routing logic, product eligibility, and compliance behavior. Engineering owns the consumer funnel build, PRS integration, and client-facing experience. Marketing owns lifecycle comms content and Iterable workflows. + +--- + +## Entry Points + +### MicroSite + +Each agent has a personal referral website (microsite) at: +**`https://agents.ethoslife.com/invite/[agent-code]`** + +The agent shares this link with potential clients via: +- **QR code** — printed materials, in-person meetings +- **Direct URL** — shared verbally, messaging apps, social media +- **Email** — agent emails the URL directly to the client +- **Agent Portal "Share Website" shortcut** — top-right of the home page ("My Business Website" + Share button) + +When the client opens the link, they start a **fresh application from the top of the PRS waterfall**. The Product Routing Service evaluates the client's profile (age, TRL/PreQual score, state, citizenship, etc.) and routes them to the appropriate product. The client does not choose a product — PRS determines it based on eligibility. + +Leads generated through the MicroSite flow directly into the agent's **Customers tab** in the Agent Portal with the status "Website Lead" until the application is progressed. + +### Share Quote + +The agent creates a quote in the Agent Portal (Quote & Application tab) and shares it with the client via: +- **Email** — system sends the quote summary to the client's email address +- **PDF** — agent downloads and shares a quote PDF + +The client receives the quote and — for products that support client-initiated — can complete the full application end-to-end on the consumer funnel, starting from the pre-filled quote details. + +**Critical compliance rule (Share Quote email):** Agents must use the client's actual email address when filling out the application. Use of any other email address may result in coverage being declined or canceled. A persistent non-dismissible amber warning banner is shown below the CTAs on the Share Quote form: *"Please make sure that you use the client's email address when filling out the application. Use of an email address other than the client's email may result in coverage being declined or canceled."* This is a carrier compliance requirement and must be preserved on any feature that collects or pre-fills email in the Share Quote flow. + +### Products: Share Quote available vs. client can complete app + +| Product | Share Quote available? | Client can complete application? | +|---|---|---| +| Prime (LGA / Spirit) | Yes | Yes | +| Choice (Ameritas) | Yes | Yes (P1 fast-follow scope) | +| TAWL / GAWL (TruStage) | Yes | Yes | +| TS Term (TruStage) | Yes | Yes | +| Beacon SIWL / GIWL (Banner Life) | Yes | **No — AAA only** | +| Ameritas IUL (Protection IUL) | Yes | **No — AAA only** | +| Sahara (Accumulation IUL) | Yes | **No — AAA only** | + +For AAA-only products, the agent can share the quote but the client cannot complete the application independently. The application must be completed by the agent via AAA. + +--- + +## Key differences from AAA + +| | AAA | Microsite / Client-Initiated | +|---|---|---| +| Who fills the application | Agent | Client (self-serve) | +| Philosophy | Agent is the product | Funnel is the product | +| Optimize for | Agent productivity | Self-serve simplicity and scale | +| Product routing | Agent selects product from quoter | PRS waterfall determines product (MicroSite); pre-filled from agent quote (Share Quote) | +| AOR / licensing checks | Required at submission and activation | **Not required** | +| Appointment check (PA state) | Required before app start | **Not required** | +| License re-validation at activation | Required (IUL: live; others: bug fix in progress) | **Not required** | +| RUW activation | Agent-mediated via e-sign | Client activates via member portal | +| IDV / AML handling | Agent manages on behalf of client | Client self-serves | +| Returning user flow | Agent drives | Client self-serves | +| Architecture | Legacy (most products) or New AAA (GAWL, Beacon, TS Term) | Legacy consumer funnel (all products) | + +--- + +## Compliance behavior + +Client-Initiated has a substantially lighter compliance footprint than AAA. These lighter rules are intentional: the agent is not acting as an intermediary in the client's transaction, so agent licensing requirements do not apply to the client's self-service actions. + +| Requirement | Microsite / Client-Initiated | AAA | +|---|---|---| +| AOR check at submission | **Not required** | Required | +| AOR check at activation | **Not required** | Required (IUL: live; others: bug fix in progress) | +| Agent license check (Life LOA) | **Not required** | Required | +| Appointment check (PA state) | **Not required** | Required | +| ToF / IDV check | Required — client self-serves | Required — agent manages | +| AML check | Client self-serves | Agent manages (GIACT/TU or TS IDV) | +| OFAC check | Required — automated | Required — automated | +| RUW activation path | Client activates via member portal | Agent-mediated via e-sign | + +**The AAA non-IUL RUW bug fix explicitly does not apply to client-initiated applications.** Client-initiated RUW activation remains with the client via the member portal — this is the correct, intended behavior. + +--- + +## AOR behavior + +- If the **agent is already contracted** when the client submits: the writing agent appears as AOR on policy documents +- If the **agent is not yet contracted** when the client submits: Ethos appears as AOR (Michael Mould placeholder); no compensation block is triggered; no follow-up reminders are sent to the agent + +This is distinct from AAA, where the agent actively manages contracting before and during the application. + +--- + +## MicroSite flow (client journey) + +1. Client opens the agent's referral link (`agents.ethoslife.com/invite/[agent-code]`) +2. Client enters basic details (age, health indicators, state) +3. PRS evaluates eligibility and routes to the appropriate product via the full waterfall +4. Client completes the consumer application (IDV, AML, health interview, UW decision) +5. If approved: client completes checkout (coverage selection, payment details, draft date) +6. If RUW: client is notified and activates via the member portal when the offer is ready +7. Client e-signs and policy activates + +The agent is notified of application progress through the Customers tab and lifecycle comms. + +--- + +## Share Quote flow (agent → client handoff) + +1. Agent creates a quote in the Agent Portal (Quote & Application tab) for the client +2. Agent enters the client's name, email, and phone — this creates a customer record in the Customers tab with status "Quote Generated" +3. Agent shares the quote via email (system-triggered) or PDF download +4. Client receives the quote and opens the consumer funnel link +5. Quote details are pre-filled; client completes the application from there +6. For AAA-only products (IUL, Sahara, Beacon): agent is notified to complete the application via AAA + +--- + +## PRS routing (MicroSite entry) + +The MicroSite always starts at the **top of the PRS waterfall**. PRS evaluates the client in a fixed sequence: + +1. Recommendation rules match (channel, age, TRL/PreQual score, state, citizenship) +2. Static eligibility filtering (PCS: age bands, state approvals, citizenship/visa/document type) +3. Force remove / product override (if applicable) +4. UW and cross-product eligibility (prior declines, cross-ineligibility rules) +5. User and carrier eligibility checks (policy history, PA status, fraud flag) +6. Carrier API eligibility (LGA, Protective/Spirit — real-time carrier check) +7. First eligible product returned + +**MicroSite routing is non-sequential** — PRS can jump across product types based on UW outcomes. Examples: +- A client starting at Prime may be rerouted to Choice, TS Term, TAWL, or GAWL based on TRL score and eligibility +- A client with an elevated risk profile routes directly to TAWL or GAWL without seeing Prime + +For Share Quote, the client starts from the pre-filled product the agent selected; if they are ineligible, PRS reroutes them through the waterfall. + +--- + +## Product-specific microsite behaviors + +### Prime (LGA / Spirit) + +- Client entry via MicroSite routes through PRS waterfall; Prime is presented if client TRL and health profile qualifies (TRL 1–50 for age 20–65 depending on age band) +- If Prime is unavailable (TRL too high, age, state): PRS routes to Choice, TS Term, TAWL, or GAWL +- Client-initiated Prime RUW: client activates via member portal (no agent involvement required) +- APS (Attending Physician Statement) may be requested for applicants age 61+ — client is notified and must provide authorization; typically takes 20 business days + +### Choice (Ameritas) + +- Available via MicroSite and Share Quote; full client-initiated flow supported (P1 fast-follow) +- Living Benefits (Critical, Chronic, Terminal Illness) included at no cost — same rider structure as AAA +- DTC excluded from Choice; this is Partnerships-only via MicroSite/Share Quote +- SoFi and CreditKarma channels excluded; those continue routing to form 3029 without LB +- RUW: client activates via member portal + +### TAWL / GAWL (TruStage) + +- TAWL client-initiated: client self-serves through standard TruStage consumer application +- If TAWL underwriting fails: **auto-pivot to GAWL** (guaranteed issue, no health questions) +- GAWL deferred death benefit: first 2 years = 110% of premiums paid (accidental death only covered in full); full benefit after 2 years +- SSN required — no ITIN support for TruStage products +- TruStage does not return UW reasons to the client; only routing reasons are shown +- Client-initiated TAWL/GAWL apps are **not** migrated to the new agent-first funnel — they remain on the legacy consumer experience +- Reinstatement: policy can be reinstated without a new application if full premium is received within 70 days of paid-to date; otherwise evidence of insurability required + new 2-year contestability period + +### Beacon SIWL / GIWL (Banner Life) + +- **Share Quote available, but client cannot complete the application** — Beacon is AAA-only +- If a client attempts to complete via Share Quote link: they are directed back to the agent to complete via AAA +- Ethos is the TPA for Beacon: owns underwriting, billing (Stripe), eDelivery, member portal; Banner Life handles claims adjudication +- No RUW for Beacon — all decisions instant (100%); SIWL auto-pivots to GIWL on underwriting failure + +### Ameritas IUL / Sahara (Accumulation IUL) + +- **Share Quote available, but client cannot complete the application** — both are AAA-only +- IUL is considered too complex for direct consumer initiation; illustration compliance requires agent + applicant dual e-sign (Sahara) +- If client receives a Share Quote link for IUL: directed back to agent to complete via AAA + +--- + +## Customer records and tracking + +### How microsite leads appear in the Customers tab + +| Source | Initial status in Customers tab | +|---|---| +| Client submits info on agent's MicroSite | "Website Lead" | +| Agent starts a quote, shares with client | "Quote Generated" | +| Client or agent starts application directly | "Started" | + +All three sources create a customer record visible in the Customers tab. Uplines can toggle "Include all downlines" to see the full hierarchy's records. + +### Application statuses (pre-activation) + +| Status | Meaning | +|---|---| +| Website Lead | Client submitted info on agent's MicroSite but has not yet started an application | +| Quote Generated | Quote created; application not yet started | +| Started | Application partially completed | +| Submitted | Application submitted for UW; may have additional requirements | +| Approved | UW approved; awaiting client activation | +| Ready for Carrier Transmission | Agent contracted and licensed; application will be transmitted to carrier by EOD | +| Completed | All requirements done; awaiting policy to flip to Premium Paying | +| Submitted – Decision Pending | Awaiting UW decision from TruStage | +| Submitted for Underwriter Review | Routed to human UW (~5% of cases) | +| Underwriting Requirements Needed | Additional UW requirements needed | +| ETI Required | Underwriter has additional questions; client emailed online form | +| EHR Requested | EHR requested from UW data provider (typically 8–10 business days) | +| APS Requested | APS requested from UW partner (typically 20 business days) | +| Disqualified | Client did not qualify for this product; offer TruStage GAWL | +| Closed | Application closed for administrative reason | +| Declined | Unable to offer coverage to this client | + +### Policy statuses (post-activation) + +| Status | Meaning | +|---|---| +| Premium Paying | Policy in good standing; coverage in force | +| Grace Period | Most recent payment not received; policy at risk of lapse | +| Lapsed | Coverage terminated due to lack of payment | +| Free Look Canceled / Surrendered | Client canceled within the 30-day free look period; refund processed | +| Rescinded | Policy rescinded due to material misrepresentation | +| Renewal Premium Failed | Recurring payment failed; policy may lapse | +| Term Expired | Initial term expired; insured did not renew | + +Full status taxonomy: see `customers/pre-submission.md` and `customers/post-submission.md` in ethos-prt. + +--- + +## Lifecycle comms + +Transactional lifecycle communications (email + SMS) are sent to both agents and clients at key moments in the microsite/client-initiated funnel. All comms are managed through **Iterable** and follow compliance approval workflows with TruStage and internal compliance. + +### Comm audience prefixes + +- **Agent comms**: `AE-` (email) or `AS-` (SMS) +- **Client comms**: `CE-` (email) or `CS-` (SMS) + +### Compliance workflow + +1. Copy drafted (Gretchen) +2. PM review (Aneri/Peter) +3. Compliance review (Anita) — issues ETH-#### code +4. TruStage review (Lori) — issues Ad Trax code (e.g., `TAWL, GAWL, PBT-XXXXXXX.X-MMYY-MMYY`) +5. Build in Iterable (Lavanya) +6. Proof review (Gretchen) + +### Product variants in Iterable + +Many comms have carrier-specific versions: +- **Non-TruStage** (generic/dynamic carrier) +- **TruStage (TS)** — separate Iterable templates due to unique compliance disclosure footers and Ad Trax codes; TruStage footer limitation means Iterable cannot nest dynamic-in-dynamic footers +- **IUL (Ameritas)** — separate flow with Ameritas-specific contact info +- Magic token links used for client-facing CTAs (login, payment, application resume) + +### Style rules for client comms + +- Times: `7 a.m.–6 p.m. CT` +- Spelling: "canceled" (not "cancelled") +- Use "Policy number" (not "Policy ID") in client-facing comms +- Use "Ethos portal" in client comms (not "customer portal" or "client portal") +- Never use "activate" in client comms — replaced with "in force" or "issued" + +### Lifecycle performance context (Q1 2026) + +- 36% of transmitted policies attributed to lifecycle comms (target: 40% in Q2) +- Weekly Pending Customer List (approved) drives highest volume of activation activity +- New agent onboarding lifecycle comms drove portal visits in first 7 days up to 47% (from 39% in Q4 2025) + +--- + +## Dependencies + +| System | Dependency type | Details | +|---|---|---| +| PRS (Product Routing Service) | Upstream — waterfall routing | Routes MicroSite applicants through full product waterfall from the top; evaluates eligibility across all active products | +| PCS (Product Configuration Service) | Upstream — coverage, eligibility, state approvals | Required for PRS to evaluate eligibility; drives which products are available in which states | +| Main App / Consumer Funnel | Runtime — client application surface | Legacy consumer app hosts the full client-initiated application experience | +| Agent Config Service | Upstream — agent referral link | Stores per-agent microsite URL (agent-code) and product priority | +| Agent Portal | Agent-facing surface | Quote creation, Share Quote entry point, Share Website link on home page | +| PAS2 (Policy Admin System) | Downstream — policy activation | Activated policy data flows to PAS2 | +| Member Portal | Downstream — RUW activation | Client activates RUW-approved client-initiated policies via the member portal | +| Iterable | Downstream — lifecycle comms | Triggers email and SMS to agents and clients at key funnel events | +| Underwriting Service | Downstream — RUW | Manual underwriting escalation for applicable products | +| Stripe | Downstream — billing | Initial premium collected via Stripe at checkout | +| Amplitude | Downstream — analytics | Funnel events, drop-offs, activation rates by product and entry point | +| Twilio | Upstream — OTP / LineType | Phone OTP delivery for client IDV; mobile number type verification | +| Persona | Upstream — document IDV | Government ID + selfie fallback when phone OTP path unavailable | +| GIACT / TransUnion | Upstream — AML | Non-documentary AML control for Term products (client self-serves) | + +--- + +## Known constraints + +**1. Legacy consumer funnel — no migration path planned.** +All client-initiated flows run on the legacy consumer architecture. The new agent-first AAA experience does not extend to client-initiated. Migration to a new consumer flow is possible in the future but not on the current roadmap. New product features must be built on or compatible with the legacy consumer funnel for client-initiated scope. + +**2. AAA-only products cannot be completed by the client.** +Ameritas IUL, Sahara IUL, Beacon SIWL, and Beacon GIWL are AAA-only. Agents can share quotes for these products but the client cannot complete the application. Any feature work involving these products must account for the agent handback flow. + +**3. No AOR, no licensing checks.** +Client-initiated applications do not trigger AOR checks, agent license verification, or PA appointment checks at any point — submission or activation. This is intentional and must not be changed without explicit compliance review. + +**4. RUW activation is client-owned.** +For client-initiated applications that go to RUW, the client activates via the member portal. There is no agent involvement in client-initiated RUW activation. This will not change as part of the non-IUL AAA bug fix. + +**5. MicroSite always starts at top of PRS waterfall.** +There is no way for the agent or client to pre-select a product on MicroSite. PRS determines the product based on the client's profile. Agents cannot force a specific product on MicroSite entry. + +**6. TruStage client-initiated apps not on new AAA funnel.** +TAWL and GAWL were migrated to the new agent-first AAA funnel in Q1 2026 for agent-initiated flows. Client-initiated TAWL/GAWL flows remain on the legacy consumer funnel. + +**7. Share Quote email compliance warning is non-dismissible.** +The amber warning banner on the Share Quote form must not be removed or made dismissible. It is a carrier compliance requirement. Any feature touching email collection in the Share Quote flow must preserve this warning. + +**8. TruStage does not return UW reasons.** +For all TruStage products (TAWL, GAWL, TS Term), UW decisions are final and non-appealable. Clients can dispute identity data via LexisNexis or Rx data via ExamOne, but TruStage does not explain specific decision reasons. This limitation applies to both AAA and client-initiated flows. + +**9. TAWL/GAWL SSN only — no ITIN.** +TruStage products do not support ITIN. Clients without SSN are not eligible for TruStage products via MicroSite. + +**10. Choice client-initiated is P1 fast-follow — confirm status.** +Choice full client-initiated application completion is noted as a P1 fast-follow scope item. Confirm with engineering whether this is live before including in downstream product docs. + +--- + +## Needs Validation + +**NV-1 — Choice client-initiated launch status.** +The source docs note client-initiated as a P1 fast-follow for Choice (Ameritas). Confirm with IPP Engineering whether the full client-initiated application flow for Choice is live in production. + +**NV-2 — MicroSite product catalog (which products appear).** +It is not documented which products are shown at the top of the PRS waterfall on MicroSite vs. restricted to the agent-portal-only catalog. Confirm with Engineering and Product whether all Partnerships products are reachable via MicroSite or if some are agent-portal-only. + +**NV-3 — Lifecycle comms triggers for client-initiated specifically.** +The lifecycle comms section above covers the general framework. The specific triggers, templates, and timing for client-initiated events (MicroSite lead created, quote shared, application started by client, client approved, client RUW) are not fully documented here. Confirm the active trigger set with Marketing/Iterable. + +**NV-4 — Foreign national eligibility on MicroSite.** +Foreign national applicants (non-citizens, ITIN holders) routing through MicroSite face different IDV and AML paths. The full foreign national compliance matrix for client-initiated is not documented here — confirm with Engineering which visa/ITIN combinations are supported on MicroSite and whether they reach the full product waterfall or are restricted to specific products. + +**NV-5 — Member portal RUW activation UX.** +The flow for a client activating a RUW-approved client-initiated policy via the member portal is not documented in the source material. Confirm with Engineering and document separately. + +--- + +## Related PRD templates + +- **Consumer (DTC) App Experience PRD** (Layer 04 / Layer 05) — conditional PRD triggered if DTC is in scope; overlaps with client-initiated funnel +- **Agent Assisted App Experience PRD** — primary PRD for agent-driven flows; AAA-only products reference this for Share Quote handback +- **Lifecycle / Marketing Comms PRD** — covers lifecycle comms triggered at key funnel events including MicroSite and Share Quote +- **UW Foundations PRD** — UW decision outcomes surfaced during client-initiated flow + +--- + +## Source Documents + +| Document | Repo / Location | Date | Notes | +|---|---|---|---| +| `channels/client-initiated-microsite.md` | ethos-prt | 2026-04-06 | Primary source — MicroSite and Share Quote overview, AOR behavior, compliance. Author: Kunal Anand | +| `agent-portal/home-page.md` | ethos-prt | 2026-04-22 | Share Website button, MicroSite link, lifecycle-driven agent activity data | +| `agent-portal/overview.md` | ethos-prt | 2026-03-25 | Agent Portal structure, Agent Config Service, microsite URL pattern | +| `quoter/overview.md` | ethos-prt | 2026-04-01 | Share Quote entry point from Quote & Application tab. Author: Kunal Anand | +| `customers/customer-list.md` | ethos-prt | 2026-04-22 | Customer record sources including MicroSite leads, status taxonomy | +| `customers/pre-submission.md` | ethos-prt | 2026-03-24 | Full application status taxonomy (pre-activation) | +| `customers/post-submission.md` | ethos-prt | 2026-03-24 | Full policy status taxonomy (post-activation) | +| `contracting-aor/overview.md` | ethos-prt | 2026-04-09 | AOR behavior for client-initiated (no AOR checks; Ethos as AOR if agent not contracted) | +| `lifecycle-comms.md` | ethos-prt | 2026-03-30 | Lifecycle comms framework, Iterable, compliance workflow, Q1 2026 performance | +| `products/tawl-gawl/overview.md` | ethos-prt | 2026-04-01 | TAWL/GAWL product details, auto-pivot behavior, client-initiated notes | +| `products/beacon-siwl-giwl/overview.md` | ethos-prt | 2026-04-01 | Beacon AAA-only constraint, Ethos TPA model | +| `contracting-aor/pattern.md` | ethos-prt | — | Share Quote email compliance warning pattern | + +## Change Log + +| Version | Date | Author | Summary | +|---|---|---|---| +| v2.0 | 2026-05-12 | Pankaj Soni | Initial draft — sourced from ethos-prt context-docs; covers MicroSite and Share Quote entry points, PRS waterfall, compliance behavior, product-specific rules, lifecycle comms, customer tracking |