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/IPP-Context-Library-Contributor-Guide.md b/IPP-Context-Library-Contributor-Guide.md new file mode 100644 index 0000000..7c9fdcb --- /dev/null +++ b/IPP-Context-Library-Contributor-Guide.md @@ -0,0 +1,353 @@ +# IPP Context Library — Contributor Setup Guide + +> For non-technical contributors who want to create and upload context docs. +> Estimated setup time: 30–45 minutes (one-time). After that, creating a new doc takes ~10 minutes. + +--- + +## What You're Setting Up + +| Tool | What it does | +|---|---| +| **Claude Code** | AI assistant that runs in your terminal — you give it instructions in plain English | +| **GitHub CLI (gh)** | Lets Claude connect to GitHub and upload your files without you touching code | +| **The IPP Context Library repo** | Where all context docs live — `github.com/getethos/ipp-context-library` | + +--- + +## Prerequisites (Before You Start) + +- [ ] You have a **Mac** (this guide is Mac-only) +- [ ] You have a **GitHub account** and have been added to the `getethos` GitHub org +- [ ] You have access to **`getethos/ipp-context-library`** repo (ask Pankaj to add you) +- [ ] You have an **Anthropic account** (claude.ai) — ask Pankaj for the team subscription details or API key + +--- + +## Part 1 — Install Homebrew (Mac Package Manager) + +Homebrew is how we install everything else. Skip this if you already have it. + +**Step 1.1** — Open **Terminal** on your Mac +- Press `Cmd + Space`, type `Terminal`, hit Enter + +**Step 1.2** — Paste this command and press Enter: +``` +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +- It will ask for your Mac password — type it (you won't see the characters, that's normal) and press Enter +- This takes 3–5 minutes. Wait for it to finish. + +**Step 1.3** — When it finishes, run these two lines exactly as shown: +``` +echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc +eval "$(/opt/homebrew/bin/brew shellenv)" +``` + +**Step 1.4** — Verify it worked by typing: +``` +brew --version +``` +You should see something like `Homebrew 4.x.x`. If so, you're good. + +--- + +## Part 2 — Install Node.js + +Claude Code needs Node.js to run. + +**Step 2.1** — In Terminal, run: +``` +brew install node +``` + +**Step 2.2** — Verify: +``` +node --version +``` +You should see `v20.x.x` or similar. + +--- + +## Part 3 — Install Claude Code + +**Step 3.1** — Run: +``` +npm install -g @anthropic-ai/claude-code +``` + +**Step 3.2** — Verify: +``` +claude --version +``` +You should see a version number. + +**Step 3.3** — Start Claude Code for the first time: +``` +claude +``` + +It will ask you to log in. Follow the prompts — it will open a browser to authenticate with your Anthropic/Claude account. + +Once logged in, type `/exit` and press Enter to close Claude for now. + +--- + +## Part 4 — Install GitHub CLI and Connect to GitHub + +**Step 4.1** — Install the GitHub CLI: +``` +brew install gh +``` + +**Step 4.2** — Create a GitHub Personal Access Token (PAT) + +This is like a password that lets the tool talk to GitHub on your behalf. + +1. Go to **github.com → Your profile (top right) → Settings** +2. Scroll down to **Developer settings** (bottom of left sidebar) +3. Click **Personal access tokens → Tokens (classic)** +4. Click **Generate new token → Generate new token (classic)** +5. Give it a name like `ipp-context-library` +6. Set **Expiration** to 90 days +7. Check these boxes: + - ✅ `repo` (all sub-options) + - ✅ `read:org` +8. Click **Generate token** at the bottom +9. **Copy the token immediately** — you won't be able to see it again + +**Step 4.3** — Authenticate the GitHub CLI with your token: +``` +gh auth login +``` + +Follow the prompts: +- Select **GitHub.com** +- Select **HTTPS** +- When asked "Authenticate Git with your GitHub credentials?" → **Yes** +- Select **Paste an authentication token** +- Paste your token and press Enter + +**Step 4.4** — Verify it worked: +``` +gh auth status +``` +You should see your GitHub username confirmed. + +--- + +## Part 5 — Get the IPP Context Library on Your Mac + +**Step 5.1** — Clone (download) the repo to your Desktop: +``` +gh repo clone getethos/ipp-context-library ~/Desktop/ipp-context-library +``` + +**Step 5.2** — Switch to the branch that has all layers and docs: +``` +cd ~/Desktop/ipp-context-library +git fetch --all +git checkout init/scaffold +``` + +**Step 5.3** — Verify all layers are there: +``` +ls ~/Desktop/ipp-context-library/ +``` +You should see: `layer-01 layer-02 layer-03 layer-04 layer-05 README.md` + +**Step 5.4** — Verify the platform system docs are there: +``` +ls ~/Desktop/ipp-context-library/layer-01/platform-systems/ +``` +You should see the existing `.md` files like `agent-assist-funnel_v2_0.md`, `prs_v2_0.md`, etc. + +--- + +## Part 6 — Open Claude Code in the Library + +Every time you want to work on the context library, do this: + +**Step 6.1** — Open Terminal + +**Step 6.2** — Navigate to the library folder: +``` +cd ~/Desktop/ipp-context-library +``` + +**Step 6.3** — Start Claude Code: +``` +claude +``` + +You're now in Claude Code, inside the IPP Context Library repo. Claude can read all the files in the folder and talk to GitHub directly. + +--- + +## Part 7 — How to Read Existing Context Files + +Once you're in Claude Code, just ask in plain English: + +**To see what docs already exist:** +> "Show me what platform system docs exist in layer-01 and their current status" + +**To read a specific doc:** +> "Read the agent-assist-funnel doc and give me a summary" + +**To see what's still outstanding:** +> "What are the outstanding items in the platform systems README?" + +Claude will read the files and respond in plain English. + +--- + +## Part 8 — How to Create a New Context Doc + +### Step 8.1 — Find your source material + +Context docs are built from internal documentation. Your source can be: + +- A **Notion page** (with sub-pages) +- A **PDF, Word doc, or text file** saved on your computer +- A **combination** — e.g., a Notion page plus a downloaded spec PDF + +### Step 8.2 — Tell Claude what to do + +#### Option A — Source is a Notion link + +In Claude Code, give this instruction (adapt it to your doc): + +> "I want to create a new context doc for [system name]. Here is the Notion link: [paste your link]. Read all the sub-pages of that link to get the complete context. Create a new file in `layer-01/platform-systems/` following the same format as the existing docs. Extract only the platform-level behaviors relevant to an AI agent — skip narrow engineering implementation details." + +Claude will: +1. Fetch the Notion page and all sub-pages +2. Extract the relevant content +3. Write a new `.md` file in the right format +4. Show you the file so you can review it + +#### Option B — Source is a file on your computer (PDF, Word, text, etc.) + +**Step 1 — Copy your file into the library folder** + +Open Finder and drag your source file into: +``` +~/Desktop/ipp-context-library/ +``` + +For example, if your file is called `underwriting-spec.pdf`, it should now be at: +``` +~/Desktop/ipp-context-library/underwriting-spec.pdf +``` + +You can drop multiple files if you have more than one source. + +**Step 2 — Tell Claude to read it** + +In Claude Code, give this instruction: + +> "I want to create a new context doc for [system name]. I've added my source files to this folder. Read `underwriting-spec.pdf` (and any other files I've added) to get the full context. Create a new file in `layer-01/platform-systems/` following the same format as the existing docs. Extract only the platform-level behaviors relevant to an AI agent — skip narrow engineering implementation details." + +Claude will read the file(s) directly from the folder and use them as source material. + +**Step 3 — Clean up after (optional)** + +Once the context doc is created and pushed to GitHub, you can delete the source file from the library folder — it was only needed for Claude to read. The source files do not get uploaded to GitHub. + +#### Option C — Source is both a Notion link and local files + +Just combine both in your instruction: + +> "I want to create a new context doc for [system name]. Here is the Notion link: [paste link]. I've also added `product-spec.pdf` to this folder. Read both sources and combine them. Create the context doc following the same format as the existing docs." + +### Step 8.3 — Review the draft + +Read through what Claude created. If something is wrong or missing, just tell it: +> "Add more detail to the payment section" or "Remove the section on deployment — that's too narrow in scope" + +### Step 8.4 — Upload to GitHub + +Once you're happy with the doc, tell Claude: +> "Commit this file and the README update to a new branch and create a pull request on GitHub" + +Claude will: +1. Create a new branch +2. Commit the file +3. Push to GitHub +4. Open a Pull Request for review + +You'll get back a GitHub PR link (e.g., `https://github.com/getethos/ipp-context-library/pull/5`). Share that link with Pankaj for review and merge. + +--- + +## Part 9 — What Happens After You Create a PR + +- The PR goes to Pankaj (or whoever has merge access) for approval +- Once approved, it gets merged into `main` — the doc is now live in the library +- The README status for that system changes from "Outstanding" to "Draft" + +--- + +## Quick Reference — Commands You'll Use Every Time + +```bash +# Navigate to the repo +cd ~/Desktop/ipp-context-library + +# Start Claude Code +claude + +# That's it — everything else is done inside Claude using plain English +``` + +--- + +## Troubleshooting + +**"command not found: brew"** +→ Close Terminal, open it again, and run: +`eval "$(/opt/homebrew/bin/brew shellenv)"` + +**"command not found: claude"** +→ Run `npm install -g @anthropic-ai/claude-code` again + +**"command not found: gh"** +→ Run `brew install gh` again, then close and reopen Terminal + +**GitHub says "authentication failed"** +→ Your token may have expired. Go back to Part 4 Step 4.2 and generate a new one. +→ Then re-run `gh auth login` with the new token. + +**"No such file or directory: ipp-context-library"** +→ The repo isn't cloned yet. Run Part 5 again. + +**Claude says it can't access a Notion page** +→ Make sure the Notion page is shared with your Notion account and is in the `getethos` workspace. If it's restricted, ask the page owner to share it with you. + +--- + +## Context Library Structure (for reference) + +``` +ipp-context-library/ +├── layer-01/ ← Platform knowledge (loaded on every product task) +│ └── platform-systems/ +│ ├── README.md ← Status tracker for all platform docs +│ ├── agent-assist-funnel_v2_0.md +│ ├── microsite-funnel_v2_0.md +│ ├── dtc-funnel_v2_0.md +│ └── [more docs...] +├── layer-02/ ← Product knowledge +├── layer-03/ ← Project/initiative knowledge +├── layer-04/ ← Session context +└── layer-05/ ← Output templates +``` + +**Outstanding** = doc not yet created +**Draft** = doc created, not yet reviewed/validated +**In Review** = under review +**Certified** = reviewed and confirmed accurate + +--- + +*Guide maintained by Pankaj Soni — IPP Product. Last updated May 2026.* 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..1ce43fa --- /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 | Draft | +| 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 | +| 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 | Draft | +| 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/agent-assist-funnel_v2_0.md b/layer-01/platform-systems/agent-assist-funnel_v2_0.md new file mode 100644 index 0000000..553f477 --- /dev/null +++ b/layer-01/platform-systems/agent-assist-funnel_v2_0.md @@ -0,0 +1,668 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: Agent Assisted Application Funnel (AAA) +owner_product: Pankaj Soni (IPP Product) +owner_engineering: IPP Engineering — Microservices / Partnerships +last_updated: 2026-05-07 +status: Draft +source: ethos-prt context-docs — channels/agent-assisted-application.md, contracting-aor/overview.md, contracting-aor/pattern.md, quoter/overview.md, agent-portal/overview.md, agent-portal/quote-and-application.md, products/prime, products/choice, products/ameritas-iul, products/sahara — Apr 2026 +template_version: 2.0 +--- + +# Agent Assisted Application Funnel (AAA) + +## What it is + +The Agent Assisted Application (AAA) is the primary application channel on the Partnerships platform. The agent drives the application end-to-end — quoting, filling the form, handling disclosures, managing IDV, AML, and OFAC checks, and submitting or routing to manual underwriting (RUW). The client participates only at specific consent and verification steps (OTP, e-sign). The guiding principle is **"agent is the product"** — the agent owns the journey and the outcome. This is distinct from Client-Initiated / MicroSite flows, where the consumer drives the application themselves. + +AAA runs across two surfaces simultaneously: +- **Agent Portal** (`agents.getethos.com`) — agent fills the form, reviews UW decisions, monitors status +- **Consumer App** — client receives OTP/e-sign link, completes identity verification, signs disclosures + +The funnel has two architectural generations: +- **Legacy AAA (consumer-first)** — built on top of the consumer application; still active for Prime, Choice, Ameritas IUL, Sahara +- **New AAA (agent-first)** — dedicated agent-first experience (PRD #47); live for GAWL, TS Term, Beacon; all other products migrating incrementally + +Available for all Partnerships products: Prime (LGA/Spirit), Choice (Ameritas), Ameritas IUL, Sahara IUL, TAWL/GAWL, Beacon SI/GI WL. + +--- + +## Ownership + +| Responsibility | Owner | Notes | +|---|---|---| +| Product requirements and funnel design | IPP Product (Pankaj Soni) | | +| Agent Portal build and maintenance | IPP Engineering — Partnerships | | +| Consumer App surface (e-sign, OTP) | IPP Engineering | Consumer-facing side of AAA | +| Agent Config Service | IPP Engineering — Microservices | Controls product enablement and priority order per agency | +| IDV / AML / OFAC compliance checks | IPP Engineering | GIACT, Persona, Twilio, TransUnion integrations | +| AOR / contracting flow | IPP Engineering — Partnerships | GCR form, DocuSign, AgentSync, carrier feeds | + +**Ownership boundary:** IPP Product defines routing rules, compliance check requirements, UW decision handling, and contracting eligibility rules. Engineering owns all service integrations, the Agent Config Service, surface-level build, and carrier feed pipelines. + +--- + +## Inputs required + +Before AAA can be configured for a new product: + +| Input | Provided by | Notes | +|---|---|---| +| Product enabled in Agent Config Service | IPP Engineering | Controls which agents/agencies see the product in the portal; drives featured product display and priority order | +| PRS recommendation rules for the product | IPP Product / Actuarial | Required before routing works in AAA; translated to PRS config via Google Sheet → CSV → Airflow pipeline | +| PCS configuration (coverage, eligibility, state approvals) | IPP Product | Required before quote or application can be generated | +| Carrier IDV / AML requirements | Insurance Team / Compliance | Determines which compliance checks apply per product | +| UW decision outcomes for the product | IPP Engineering / UW | Drives which decision states are surfaced to the agent | +| E-sign and OTP configuration | IPP Engineering | Required for activation path | +| RUW support (if applicable) | IPP Engineering | Required before agent resume of RUW-approved apps is enabled | +| AOR / contracting configuration per carrier | IPP Engineering | GCR form, DocuSign setup, SFTP or feed configuration for the carrier | +| Carrier submission cap (if applicable) | IPP Product | 3-policy cap enforced for most carriers before contracting confirmed | +| PA (Pennsylvania) appointment check configuration | IPP Engineering | Required for any product available in PA | + +--- + +## Outputs produced + +| Output | Destination | Notes | +|---|---|---| +| Started application (policy record) | Main App / PAS2 | Created when agent begins a quote or application | +| Customer record | Customers tab (Agent Portal) | Created on first entry of name, email, phone number | +| Routed product | PRS → Main App | PRS evaluates eligibility and routes to the correct product at application start | +| UW decision | Agent Portal (inline) | Surfaced at post-interview step; reasons shown where available (TruStage products do not return UW reasons; routing reasons shown instead) | +| Activated policy | PAS2 / carrier | Triggered by e-sign completion | +| TX103 (ACORD) | Carrier | New business submission sent to carrier after all pre-transmission checks pass | +| RUW submission | Underwriting Service | Triggered when UW routes to manual review | +| AOR / contracting record | Par system / Salesforce | Written agent NPN appears on carrier submissions and all policy documents after contracting confirmed | +| Analytics events | Amplitude | Funnel drop-offs, e-sign method split, reroute frequency, risk/fraud check pass/fail rates | + +--- + +## Product catalog and entry points + +### Products available in AAA (as of May 2026) + +| Product | Carrier | Coverage | Issue Age | Instant Decision | AAA Architecture | Quote Pattern | +|---|---|---|---|---|---|---| +| Term Life — Prime (LGA) | Banner Life (Legal & General America) | $100K–$2M (age-banded) | 20–65 | ~90% | Legacy | Separate quote + app | +| Term Life — Prime (Spirit) | Protective Life Insurance Company | $100K–$2M (age-banded) | 20–65 | ~90% | Legacy | Separate quote + app | +| Term With Living Benefits — Choice | Ameritas Life Insurance Corp | $50K–$1M (age-banded) | 20–65 | 90% | Legacy | Separate quote + app | +| Ethos Protection IUL (Ameritas IUL) | Ameritas Life Insurance Corp | $25K–$1M (age-banded) | 20–65 | 60%+ | Legacy | Combined quote + app | +| Accumulation IUL (Sahara) | North American Company / SFG | $25K–$2M (age-banded) | 18–65 | ~80% | Legacy | Combined quote + app | +| Final Expense Whole Life (TAWL) | MEMBERS Life Insurance Co. | $5K–$100K | 20–85 | 100% | New AAA | Separate quote + app | +| Guaranteed Acceptance Whole Life (GAWL) | CMFG Life Insurance Co. | $2K–$25K | 45–80 | 100% | New AAA | Separate quote + app | +| Beacon Simplified Issue WL (SIWL) | Banner Life Insurance Co. | $2K–$50K | 45–85 | 100% | New AAA | Separate quote + app | +| Beacon Guaranteed Issue WL (GIWL) | Banner Life Insurance Co. | $2K–$25K | 45–80 | 100% | New AAA | Separate quote + app | +| TruStage® Term Life (TS Term) | MEMBERS Life Insurance Co. | $15K–$300K | 20–69 | 100% | New AAA | Separate quote + app | + +**Not available in New York** for all products. Additional state restrictions: TAWL not available in CT; GAWL not available in WA. + +### Agent Portal — Quote & Application tab + +Products are displayed in two sections: + +**Featured section (top 3):** Determined by the Agent Config Service — the top 3 enabled products based on priority order configured per agency. Same priority logic drives shortcuts on the Home page. Each card shows: product name, description, coverage range, carrier tags, and CTA button(s). + +**All Products section:** All available products in collapsible categories (Term Life, Index Universal Life, Whole Life). Two agents at different agencies may see a different set of featured products and a different default product order. + +### CTA patterns by product + +| Pattern | Products | +|---|---| +| **Create quote** + **Start application** (separate steps) | Prime (LGA/Spirit), Choice, TAWL/GAWL, Beacon, TS Term | +| **Start quote & application** (combined, single flow) | Ameritas IUL, Sahara (Accumulation IUL) | + +--- + +## AAA Flow — Step by Step + +### Step 1 — Quote → Application Handoff + +For separate-flow products (Prime, Choice, TAWL/GAWL, Beacon, TS Term), the agent creates a quote first by entering: Sex, Birth date, Smoking status, Residence, Health class. The quote displays estimated coverage and premium. From the quote, the agent starts the application independently. + +For combined-flow products (Ameritas IUL, Sahara), the agent enters the quote form and proceeds directly into the application without a separate quote-creation step. IUL quote forms also offer multiple solve options: + +- **Ameritas IUL**: Smart Solve™ (default), Maximize Cash Value, More Solves (dropdown) +- **Sahara**: Express Solves (Max Cash Value · Maximize retirement income · Smart Solve™ · Million dollar baby · College savings alternative), Custom Solve, Import an illustration + +Both IUL products surface inline **Frequent Knockout Conditions** panels in the quoter — agents are warned before entering the full application. + +### Step 2 — Pre-Interview: Basic Client Info + +Before the main health interview, the agent completes: + +**a. Soft consent** — agent informs the client of the application process and captures soft consent before proceeding. + +**b. Basic client info** — agent enters: +- Full name, DOB, address, SSN or ITIN +- Driving license (state confirmation) +- LexisNexis prefill surfaces address and phone suggestions; partial SSN prefill available for eligible applicants + +**c. Returning user check** — if the email matches an existing Ethos user, the system prompts client verification using existing profile details. Name and DOB are pre-filled and locked (cannot be changed). Verification attempt limit is configurable. Any open application for the same profile is automatically closed when a new one is started. If verification fails: agent can start a fresh application with a new email. + +**d. Phone number selection** — agent selects from prefilled LexisNexis phone options or enters manually if no prefill is found. For returning users with an existing number, OTP is sent to verify or update it. + +### Step 3 — Pre-Interview Compliance Checks + +Three compliance checks run before the main health interview begins. All three are required before the application can proceed. + +#### ToF Fraud / Identity Check + +| Path | Trigger | Method | +|---|---|---| +| Primary | SMS Disclosure Signature qualifies | Phone OTP via Twilio | +| Fallback | Any SMS criterion fails | Document IDV via Persona (Government ID + selfie) | + +**SMS Disclosure Signature qualification** — phone OTP path is used only if ALL four criteria are met: +1. Client's phone is a mobile number (confirmed via Twilio LineType) +2. Phone is associated with the user via LexisNexis Prefill or Twilio Identity match +3. Non-documentary AML control has passed +4. No government ID upload required by UW (US Resident, or TruStage + SSN) + +If any criterion fails → document-based IDV (Persona) is triggered. + +#### AML Check + +| Product | Primary | Backup | +|---|---|---| +| Term products (Prime, Choice) | GIACT | TransUnion | +| WLFE / TruStage products (TAWL/GAWL) | TS IDV check | — | +| TruStage/TS products | Not applicable | — | + +#### OFAC Check + +Automated for all products and all users. Blocks the application with a visible reason if flagged. + +#### Foreign national handling + +If the client is a non-citizen or non-Permanent Resident, the agent selects the applicable visa/ID type and is shown guidance on required documents. IDV, AML, and UW controls differ: + +| Document Type | ToF Control | AML Control | UW Control | +|---|---|---|---| +| Eligible visa + SSN | Phone OTP (primary) | Non-doc available; Govt ID+Selfie as backup | Visa or EAD required | +| Eligible visa + ITIN | Phone OTP (primary) | Non-doc NOT available; Govt ID+Selfie only | Visa or EAD required | +| EAD only + SSN | Govt ID+Selfie (backup) | Non-doc available; Govt ID+Selfie as backup | EAD required | +| EAD only + ITIN | Govt ID+Selfie only | Non-doc NOT available; Govt ID+Selfie only | EAD required | +| No visa + No EAD + SSN | None | Not applicable — routed to TruStage | — | +| No visa + No EAD + ITIN | — | Non-doc NOT available; Govt ID+Selfie only | UW doc upload not needed | + +**Product eligibility by document type (Choice and Ameritas IUL):** + +| Document Type | Eligible? | Conditions | +|---|---|---| +| SSN + eligible US visa | Yes | — | +| SSN + EAD (no visa) | Yes | No travel outside US within 2 yrs of EAD issue; US resident ≥18 months; US-based medical care + physician visit in past 18 months | +| SSN only (no visa, no EAD) | No | Routed to TruStage | +| ITIN + eligible US visa | Yes | — | +| ITIN + EAD (no visa) | Yes | Same EAD conditions above | +| ITIN only | Yes (Choice/IUL) | Age 25–60; ≥$40K household income; US resident ≥18 months; no travel outside US; US-based medical care + physician visit in past 18 months | + +### Step 4 — AOR / Contracting Check (Agent of Record) + +Before or during the AAA flow, the platform enforces agent contracting and licensing requirements. The check point varies by product and state — it runs at **app start, waterfall routes, and submission/activation**. + +#### What AOR means + +- **Before AOR:** All Ethos policies were submitted under a single internal agent (Michael Mould). The writing agent's NPN was passed alongside but not used as AOR. +- **After AOR:** The writing agent's NPN appears in the carrier API header and on all policy documents. +- **Transition state:** Until an agent completes contracting, Ethos remains the AOR. Exception: Spirit (Protective) uses one signature (Ethos/Michael Mould) until the agent is fully contracted — they do not want two signatures. + +#### Agent eligibility categories + +| Agent type | AOR eligible? | GCR required? | +|---|---|---| +| `consumer`, `agent`, `agency` | Yes | Yes | +| `affiliate` | No | No — Ethos always AOR | +| Referral / Goosehead type | No | No — Ethos always AOR | + +#### Three-ladder contracting model + +**Ladder 1 — GCR status:** + +| Status | Meaning | +|---|---| +| Not applied | Agent hasn't started the GCR form | +| Initiated | Agent started but hasn't completed | +| Completed | GCR submitted; versioned by update date | + +**Ladder 2 — Contracting status (carrier-level):** + +| Status | Meaning | +|---|---| +| Not initiated | Default; agent has not started GCR or DocuSign | +| Started | Agent started GCR form but has not yet signed DocuSign | +| Submitted | DocuSign signed; waiting for carrier confirmation (PA at TruStage only) | +| Active | Agent is contracted and appointed in at least one state | +| Inactive | Carrier marked agent inactive; reinstatement may be possible | +| Carrier Ineligible | Carrier cannot onboard agent; blocks that carrier's products only | +| Terminated | Hard decline — agent cannot sell for that carrier | +| Needs attention | Carrier needs additional info; GCR unlocks for resubmission | +| Expired | Contracting expired by carrier | + +**Ladder 3 — Appointment status (state-level):** +Not applied → Submitted → Confirmed → Declined → Needs attention → Expired + +#### Policy submission cap + +Most carriers enforce a 3-policy cap per agent before contracting is fully confirmed: + +| Carrier / Product | Cap | +|---|---| +| LGA (Banner) — all products (Beacon + Prime share the same count) | 3 policies / agent | +| Protective (Spirit) | 3 policies / agent | +| TruStage — TAWL, SITL, GAWL | 3 policies / agent / TS product (each counted separately) | +| Ameritas IUL | 3 policies / agent | +| Ameritas Choice | No cap | + +The 4th submission is blocked at: Routing page, Quoter, AAA → Client Details, Homepage, Final Look, Thank You page, Settings. Quoting remains allowed; only "Start Application" is disabled. + +#### License verification (AgentSync / NIPR) + +License check (Life LOA) runs via AgentSync on the Final Look page for all products. AgentSync queries NIPR (refreshed daily; ~24-hour lag for new licenses). + +**AgentSync failure modes:** + +| Scenario | Behavior | +|---|---| +| Agent NPN incorrect or name/SSN mismatch | AgentSync returns error; inform agent | +| License found but wrong Line of Authority (not Life LOA) | Submission blocked | +| API failure (NIPR timeout) | Final Look: allow submission (policy → "Ready for Carrier Transmission") | +| NIPR lag (new license, 1–2 day delay) | Background job re-checks every 4–6 hours for up to 48 hours | +| NIPR down/unreachable | Submit allowed; policy → "Ready for Carrier Transmission"; background retries | +| No license confirmed after 48h | Application auto-closes; agent and client notified | + +#### Pennsylvania (PA) — pre-appointment state + +PA is the only pre-appointment state at TruStage launch. It requires formal carrier appointment before an agent can submit their first policy as AOR. Checks run at 3 points: **app start, waterfall routes, submission/activation**. + +**PA flow for Prime (LGA + Spirit):** +1. License check — not licensed in PA → cannot start AAA (can still share quote) +2. Contracting check — if not contracted: + - GCR → DocuSign for Protective first; XML feed sent to Protective (pre-appoints licensed PA agents) + - Then DocuSign for LGA/Banner; XML feed sent to LGA with state = PA +3. Appointment check — contracted but not yet appointed → PA appointment request sent to contracted carriers +4. PRS routing once appointed: agent appointed with Protective only → Spirit products only; LGA only → LGA products only; both → all Prime products available + +**Appointment confirmation by carrier:** +- TruStage: Confirmed via email +- LGA (Banner) / Spirit (Protective): Via XML SFTP feed (state = PA sent in feed); Protective pre-appoints licensed PA agents automatically +- Sahara (North American): Via TX1228 daily feed +- Ameritas IUL: Via SuranceBay +- Ameritas Choice: License check applies; appointment request sent if not appointed + +#### AML training requirement + +Required for: Ethos/Ameritas IUL, Accumulation/Sahara IUL, Beacon (Banner WL), TruStage TAWL, TruStage GAWL. +**Not required for:** LGA Prime, BGA Prime, Protective/Spirit Prime, TruStage Term, Ameritas Choice. + +Validity window: 24 months. Captured via GCR form question flow: +1. "Have you completed AML training within the previous 24 months?" → Yes/No +2. If Yes: "Did you complete on Limra?" → Yes/No + - If Yes: done + - If No: certificate upload required +3. Date selector: "When did you last complete AML training?" (stored as ``) + +If date entered is > 24 months ago: agent is blocked and instructed to complete training before continuing. + +#### State IUL training requirements (Iowa and California) + +Both states require a one-time 4-hour IUL training course before selling indexed products. Certificates do not expire. + +- **Iowa**: State-approved Indexed Product Training required for IUL products (Ameritas IUL, Sahara) +- **California (SB 263)**: Required for agents with licenses issued or renewed on or after 1/1/2024; applies to IUL products only + +#### Carrier outbound feed (contracting requests) + +| Carrier | Method | +|---|---| +| TruStage | Email | +| LGA (Banner Life) | SFTP XML (custom, not ACORD); twice daily at 3:30 AM and 3:30 PM UTC | +| Spirit (Protective) | SFTP XML — same structure as LGA | +| Sahara (North American) | TX1228 Daily Agent Contracting Feed (inbound carrier → Ethos) | +| Ameritas IUL | SuranceBay third-party flow — NOT the standard GCR/DocuSign pipeline | +| Ameritas Choice | Appointment only; not via SuranceBay or GCR/DocuSign | + +### Step 5 — Main Interview + +The agent fills all health history, lifestyle, financial, and beneficiary questions on behalf of the client. Reflexive (follow-up) questions appear inline. UW and routing reasons are surfaced at reroute decision points. For non-Sahara products, payment details can be added before RUW submission. + +**Key interview fields by product:** + +| Category | Prime / Choice | Ameritas IUL | Sahara IUL | +|---|---|---|---| +| Health questions | Standard health interview (APS for age 61+) | Standard + financial history | Knockout guide-aligned | +| Financial history | Moderate | Yes — bankruptcy/foreclosure within 7 years; multiple credit delinquencies are knockout conditions | Standard | +| Beneficiary | Yes | Yes | Yes | +| Riders | N/A | Care4Life LB, Lifetime Income Rider, Waiver, ADB | ADB, Waiver of Monthly Deductions, Flexible Benefit | +| Payment info | Before RUW submission | After illustration review | Monthly/quarterly/semi-annual/annual ACH options | +| Illustrations | N/A | Ameritas PAS system | WELiS Illustration Engine — agent and applicant both e-sign | + +### Step 6 — UW Decision + +| Decision | Description | Applies to | +|---|---|---| +| Approved as applied | Instant approval at quoted class | All products | +| OTAF | Offer To Applicant in Full — approved at applied-for terms | Prime, Choice | +| Approved with adjusted offer | Rate class change or rider modification | Prime, Choice, IUL | +| Product + AD bundle | Approved with Accidental Death rider option | Select products | +| IUL as approved | IUL approval at quoted class | Ameritas IUL, Sahara | +| IUL OTAF (upgraded/downgraded) | IUL approval at adjusted class | Ameritas IUL, Sahara | +| RUW | Referred to Underwriting — manual review required | Prime, Choice, IUL, Sahara | +| IUL → TAWL | IUL declined; rerouted to TruStage Advantage Whole Life | Ameritas IUL, Sahara | +| Hard decline | Not eligible for any Ethos product | All products | + +**Approval rates:** ~90% instant for Prime/Choice; ~60%+ for Ameritas IUL; ~80% for Sahara. +**TruStage products:** Do not return UW reasons; routing reasons shown instead. + +**Choice — Living Benefits at UW decision:** + +| Scenario | LB outcome | +|---|---| +| Table D (4) or better | All 3 riders: Critical, Chronic, Terminal Illness | +| Table E or above | Terminal Illness Rider only (Chronic + Critical declined) | +| CA, age 65+ | No Critical Illness Rider | +| CA, applicant answers "No" to UN 3001 supplement | No Critical Illness Rider; gets Chronic + Terminal | +| LB declined by UW | Terminal Illness Rider only | + +**IUL + Choice bundling (after IUL approval):** + +After Ameritas IUL underwriting approval, agents are offered the option to add a Choice term policy for the same applicant: +- No additional UW questions — IUL approval covers Choice eligibility +- If IUL goes to RUW: Choice consent screen is deferred (P1 scope) +- If IUL is declined: Choice also declined; applicant sent to TruStage +- Beneficiary, payment, and future date information are pre-filled from IUL to Choice +- Policies submitted separately; failure of one does not block the other +- Exclusions: user has an existing active Choice policy; user was previously declined for Choice; max 1 IUL + 1 Choice per person + +### Step 7 — Coverage & Payment + +After approval, the agent reviews a **coverage selector** (standardized for Prime, Choice, and other products post-RUW) and a **premium draft selection page**: + +- Activate today, or future-date up to 30 days out +- Draft dates 27–31 of any month are excluded (billing cycle constraint) +- If future date falls on or after the client's birthday, premium may increase; this must be surfaced to the agent + +**Sahara payment options (Super Solve — PRD #41, live):** +- Monthly ACH (standard) +- Annual premium payments (client pays APP annually upfront) +- Lump sum (one-time at activation; additional lump sums made directly with Ameritas post-activation) + +The agent previews all final policy details before activation. + +### Step 8 — Activation (E-Sign) + +Two activation paths: + +| Path | Who | How | +|---|---|---| +| Client e-sign | Client signs from their device | Agent sends OTP/activation link; client confirms on Consumer App | +| Agent e-sign on behalf of client | Agent signs with client present | Agent uses e-sign flow in Agent Portal | + +Both paths are tracked in analytics to monitor the split between the two methods. AOR re-validation runs at the activation step (live for IUL; part of the non-IUL bug fix for Prime and Choice). + +--- + +## RUW Activation (Post-Approval) + +RUW-approved policies require a separate activation step after the UW team generates an offer. Supported for: Choice, Prime (LGA and Spirit), Ameritas IUL, Sahara IUL. + +### Channel resume rules (by design) + +- **AAA apps:** Only the agent can resume. Client cannot resume an AAA app — ever. +- **Client-initiated apps:** Only the client can resume. Agent cannot resume a client-initiated app — ever. + +### Current state by product + +| Product | Agent Can Resume RUW-Approved AAA | Status | +|---|---|---| +| Ameritas IUL | Yes — via e-sign consent | Working | +| Sahara IUL | Yes — via e-sign consent | Working | +| LGA Prime | No | Known bug; fix in progress | +| Spirit (Protective) | No | Known bug; fix in progress | +| Ameritas Choice | No | Known bug; fix in progress | + +### RUW activation flow (IUL — current working state) + +1. RUW submission — no changes to e-sign/OTP flows at submission +2. UW team generates offer (as-applied or OTAF) via legacy admin portal +3. Agent resumes from Agent Portal +4. Agent sends OTP to client (path 1) or sends activation link to client (path 2) +5. System runs AOR re-validation +6. Policy activated + +**Bug fix in progress (non-IUL):** When shipped: +- Enables agent resume + e-sign activation for Prime and Choice +- Requires e-sign consent (OTP or send-to-client) at agent activation +- Adds AOR re-validation at the activation step +- Blocks client activation of AAA policies via member portal post-RUW + +--- + +## Compliance requirements + +| Requirement | AAA | Client-Initiated | +|---|---|---| +| AOR check | Required at submission; re-validation at activation (IUL: live; non-IUL: part of bug fix) | Not required | +| License check (Life LOA) | Required via AgentSync on Final Look | Not required | +| Appointment check (PA states) | Required before application start | Not applicable | +| ToF Fraud (IDV) | Required — phone OTP (primary) or Persona doc IDV (fallback) | Required | +| AML | GIACT/TU (Term); TS IDV (WLFE) | Client self-serves | +| OFAC | Required — automated | Required | +| AML training (agent) | Required for IUL, TAWL, GAWL, Beacon products | Not applicable | +| IUL training (Iowa / CA) | Required for IUL products; one-time | Not applicable | + +--- + +## Product-level rerouting via PRS + +PRS determines the final issued product based on UW outcomes. Routing is non-sequential — it can jump across product types. + +| Entry product | Routes out to | Trigger | +|---|---|---| +| Prime (LGA/Spirit) | Choice | Exceeds Prime TRL eligibility but within Choice range | +| Prime | TS Term Life | Moderate/high-risk outside Choice eligibility | +| Prime | TAWL/GAWL | Further fallback for applicants not eligible for term products | +| Choice | TruStage | TRL > 95 or FN with SSN only | +| Ameritas IUL | TAWL | Tables 7–10 or manual UW referral | +| Sahara IUL | TAWL | ~20% of applicants not receiving instant IUL approval | +| TAWL | GAWL | TAWL not available or applicant not eligible | + +--- + +## Product-specific AAA behaviors + +### Prime (LGA + Spirit) + +- **Coverage (age-banded):** Age 20–50: $100K–$2M; Age 51–60: $100K–$1M; Age 61–65: $100K–$500K +- **Term lengths:** 10–40 years (varies by age band and tobacco status) +- **UW classes:** Preferred Plus, Preferred, Standard, Table ratings (non-tobacco); Standard, Table ratings (tobacco) +- **APS/EHR:** Required for applicants age 61+ +- **Conversion (Banner Life only):** Client may convert to Life Step UL — the only conversion option across Ethos term products. Not available on Protective policies. +- **BGA Term (LGA only — Q2 2026 launch):** Expanded TRL eligibility, lower PPU pricing, max issue age 60, coverage up to $3M for age 20–50. Available only to BGA-configured agencies. +- **RUW bug:** Agent resume of RUW-approved AAA apps not working for Prime. Fix in progress. + +### Choice (Ameritas) + +- **Coverage (age-banded):** Age 20–50: $50K–$1M; Age 51–60: $50K–$500K; Age 61–65: $50K–$350K +- **Term lengths:** 10–40 years (varies by age and tobacco status) +- **UW classes:** Preferred Plus through Standard; Table ratings 1–10 (non-tobacco); Standard, Table ratings 1–10 (tobacco) +- **Living Benefits at no cost:** Critical, Chronic, and Terminal Illness riders included; requires Table D (4) or better for Chronic/Critical +- **LB acceleration:** 90% of death benefit; APV (Actuarial Present Value) basis — not lien-based +- **State-specific rider structure:** Single combined rider for most states; three separate riders in CA; state-specific filings for FL, SD, SC +- **IUL + Choice bundling:** After IUL UW approval, agent offered Choice for same applicant (no additional UW required) +- **DTC excluded:** Partnerships-only; Ameritas not approved for DTC term + LB +- **SoFi/CreditKarma excluded:** Continue routing to form 3029 without LB +- **No agent appointment change:** No additional appointment beyond standard Ameritas contracting +- **RUW bug:** Agent resume of RUW-approved AAA apps not working. Fix in progress. + +### Ameritas IUL (Ethos Protection IUL) + +- **Coverage (age-banded):** Age 20–50: $25K–$1M; Age 51–60: $25K–$500K; Age 61–65: $25K–$350K +- **Design:** Protection-first, level-to-endow configuration +- **Illustrations:** Ameritas PAS illustration system; not WELiS +- **Riders:** Care4Life ADB (Critical/Chronic/Terminal); Lifetime Income Rider (not available in WA); Overloan Protection; Waiver of Specified Premium; ADB (at cost) +- **Super Solve (PRD #41 — live):** Annual and lump sum payment modes added in addition to monthly +- **Contracting:** AOR flow active but uses SuranceBay (third-party), NOT the standard GCR/DocuSign pipeline +- **Training:** AML + Iowa/CA IUL training required +- **Non-PA states:** Agent can submit before contracting confirmed; TX103 held in "Ready for Carrier Transmission" until contracting confirmed +- **RUW activation:** Working — agent resumes, e-sign consent, AOR re-validation at activation + +### Sahara (Accumulation IUL — North American / SFG) + +- **Coverage (age-banded):** Age 18–50: $25K–$2M; Age 51–60: $25K–$1M; Age 61–65: $25K–$250K +- **Design:** Accumulation-first; Min-Non-MEC-DB, Option B to A — maximizes cash value +- **Illustrations:** WELiS Illustration Calculation Engine; both agent and applicant e-sign the illustration AND the application +- **Riders:** ADB (Critical/Chronic/Terminal); Protected Death Benefit; Overloan Protection; Return of Premium DB Endorsement; Life Perks Rider; Waiver of Monthly Deductions; Flexible Benefit Rider; ADB Rider (not available in CA) +- **Not available in:** NY, CA, OR +- **Agency contracting:** Carrier → Ethos → Agency → Agent (not standard carrier → Ethos → Agent). Each agency requires an `sfgAgencyID` from SFG before any agents can sell Sahara. This is a one-time manual process outside Ethos systems. +- **Compensation:** Instant True-up (ITU) basis; 12-month advance pay cap of $10,000; rolling target premium across multiple years +- **Billing feeds:** TX508 (initial premium), TX1203 (inforce daily), TX1228 (daily agent contracting) +- **Primary distribution:** FFL (Family First Life) and GFI (Global Financial Impact) +- **Training:** AML + Iowa/CA IUL training required +- **RUW activation:** Working — agent resumes, e-sign consent, AOR re-validation at activation + +--- + +## Agent Portal — system context + +| Component | Description | +|---|---| +| Agent Config Service | Stores per-agent and per-agency configuration — product eligibility, product priority order, feature flags, integration settings. Controls featured product display. | +| Partnerships API | Core API layer connecting enterprise onboarding flows, Salesforce, and the portal | +| AgentSync | NPN verification and NIPR licensing data integration | +| Par system | Core backend; source of truth for AOR and controlled policy status | +| Salesforce (SFDC) | Stores contracting status; feeds to Par system | +| DocuSign | Carrier contracting form signing — triggers commission unblock on agent signature | +| Retool | Partner Ops tool — update contracting status, disable commission blocks, manage PA appointments manually | +| Ironclad | Metadata storage for signed contracting forms (timestamp, PDF copy) | + +**Portal navigation relevant to AAA:** + +| Nav item | Description | +|---|---| +| Quote & Application | Product selector; entry point for starting quotes and applications | +| Customers | Full list of leads, quotes, and policy records; CRM-lite with notes and tasks | +| Settings → Carrier Contracting | Agent's per-carrier contracting status, appointment states, and action items | + +--- + +## Dependencies + +| System | Dependency type | Details | +|---|---|---| +| Agent Config Service | Upstream | Controls product enablement and priority order per agency | +| PCS (Product Configuration Service) | Upstream | Coverage, eligibility, state approvals — required before quote or application | +| PRS (Product Routing Service) | Upstream | Routes applicant to correct product at application start; determines final issued product | +| Main App | Runtime | AAA application data flows into and is managed by Main App | +| Consumer App | Runtime — client surface | Client receives OTP/e-sign link; completes IDV, disclosures, activation | +| LexisNexis | Upstream — prefill | Address, phone, partial SSN prefill at pre-interview step | +| Persona | Upstream — document IDV | Government ID + selfie when phone OTP path is not available | +| GIACT / TransUnion | Upstream — AML | Non-documentary AML control for Term products | +| Twilio | Upstream — OTP / LineType | Phone OTP delivery; mobile number type verification | +| AgentSync / NIPR | Upstream — license verification | Life LOA confirmation; 24h NIPR refresh lag | +| DocuSign | Upstream — contracting | Carrier contracting form signing; commission unblock trigger | +| WELiS | Upstream — illustrations (Sahara) | IUL illustration calculation engine for Sahara/North American products | +| Ameritas PAS | Upstream — illustrations (Ameritas IUL) | Illustration system for Ethos Protection IUL | +| PAS2 (Policy Admin System) | Downstream — policy activation | Activated policy data flows to PAS2 | +| Underwriting Service | Downstream — RUW | RUW submission routed to UW team for manual review | +| Par system | Downstream — AOR | Source of truth for AOR and controlled policy status | +| Salesforce | Downstream — contracting | Contracting status stored; feeds to Par system | +| Optimizely | Runtime — feature flags | Used for AAA migration rollouts and treatment experiments | +| Amplitude | Downstream — analytics | Funnel events, e-sign split, reroute frequency, fraud check pass/fail rates | +| Stripe | Downstream — initial premium | Initial premium charged via Stripe after activation | + +--- + +## Known constraints + +**1. Legacy AAA architecture for most products.** +Prime, Choice, Ameritas IUL, and Sahara remain on the consumer-first legacy AAA. The agent-first migration (PRD #47) is incremental. New products should target the new AAA experience. + +**2. Non-IUL agent resume of RUW-approved apps is broken.** +Prime (LGA + Spirit) and Choice agents cannot resume RUW-approved AAA apps from the portal. Clients are using the member portal as a workaround — this is incorrect behavior. Fix is in progress. When shipped: enables agent resume, adds e-sign consent at activation, adds AOR re-validation, and blocks client activation of AAA policies post-RUW. + +**3. Client cannot resume an AAA app.** +By design. Any AAA app started by an agent must be resumed by the agent. There is no client-resume path for AAA. Conversely, agents cannot resume client-initiated apps. + +**4. Draft date exclusions.** +Dates 27–31 of any month are excluded from premium draft selection (billing cycle constraint). New products must account for this in activation UX. + +**5. Birthday premium increase.** +If the activation future date falls on or after the client's next birthday, the premium may increase. This must be surfaced to the agent in the coverage/payment step. + +**6. SMS Disclosure qualification is a 4-criteria gate.** +Failure of any single criterion routes to document IDV (Persona), which has higher drop-off. Foreign national flows have limited or no phone OTP path depending on document type. + +**7. AOR re-validation at activation (non-IUL).** +Once the non-IUL bug fix ships, AOR re-validation will be required at the activation step — consistent with the IUL flow. Products going live before the fix ships should plan for this requirement. + +**8. Sahara requires agency-level contracting with SFG before any agents can sell.** +The agency must obtain an `sfgAgencyID` from SFG/North American directly. This is a one-time manual process outside Ethos systems. It is a prerequisite for the AOR flow to work for any agent at that agency. + +**9. Ameritas IUL uses SuranceBay (non-standard contracting pipeline).** +Ameritas IUL contracting is not integrated into the standard GCR/DocuSign pipeline. End-to-end AOR standardization for Ameritas IUL is not on the current roadmap. + +**10. NIPR 24-hour lag.** +New licenses may not be visible in NIPR for up to 24 hours. Background job retries every 4–6 hours for up to 48 hours. Applications auto-close if license is not confirmed after 48 hours. + +**11. Sahara not available in CA or OR.** +Ameritas IUL not available in NY. All products unavailable in NY. State restrictions must be enforced before showing products in the quoter. + +**12. IUL illustrations require dual e-sign (agent + applicant).** +For Sahara, the illustration generated via WELiS must be e-signed by both the agent and the applicant. This is a carrier compliance requirement and cannot be bypassed. + +--- + +## Needs Validation + +**NV-1 — New AAA migration timeline for remaining products.** +Prime, Choice, Ameritas IUL, and Sahara are still on the legacy consumer-first AAA. Migration timeline to the agent-first experience is not documented. Confirm with IPP Engineering before including migration ETA in downstream PRDs. + +**NV-2 — Agent Config Service entity model.** +The full configuration entity model for Agent Config Service (beyond product enablement and priority order) is not documented. A separate Layer 01 platform overview for Agent Config Service may be warranted. + +**NV-3 — Returning user verification attempt limit.** +The number of verification attempts before an agent is blocked when a returning user fails verification is configurable. Current production value is not documented here. + +**NV-4 — Non-IUL RUW bug fix ship date.** +Fix is confirmed in progress but no ship date is documented. Products depending on correct RUW agent resume behavior should confirm the fix is live before GA. + +**NV-5 — BGA Term (LGA) launch status.** +Target Q2 2026. Agency classification rules and waterfall protection are documented in `ethos-prt/reference/mlm-bga-agency-list.md`. Confirm launch status and exact TRL eligibility expansion before including in any routing documentation. + +**NV-6 — Choice LB rider structure in non-compact states (FL, SD, SC).** +State-specific filing details for FL, SD, SC are not fully documented here. Confirm form and rider structure with Compliance before configuring these states for Choice. + +--- + +## Related PRD templates + +- **Agent Assisted App Experience PRD** (Layer 04 / Layer 05) — core PRD for all native products +- **UW Foundations PRD** — UW decision outcomes passed to AAA +- **ERD Writer PRD** — AAA data model and API contract +- **Agent Contracting PRD (PRT)** — AOR check and license verification, GCR form, carrier contracting rules +- **IDV PRD** — identity verification service used in AAA compliance checks (IDV Layer 01 platform overview not yet created — see PRS NV-1) + +--- + +## Source Documents + +| Document | Repo / Location | Date | Notes | +|---|---|---|---| +| `channels/agent-assisted-application.md` | ethos-prt | 2026-04-06 | Primary source — AAA flow, compliance checks, RUW activation. Author: Kunal Anand | +| `contracting-aor/overview.md` | ethos-prt | 2026-04-09 | AOR system, GCR, carrier contracting, license verification, PA state rules | +| `contracting-aor/pattern.md` | ethos-prt | — | UI/UX patterns across AOR flows | +| `agent-portal/overview.md` | ethos-prt | 2026-03-25 | Agent Portal structure and backend services | +| `agent-portal/quote-and-application.md` | ethos-prt | 2026-03-25 | Quote & Application tab, Agent Config Service, product display logic | +| `quoter/overview.md` | ethos-prt | 2026-04-01 | Product catalog, PRS routing, solve options. Author: Kunal Anand | +| `products/prime/overview.md` | ethos-prt | 2026-05-05 | Prime (LGA/Spirit) — coverage, UW, AOR, BGA Term. Author: Kunal Anand | +| `products/choice/overview.md` | ethos-prt | 2026-04-01 | Choice — coverage, LB riders, foreign national eligibility. Author: Kunal Anand | +| `products/ameritas-iul/overview.md` | ethos-prt | 2026-04-06 | Ameritas IUL — coverage, solve options, contracting. Author: Kunal Anand | +| `products/sahara/overview.md` | ethos-prt | 2026-04-01 | Sahara IUL — coverage, agency contracting, compensation. Author: Kunal Anand | +| `channels/design-reference/aaa-shell.md` | ethos-prt | 2026-04-06 | Consumer-facing AAA shell UI patterns | + +## Change Log + +| Version | Date | Author | Summary | +|---|---|---|---| +| v2.0 | 2026-05-07 | Pankaj Soni | Full draft — sourced from ethos-prt context-docs; covers full AAA flow, AOR/contracting, all products, compliance checks, PRS rerouting | diff --git a/layer-01/platform-systems/dtc-funnel_v2_0.md b/layer-01/platform-systems/dtc-funnel_v2_0.md new file mode 100644 index 0000000..ade8706 --- /dev/null +++ b/layer-01/platform-systems/dtc-funnel_v2_0.md @@ -0,0 +1,248 @@ +--- +layer: 01 — Platform Knowledge +type: Platform System +system: DTC Application Funnel (Direct-to-Consumer) +owner_product: Ash Muralidharan (Consumer Product) +owner_engineering: Gaurang Khetan (Consumer Engineering) +last_updated: 2026-05-12 +status: Draft +source: Notion — Consumer Org page and sub-pages (Main App flows, BoF Statuses, Consumer Payments, Activation, PreInterview Cleanup, Payment Processing Flow, ConsolidatedCheckoutV2, Returning User Flow) — May 2026 +template_version: 2.0 +--- + +# DTC Application Funnel (Direct-to-Consumer) + +## What it is + +The DTC Application Funnel is Ethos's self-serve online life insurance application experience at **`app.ethoslife.com`**. Customers arrive organically from marketing landing pages at `www.ethoslife.com` (CMS) and complete the entire application without agent involvement. The funnel covers the full journey from the first question through underwriting decision, payment, and policy activation. + +The DTC funnel is owned and operated by the **Consumer org**. It is separate from the Agent Assisted Application (AAA) channel and the client-initiated Microsite/Share Quote channel, though it shares underlying infrastructure (PRS, UW, Stripe/GIACT payments, carrier transmit systems). + +--- + +## Ownership + +| Responsibility | Owner | +|---|---| +| Product strategy and roadmap | Ash Muralidharan (Consumer Product) | +| Engineering leadership | Gaurang Khetan (Consumer Engineering) | +| STL | Prassath Leelakrishnan | +| Analytics | Gopi Ramesh | +| Design | Raffi Feinstein, Kelly LaFleur | +| Payments sub-team | Aron San (PM), Michael Mata (EM) | +| Activation sub-team | Soumya Santhanakrishnan (PM), Michael Mata (EM) | + +**Consumer Slack:** `#consumer-team`, `#consumer-bugs`, `#consumer-bugs-high-priority` +**Deployment schedule:** Tuesday and Thursday (IST handles Tuesday; US hours handles Thursday) + +--- + +## How It Is Triggered + +1. User lands on a marketing or SEO page at **`www.ethoslife.com`** (CMS — `cms-next` repo) +2. User clicks a CTA (e.g., "Get my estimate", "Check my price") +3. CMS redirects to **`app.ethoslife.com`** with a `?flow=` query parameter that determines which Pre-Interview flow the user enters (see Pre-Interview Flows below) +4. If no flow parameter is provided, users default to the `nap-recommendation` flow (standard Term product path) + +--- + +## DTC Funnel Flow + +### Step 1 — Pre-Interview + +The Pre-Interview collects lightweight qualification data before the full interview. Questions vary by flow (see Pre-Interview Flows section). Key questions collected in most flows: + +- Name, email, date of birth, gender, zip code, citizenship status +- Health/lifestyle signals used for eligibility routing and product recommendation + +Flow is stored in the `lead` object in browser session during Pre-Interview. Once a policy is created, flow is persisted to the database (`clientData` on the policy record) and is the authoritative source thereafter. + +### Step 2 — Product Routing (PRS) + +After the email question, PRS evaluates the user's profile to determine product eligibility. For the DTC funnel, PRS runs the full waterfall from the top (same as MicroSite). If the user qualifies for multiple products, PRS routes to the highest-priority eligible product. + +### Step 3 — Main Interview + +Full health, lifestyle, and beneficiary questionnaire. Question set varies by product and carrier. + +### Step 4 — Underwriting Decision + +- **Instant approval** — most products; decision returned immediately +- **Instant decline** — application rejected; user may be offered product alternatives via PRS rerouting +- **Manual (RUW) review** — LGA Prime only; application submitted to manual underwriting queue + +If declined on one product, PRS may reroute the user to an alternative product and re-present an application opportunity. + +### Step 5 — Checkout / Payment + +User reaches the checkout page ("Final Look") to confirm coverage and enter payment details. Two payment methods are supported: + +**Credit Card (CC)** +- Stripe Elements collect and tokenize CC details in the browser (SAQ-A PCI DSS compliant — CC data never touches Ethos servers) +- Token sent to backend → payment method attached to Stripe customer profile → stored in `Payor` object +- Ethos charges the card immediately; instant success/failure response +- Success → proceed to activation; Failure → user blocked, must re-enter payment + +**ACH (Bank Account)** +- User enters bank routing + account number +- **GIACT** verifies bank account ownership and validity +- Bank details tokenized → Stripe profile → stored in `Payor` + `PayorInfo` objects +- Ethos initiates ACH charge; returns **pending** status (not instant) +- User proceeds to the member portal; actual success/failure resolves in 3–5 business days + +**Payment administration by product:** +- **Ethos-administered (Stripe):** LGA Term (Prime/Choice), most standard term products +- **Carrier-administered:** IUL, AD — Ethos collects bank details and passes them to the carrier; carrier handles all charging +- **TruStage Native (TSN) 1st premium:** Tokenization happens server-side (not via Stripe Elements); Ethos charges the first premium only, then passes details to the carrier for recurring billing + +### Step 6 — Policy Activation + +Activation = the point at which a policy goes into force. + +| Scenario | Behavior | +|---|---| +| Instant policy, CC payment success | Activated immediately at submission | +| Instant policy, ACH payment | Activated after ACH clears (~3–5 days) | +| Forward-dated policy | Transmitted at submission; activated on the chosen future effective date (max 30 days ahead) | +| LGA Prime RUW | Submitted to manual UW queue; activated only after manual approval | +| CC payment failure | Blocks activation; user must correct payment | +| ACH failure post-activation | Policy becomes **Unissued**; user must re-enter payment credentials | + +--- + +## Pre-Interview Flows + +Flows are defined in the monorepo at: +`frontend/src/main/InsuranceApp/PreInterview/constants/flows.ts` + +| Flow name | Products | Entry point | Notes | +|---|---|---|---| +| `nap-recommendation` / `trustage-native` | Prime (LGA/Spirit), Choice (Ameritas) | Default — most CMS traffic | Standard term product path; most users | +| `final-expense` | TAWL / GAWL (TruStage) | CMS Final Expense pages | Shorter question set | +| `iul-instant` | Ameritas IUL | Partnerships activation | ~2K users/month; cannot remove | +| `returning-user` | All products | App login flow | Resumed applications for existing accounts | +| `iul-d2c-p2` | IUL D2C phase 2 | Consumer app | IUL secondary flow | +| `new-policy` | All products | Member portal (2nd policy) | Used for second-policy creation; Member Portal dependency | +| `trustage-native` | TruStage Term | TruStage Partnerships | Reuses `NAP_RECOMMENDATION_FLOW` directly | + +Flow switching logic lives in: +`frontend/src/main/InsuranceApp/PreInterview/helpers/getUserFlow.ts` + +--- + +## Application Statuses (Bottom of Funnel) + +| Status | Meaning | +|---|---| +| **Decisioned** | Application received an approved or declined UW decision | +| **Submitted** | Application completed and sent; for RUW policies = sent to manual UW queue | +| **Transmitted** | Application sent to carrier; for instant policies this coincides with Submitted and Activated | +| **Activated** | Policy is in force; effective date is set | +| **Unissued** | ACH credentials were invalid; policy reverts to Submitted state; user must re-enter payment (~2–7 days post-activation) | + +For **instant policies** (all products except LGA Prime RUW): Submitted, Transmitted, and Activated occur at the same time. + +--- + +## Returning User Behavior + +Users with an existing Ethos account who return to `app.ethoslife.com` are identified at the email question and routed to a login flow: + +- **Verified phone number on file** → SMS OTP verification +- **No verified phone** → Email OTP verification +- **CIO token** (from lifecycle email link) → same OTP flow based on phone verification status; first-time CIO login uses original verification (phone + zip) + +Controlled by Optimizely feature flag: `improved_login_experience_flow` + +--- + +## Checkout Architecture + +The DTC funnel checkout page ("Final Look") is built on top of a shared `ConsolidatedCheckout.tsx` component in the monorepo. An active migration (`ConsolidatedCheckoutV2`) is in progress to split this monolith into per-product checkout components: + +| Carrier | Product | V2 component | +|---|---|---| +| LGA | Term (Prime) | `LgaTermConsolidatedCheckoutV2` *(in progress)* | +| Ameritas | Choice | `AmeritasChoiceConsolidatedCheckoutV2` | +| Ameritas | SI | `AmeritasSimplifiedConsolidatedCheckoutV2` | +| Ameritas | IUL | `AmeritasIulConsolidatedCheckoutV2` | +| Protective | Spirit | `ProtectiveSpiritConsolidatedCheckoutV2` | +| TruStage | TSN Term | `TrustageTermConsolidatedCheckoutV2` | +| TruStage | TAWL/GAWL | TBD | + +State management in V2 uses **Zustand** scoped per checkout session, replacing Redux prop-drilling. Each product checkout exposes atomic selector hooks and an `actions` hook for UI state (loading, modals, payment submission). + +**Active checkout modals:** +- `SsnFormModal` — collects SSN for LGA Term when not yet verified +- `InstantCheckoutPackageSelectModal` — lets users edit coverage (face amount, term length) +- `AflacPaymentModal` — Aflac bundle payment capture +- `EffectiveDatePickerModal` — forward-date policy selection + +--- + +## Dependencies + +| System | Role | +|---|---| +| CMS (`www.ethoslife.com` / cms-next) | Landing pages; drives traffic with `?flow=` parameter | +| Product Routing Service (PRS) | Routes user to eligible product; re-routes on UW decline | +| Underwriting (UW 2.0) | Issues instant approval/decline decisions | +| Stripe | CC tokenization, charging, payment method management | +| GIACT | ACH bank account verification and ownership validation | +| Profile Service | Stores and verifies user phone numbers for returning user OTP | +| Optimizely | Feature flags and A/B experimentation across funnel | +| Amplitude | Behavioral analytics; flow and conversion tracking | +| Segment | Analytics event pipeline | +| Iterable (CIO) | Lifecycle comms; CIO token-based login links | +| Carrier transmit systems | Receive policy data at activation (LGA, Ameritas, Protective, TruStage) | +| Member Portal | Destination post-activation; surfaces policy status and payment management | +| Policy Admin System (PAS2) | Manages recurring invoicing and payment status | + +--- + +## Known Constraints + +1. **No agent in the DTC flow** — No AOR, no licensing check, no contracting requirement. If a user was referred by an agent (MicroSite/Share Quote), those flows are handled by the Microsite Funnel doc, not DTC. +2. **Flow is browser-session-scoped until policy creation** — If a user clears session storage before completing the application, `lead` (including flow) is lost. Flow is only reliably DB-persisted after a policy record is created. +3. **CC instant / ACH pending asymmetry** — CC gives immediate activation confirmation; ACH requires a 3–5 day settle window. Products that require confirmed payment before activation cannot guarantee same-session activation for ACH users. +4. **Unissued risk for ACH** — Incorrect ACH credentials are not caught until the charge attempt 2–7 days post-activation. The policy moves to Unissued and the user must re-enter payment. +5. **LGA Prime RUW is not instant** — Manual underwriting queue means these policies do not follow the standard instant-transmit-activate path. Activation can take days to weeks. +6. **Forward-date limit** — Effective date can be set no more than 30 days in advance of application submission date. +7. **ConsolidatedCheckout.tsx migration risk** — The legacy checkout monolith (3K+ lines) handles multiple products/carriers simultaneously. Changes intended for one product can affect others. The V2 migration is in progress but incomplete; any checkout changes must account for the monolith until product-specific V2 components are live. +8. **IUL and AD payment passthrough** — For IUL and AD products, Ethos does not administer payments. Bank details are passed to the carrier. Ethos has no visibility into recurring payment success/failure for these products. +9. **Prepaid cards blocked** — Prepaid cards are blocked as a payment method across all products. +10. **TSN first premium** — TruStage Native is charged for the first premium by Ethos (server-side tokenization), then carrier handles recurring. This differs from the standard Stripe Elements path. + +--- + +## Needs Validation + +1. **PRS rerouting scope on DTC decline** — Confirm which products PRS can reroute to after a DTC decline, and whether the reroute experience is the same as MicroSite reroute behavior. +2. **ACH failure notification** — Confirm what happens to lifecycle comms (Iterable) when a policy becomes Unissued — whether the user is automatically notified and through what channel. +3. **CIO token login behavior** — Confirm whether the first-time CIO token login always uses the original phone+zip verification or whether there are cases where it skips directly to SMS OTP. +4. **TAWL/GAWL checkout V2 timeline** — ConsolidatedCheckoutV2 migration plan for TAWL/GAWL is listed as TBD; confirm current checkout path and any IPP-relevant changes planned. + +--- + +## Source Documents + +| Document | Type | Notes | +|---|---|---| +| Notion — Consumer Org page | Notion | Team contacts, tech stack, communication channels | +| Notion — Main App flows (1) | Notion | Pre-Interview flow definitions, routing, analytics | +| Notion — Bottom of Funnel (BoF) Statuses | Notion | Application status taxonomy | +| Notion — Consumer Payments | Notion | Payment team, feature history | +| Notion — Payment Processing Flow Documentation | Notion | CC/ACH/GIACT checkout flow detail | +| Notion — Overview of Ethos Payments process | Notion | High-level payment overview by product | +| Notion — Activation | Notion | Activation team and sub-team contacts | +| Notion — PreInterview Cleanup, Migration & Performance Plan | Notion | PreInterview architecture, flow routing, V2 migration roadmap | +| Notion — ConsolidatedCheckoutV2 Migration Guide | Notion | Checkout architecture, per-product V2 breakdown, modal inventory | +| Notion — Returning User Flow v2 | Notion | Login/OTP flow behavior | + +--- + +## Change Log + +| Version | Date | Author | Summary | +|---|---|---|---| +| v2.0 | 2026-05-12 | Pankaj Soni | Initial draft from Consumer Notion pages | 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 | 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..d328899 --- /dev/null +++ b/layer-01/platform-systems/pcs_v2_0.md @@ -0,0 +1,170 @@ +--- +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 (`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) | 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 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 — 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; 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 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: 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 — 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.** 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 + +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 | 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 | + +### 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 + +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 + +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 + +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/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/platform-systems/prs_v2_0.md b/layer-01/platform-systems/prs_v2_0.md new file mode 100644 index 0000000..e8e0c5c --- /dev/null +++ b/layer-01/platform-systems/prs_v2_0.md @@ -0,0 +1,543 @@ +--- +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 + +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 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 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 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 (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). | + +--- + +## 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. + +**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. + +--- + +## Product type variations + +| Product type | Behavior | Notes | +|---|---|---| +| 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. 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. 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. | + +--- + +## 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 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 — 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 — 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 — 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 — 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. + +--- + +## Age calculation + +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). + +--- + +## Dependencies + +| System | Dependency type | Details | +|---|---|---| +| 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. | + +--- + +## 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. + +**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. 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. 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 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:** + +| 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 | + diff --git a/layer-01/platform-systems/uw2_v2_0.md b/layer-01/platform-systems/uw2_v2_0.md new file mode 100644 index 0000000..41d00bc --- /dev/null +++ b/layer-01/platform-systems/uw2_v2_0.md @@ -0,0 +1,404 @@ +# Underwriting (UW 2.0) — Platform System Context + +**Version:** v2.0 +**Last updated:** 2026-05-13 +**Context owner:** Pankaj Soni +**IPP relationship:** IPP integrates +**Status:** Draft + +## 1. System Overview + +UW 2.0 is Ethos's automated underwriting platform. It orchestrates the interview, evidence ordering, rules evaluation, and decision generation for all life insurance products. The system is a set of discrete services that communicate sequentially to produce an underwriting decision. + +**Service chain:** +``` +Main App → Question Engine (QE) → Maestro → Dante → Janus → Parsi + ↕ ↕ + Decision Service [S3 evidence store] + ↕ + Nora (manual RUW + PIA) +``` + +| Service | Role | +|---------|------| +| **Question Engine (QE)** | Conducts the underwriting interview. Interview tree is dynamic (adapts based on answers), product-specific, and identified by an interview ID stored in the consumer env var. | +| **Maestro** | Central orchestrator. Invoked at policy creation. Orders evidence progressively via Dante, applies rules, produces soft and final decisions. Stores decisions in Decision Service. | +| **Dante** | Third-party evidence ordering service. Issues requests to MIB, MVR (TransUnion), Rx (Milliman), Criminal Records (Sherlock), AUTO_MEDICAL_CLAIMS. Stores raw XML responses in S3; triggers SNS/SQS notification on completion. | +| **Parsi** | Evidence parsing and transformation. Converts raw evidence XML into standardized "facts" (data points) and "attributes" (metadata) used by Janus. | +| **Janus** | Carrier-specific rules engine. Evaluates facts/attributes against rules to produce decision outcomes. Rules are authored separately per carrier and product. | +| **Nora** | Manual underwriter workbench for RUW cases and PIA (Post Issue Audit). Manual underwriters view all evidence and make decisions here. Tight integration with Maestro for ordering additional evidence (e.g., APS — no direct API, manually retrieved by case manager). | +| **Decision Service** | Central repository for all decisions (automated + manual). Unified schema used by Maestro, Nora, and consumers. Source of truth for all policy decision history. | + +**Team ownership:** UW 2.0 is owned by the Risk Platform / UW Platform team. IPP (and Consumer) integrates as a consumer of QE interview outputs and Decision Service data. + +--- + +## 2. IPP Touchpoints + +| Touchpoint | Description | +|------------|-------------| +| Interview initiation | Main App calls Maestro's create-policy API when user starts the interview; also calls QE's start-interview with the product-specific interview ID | +| Soft decision checks | Main App calls `get soft decision` twice during the interview — once after medical questions and once at end. If soft decision is trending toward decline, applicant is routed to an alternative eligible product. `start UW` (evidence pull) is only called if soft decision is trending approval. | +| Hard decision (get decision) | After interview completes, Main App calls get-decision; Maestro pulls all evidence, applies rules, and returns a final decision | +| Decision consumption | IPP reads decisions from Decision Service (by policyId) to determine application status, coverage offer, health class, and next steps | +| Product routing on decline | On decline, Main App redirects user to an alternative product based on eligibility criteria from predefined rules | +| Instant checkout | On approval, Main App offers instant checkout | +| PIA sampling | After policy activation, IPP applications are sampled for Post Issue Audit per product-specific rates; PIA decisions can override the original Final decision post-activation | +| Prior policy lookback | UW checks prior policies (same SSN) within an 18-month window; decisions from prior applications can cap coverage or force RUW/Decline on the new application | + +--- + +## 3. Key Behaviors + +### 3.1 Interview (Question Engine) + +- Interview tree is **dynamic** — questions adapt based on prior answers (reflexive questions) +- Each product has its own interview ID; the interview ID is hardcoded in the consumer env var. It can be changed without a code deploy (ArgoCD restart is sufficient). +- Example: interview ID 5002 = LGA Prime; 5003 = another product +- QE responds in "ask" format: includes question text, question type, options, section info, metadata, and a UUID (user interview identifier required for all subsequent requests) +- Consumer calls QE for next question on each step; when no more questions, QE indicates completion → consumer initiates get-decision flow +- Consumer can also call: get previous question, get current question, export all answers as JSON (used for PDF document generation), get flat export (for UW) +- Product determination happens in Main App using prequal TRL score and applicant age: + - If prequal TRL < 25 or age < 50 → full TRL score not needed (prequal is cheaper) + - Otherwise, full TRL (includes risk assessment data) is ordered + +### 3.2 Evidence Ordering (Maestro + Dante) + +**Progressive ordering**: Maestro does not order all evidence upfront. It orders evidence based on how the decision is trending: +- If trending approval → order next evidence batch +- If trending decline → stop ordering additional evidence +- Each evidence step has a predetermined timeout; if time limit is reached, Maestro forces a compute (does not wait indefinitely) + +**Rx pre-ordering**: Originally, Rx was pre-ordered at policy creation regardless of decision (to avoid a 60-second wait). After Rx cost optimization, Rx is now fetched only after the user adds credit card information. + +**Evidence reuse**: Evidence is reused if: +- Same person/identity (by email/SSN) +- Evidence was received within the last **30 days** +- Sharing logic matches (see Evidence per Product section below) + +**Evidence by active product:** + +| Product | Evidence ordered | +|---------|-----------------| +| LGA Term (LGA Prime) | Criminal Records, MIB, MVR, TRL, Rx, AUTO_MEDICAL_CLAIMS | +| Ameritas Choice | Criminal Records, MIB, MVR, TRL, Rx, AUTO_MEDICAL_CLAIMS | +| Ameritas IUL | Criminal Records, MIB, MVR, TRL, Rx, AUTO_MEDICAL_CLAIMS | + +**Evidence sharing logic (current):** + +| Evidence | Sharing scope | +|----------|--------------| +| Criminal Records | Shared across all products | +| MVR | Shared across all products | +| TRL | Shared across all products | +| Rx | Shared across same carrier only (Choice + IUL share with each other) | +| MIB | Shared across same carrier only | +| AUTO_MEDICAL_CLAIMS | Shared across same carrier only | + +*Evidence is ordered at policy level. Reuse logic checks identity but is scoped per the sharing rules above.* + +**Fallback behavior**: If evidence cannot be obtained, Maestro takes a fallback decision (typically RUW). + +**Evidence storage**: Raw XML responses stored in S3 at `evidence-service-payload-production///`; converted JSON stored at `evidence-data-production///`. + +### 3.3 Timeouts + +| Scope | Timeout | Behavior on expiry | +|-------|---------|-------------------| +| Choice / Term (LGA Prime) / IUL — UW decision | 60 seconds | Decision sent to RUW | +| SI (Simplified Issue) — UW decision | 300 seconds | Decision sent to RUW; debits added | +| All products — Main App frontend | 150 seconds | Routes to TruStage / RUW | +| All products — Main App backend call to UW | No timeout (async) | — | +| Evidence-level | No individual timeout (much larger than decision timeout) | — | + +*Note: Rx is typically the slow evidence source (not MVR). 65% of timed-out SI policies had reasons other than UW timeout (e.g., slow queue worker). This caused ~124 policies to time out, 83 of which were later found to be Approvable.* + +### 3.4 Rules Evaluation (Janus) + +- Janus evaluates carrier-specific underwriting rules per product +- Input: standardized facts and attributes from Parsi +- Output: decision outcome (Approved / Declined / RUW) + health class + tobacco class + debits/table rating +- Rules are authored and maintained by the UW Platform team; carrier rules are not exposed to IPP directly + +### 3.5 Manual Review (Nora) + +- Nora is the manual underwriter workbench for RUW cases +- Manual underwriting is triggered when the engine cannot make an automated decision (evidence timeout, rules force RUW, code-level triggers, etc.) +- RUW cases **block policy activation** until a Final decision is issued by a manual underwriter — this can take days +- Even fully automated applications: approximately 20% of policies must undergo PIA post-activation (see Section 6) +- For APS (Attending Physician Statements): no direct API integration; underwriters create a task, case managers manually retrieve the APS + +--- + +## 4. ACORD Transactions + +Not applicable within UW 2.0. The UW pipeline communicates internally via APIs. ACORD transactions for carrier submission are handled separately by the ACORD Feed Framework after a Final decision is issued. + +--- + +## 5. Data Inputs / Outputs + +### Inputs to UW 2.0 +- Applicant interview answers (from QE session, via Main App) +- Applicant demographics: DOB, SSN, state, driver's license info +- Prequal TRL score (ordered by consumer funnel, passed to UW) +- Third-party evidence: Criminal Records (Sherlock), MIB, MVR (TransUnion), Rx (Milliman), AUTO_MEDICAL_CLAIMS +- Prior policy decisions (from Decision Service; 18-month lookback) +- Carrier eligibility data (LGA and Protective provide detailed eligibility info) +- Product and carrier configuration + +### Outputs from UW 2.0 + +**Decision entity** (stored in Decision Service). Key fields: + +| Field | Type | Notes | +|-------|------|-------| +| `id` | UUID | Primary key | +| `policyId` | string | Required | +| `product` | enum | TERM, SI, ER (deprecated), SIWL (deprecated), GIWL (deprecated) | +| `carrier` | enum | LGA, AMERITAS, SENIOR_LIFE | +| `decisionType` | enum | AppliedFor, SoftDecline, Checkpoint, Engine, Final, PIA, RandomHoldout | +| `decision` | enum | Approved, Declined, RUW, Withdrawn, Ineligible, Rescinded, Waived | +| `rateClass` | enum | Standard, Preferred, PreferredPlus (null on non-Approved) | +| `tobaccoClass` | enum | Tobacco, NonTobacco | +| `maxCoverage` | number | Coverage cap applied | +| `percentageAddition` | number | Table rating as debit % | +| `classDowngrade` | boolean | Whether health class was downgraded | +| `debits` | number | Additional risk debits | +| `ineligibleProduct[]` | array | Products the applicant is ineligible for | +| `eligibleProduct[]` | array | Products the applicant is eligible for | +| `requirements[]` | array | Outstanding requirements | +| `description` | JSON | declineReasons, withdrawReason, otafReason, waiveReason, ineligibleReasons | +| `additionalInfo` | JSON | tracemap, doctor info, otaf needed, amendment, sentToAdmin | +| `createdAt` | timestamp | | + +--- + +## 6. Standard Decisions + +### 6.1 Decision Types + +| Decision Type | When Generated | Description | +|---------------|----------------|-------------| +| **AppliedFor** | At application start (Main App calls create-case) | Records the coverage amount the applicant requested | +| **SoftDecline** | During interview (called twice by Main App mid-interview) | Intermediate decline signal; determines whether to continue ordering evidence or redirect to alternative product | +| **Checkpoint** | During progressive evidence ordering | Intermediate decision after each evidence batch; drives Maestro's "order next evidence?" decision | +| **Engine** | After full evidence evaluation by Janus | Automated decision produced by the rules engine | +| **Final** | After all evaluation is complete (automated or after manual review) | The binding UW decision; required for policy submission | +| **PIA** | Post policy activation | Post Issue Audit decision; can override the original Final decision (including rescinding coverage) | +| **RandomHoldout** | At application | Application withheld from automated UW for statistical holdout; requires manual handling | + +### 6.2 Decision Outcomes + +| Outcome | Meaning | +|---------|---------| +| **Approved** | Application approved; health class assigned | +| **Declined** | Application declined; not eligible for coverage | +| **RUW** | Referred to manual underwriter review (Nora) | +| **Withdrawn** | Applicant withdrew during process | +| **Ineligible** | Did not meet basic eligibility criteria (age, state, product eligibility) | +| **Rescinded** | Policy rescinded post-issue (can happen via PIA) | +| **Waived** | Evidence requirement waived | + +### 6.3 Health Class Ratings + +| Class | BMI Range (example at 5'11") | Notes | +|-------|------|-------| +| **PreferredPlus** | BMI 20.0–26.0 | Best health class; lowest mortality risk | +| **Preferred** | BMI 18.5–20.0 or 26.0–30.0 | Mid-tier approval | +| **Standard** | BMI 18.0–18.5 or 30.0–38.0 | Base-rate approval | +| **Standard + Debits/Table Rating** | BMI 38.0–48.91 | Standard class with added table rating (T2–T10) | +| **Decline** | BMI < 18 | Below minimum threshold | + +BMI-based health class examples at 5'11": + +| BMI Range | Decision | Class | Debit | Table | +|-----------|----------|-------|-------|-------| +| < 18 | Decline | N/A | 0 | — | +| 18.0–18.5 | Approve | Standard | 0 | — | +| 18.5–20.0 | Approve | Preferred | 0 | — | +| 20.0–26.0 | Approve | Preferred Plus | 0 | — | +| 26.0–30.0 | Approve | Preferred | 0 | — | +| 30.0–38.0 | Approve | Standard | 0 | — | +| 38.0–38.49 | Approve | Standard | 50 | T2 | +| 38.49–40.49 | Approve | Standard | 75 | T3 | +| 40.49–41.49 | Approve | Standard | 100 | T4 | +| 41.49–43.49 | Approve | Standard | 125 | T5 | +| 43.49–44.49 | Approve | Standard | 150 | T6 | +| 44.49–45.90 | Approve | Standard | 175 | T7 | +| 45.90–46.90 | Approve | Standard | 200 | T8 | +| 46.90–47.90 | Approve | Standard | 225 | T9 | +| 47.90–48.91 | Approve | Standard | 250 | T10 | + +### 6.4 Tobacco Class + +Tobacco class = **Tobacco** if the applicant used cigarettes, e-cigarettes, or vaporizers within the last year. +- Frequency does not matter; recency (within 12 months) is the trigger +- Tobacco is a modifier applied on top of health class (affects premium / product eligibility) + +### 6.5 Maximum Table Rating by Product + +| Product | Max table rating allowed | +|---------|-------------------------| +| Ameritas Choice | T8 | +| Ameritas IUL | T8 | +| LGA Prime (LGA Term) | T10 | + +*Note: T9–T10 for Ameritas Choice results in a decline (T9–T10 still allowed for class downgrade calculations but not as final outcome).* + +### 6.6 Age 61–65 Treatment + +| Product | Age 61–65 treatment | +|---------|---------------------| +| Ameritas Choice | Product-specific logic (special handling) | +| Ameritas IUL | Product-specific logic (same as Choice) | +| LGA Prime | Routes to RUW | + +--- + +## 7. PIA Logic by Product + +PIA (Post Issue Audit) is a post-activation underwriting review. PIA decisions can override the original Final decision. + +### LGA Term (LGA Prime) +- **65%** of activated policies with DX status "hit" (random selection via code; random number 0–99) +- **100%** of activated policies with DX status "clear" +- **100%** of IC policies with missing/failed evidence in engine decision +- **100%** of policies with coverage above prior age limit / table limit (LGA $3M initiative) +- RUW cases with sufficient APS do not need to go to PIA + +### Ameritas Choice +- **100%** of IC policies with missing/failed evidence in engine decision +- **100%** if age > 60 +- **100%** if table rating > T6 +- **50%** random selection for all others not meeting the above criteria + - 50% of this random group selected from DX "hit" population + - 50% selected from DX "clear" population (insured age ≥ 40) + - Male/Female split maintained when selecting random population + - **Implementation:** Airflow job (not in-service logic), runs **twice per week (Monday and Thursday)** + +### Ameritas IUL +- Same logic as Ameritas Choice + +### Protective Spirit +- **100% PIA** for first 100 activated policies +- After 100: **40%** of DX No Hit, **25%** of DX Hit (~31% overall) + +### Sahara IUL +- **100% PIA** for first 250 activated policies +- After 250: **25%** of all activated policies per month + +### Multiple Policies (Same Insured) +- If insured has a currently active prior Ethos policy → compulsory PIA for both old and new policy +- **18-month lookback window**: if prior policy was activated within 18 months, both policies go to PIA + - If prior policy already had PIA, it does not need another; same UW assigned to new PIA + - If prior policy was activated > 18 months ago, only the new policy goes to PIA +- First, check prior policy activation status via Policy Admin data; if prior policy not active, standard product-level PIA logic applies + +--- + +## 8. Code-Level Decision Triggers + +These are non-rules-engine logic (implemented in code) that affect the decision outcome of an application. They run in Maestro before/after Janus rules evaluation. + +| Outcome | Trigger | 18-month window? | Notes | +|---------|---------|-----------------|-------| +| **RUW** | Prior tobacco class = Tobacco, current = NonTobacco (self-reported) | Any | Applicant may have legitimately quit or may be lying | +| **RUW** | Prior active policy = Tobacco class, Ethos Engine generates NonTobacco | Any | Via carrier eligibility data (LGA only currently) | +| **RUW** | Prior rating (health class + debits) is worse than current | > 18 months | Manual review to verify legitimate health improvement | +| **Cap decision** | Prior rating (health class + debits) is worse than current | Within 18 months | Current decision is capped to match the worse prior decision | +| **Decline** | Prior decision = Decline (disclosure-based) | Within 18 months | Disclosure-based declines are not re-underwriteable in this window | +| **Approve (skip decline)** | Prior decision = Decline (non-disclosure, reUnderwriteable=true), flag `uw_ignore_re_underwritable_decisions_for_capping` ON | Within 18 months | Non-disclosure declines may change on re-application; evaluated on own merits | +| **Decline** | Prior decision = Decline (non-disclosure, reUnderwriteable=true), flag OFF | Within 18 months | Conservative path when flag is off | +| **Decline** | Prior decision = Decline (unknown source) | Within 18 months | Conservative path when decline source is unknown | +| **RUW** | LGA carrier eligibility data shows worse rating | Any | LGA provides detailed eligibility info; triggers RUW (not cap) since LGA internal guidelines differ from Ethos's | +| **RUW** | LGA eligibility data contains Postpone or Decline | Any | Manual review if carrier-level data suggests prior decline | +| **RUW** | Incomplete PIA in prior policies | N/A | New evidence may surface during PIA (e.g., APS). Exceptions: PIA triggered within 72 hours; Evidence On Hold stage; PIA decision = Waived with no new evidence | +| **RUW** | Prior policies ever in CLR (Closed Loop Rescission) | N/A | Prior CLR means pre-issue decision was inaccurate; new application may have same issue | +| **RUW** | Reconsideration flag ON | N/A | Profile intentionally routed to RUW for manual review | +| **RUW** | Missing carrier eligibility data or missing prior Ethos application data | N/A | Error fetching LGA/Protective eligibility or prior policy data; elevated risk → RUW | +| **RUW** | Prior reinstatement had a Declined decision | N/A | Possible data gap in automated decision | +| **Decline** | Allowed coverage < minimum coverage for the product | N/A | After deducting existing coverage from Ethos max / carrier max / product max; if result < product minimum, decline | + +**Prior policies definition**: Policies with same SSN as the applicant across: LGA Term, Protective Term, Ameritas Choice, Ameritas IUL, Accumulation Sahara IUL. + +--- + +## 9. Known Constraints + +1. **Evidence timeouts are hard limits** — Maestro does not wait indefinitely. If evidence does not return within the decision timeout, it forces a compute. This can produce a decision based on incomplete evidence, typically resulting in RUW rather than Approved. + +2. **Rx is the common slow evidence source** — Not MVR. SI timeouts are especially risky because SI has a 150s frontend timeout against a 300s UW decision timeout; the frontend may route to TruStage/RUW while UW is still processing. + +3. **Interview is product-specific** — There is no generic interview. Each product has its own QE interview ID stored in the consumer env var. Changing products mid-session typically requires restarting the interview. + +4. **Soft decision is called twice** — Main App calls `get soft decision` after medical questions and again at the end of the interview. A soft decline causes applicant routing to an alternative product. `start UW` (evidence ordering) only proceeds if the soft decision is trending toward approval. + +5. **RUW cases block activation** — Applications in RUW cannot be activated until Nora produces a Final decision. This can take days; IPP must handle this state gracefully in the application lifecycle. + +6. **PIA can override Final decisions post-activation** — A PIA review after activation can Rescind or modify coverage. IPP must be prepared to receive post-activation decision changes (including Rescinded status). + +7. **Tobacco mismatch triggers RUW** — If Rx evidence shows tobacco use inconsistent with self-reported status, the application is sent to RUW regardless of other evidence. + +8. **18-month lookback caps or blocks coverage** — Prior worse decisions within 18 months cap the current application's health class/debits. Prior disclosure-based declines within 18 months force a Decline. IPP should verify prior policy state before presenting a coverage offer. + +9. **Coverage floor decline** — If deducting existing coverage from Ethos/carrier/product maximum results in a coverage amount below the product's minimum, the application is Declined rather than Approved at a lower amount. + +10. **Evidence reuse is 30 days** — Evidence from a prior application is reused if within 30 days and sharing logic matches. This means a returning user may not trigger fresh evidence pulls. + +11. **RandomHoldout applications get no automated decision** — These are intentionally excluded from the UW pipeline for statistical purposes. IPP should handle applications that do not receive an automated decision. + +12. **APS has no direct API integration** — When an application requires an Attending Physician Statement, there is no automated fetch. Case managers manually retrieve APS. This adds significant handling time. + +--- + +## 10. Carrier-Specific Variations + +| Carrier / Product | Variation | +|-------------------|-----------| +| **LGA Term (LGA Prime)** | T7–T10 bucketing logic; max table rating T10; age 61–65 → RUW; class downgrade: 1 class for RX No Hit age 51-60; 1 class for age 20-50 TRL 51-70; 2 classes for age 20-50 TRL 71-80; full TRL ordered if age 20-50 and prequal TRL > 50 | +| **Ameritas Choice** | Max table rating T8; T9-T10 → Decline; age >60 → 100% PIA; table rating >T6 → 100% PIA; 50% random PIA via Airflow job (Mon/Thu); Select and PrefTobacco supported; full TRL if prequal ≥71 | +| **Ameritas IUL** | Same as Ameritas Choice; financial and living assistance questions (IUL-specific); age 61–65 specific logic | +| **Protective Spirit** | 100% PIA for first 100 activated; then 40% DX No Hit / 25% DX Hit | +| **Sahara IUL** | 100% PIA for first 250 activated; then 25%/month | + +Carrier-specific Janus rules (medical conditions, disclosure rules, etc.) are maintained by the UW Platform team and are not documented here. + +--- + +## 11. Needs Validation + +1. **Rx ordering timing after cost optimization** — The current behavior (Rx ordered at CC entry, not at create-policy) should be confirmed as the live production behavior for all active products. + +2. **Soft decision call sequence** — Confirmation that `get soft decision` is called exactly twice (after medical questions and at interview end) and that this behavior is consistent across all active products. + +3. **Ameritas Choice PIA Airflow job** — Confirm the job is still running twice per week (Monday/Thursday) in production; confirm it accurately reflects the 50/50 DX Hit/No Hit split logic in current code. + +4. **Incomplete PIA exceptions** — "Evidence On Hold" and "Waived with no new evidence" exceptions were noted as in-development (RP-6264 at time of documentation). Confirm current production behavior. + +5. **`uw_ignore_re_underwritable_decisions_for_capping` flag state** — Confirm whether this flag is ON or OFF in production (RP-6674). + +--- + +## 12. Source Documents + +| Document | Type | Date | Notes | +|----------|------|------|-------| +| Underwriting — Notion Hub | Notion page | 2026-05 | Top-level index; links to all sub-pages | +| Question Engine (HLD) | Notion sub-page | 2025-03 | Full architecture; Main App + QE + Maestro + Dante + Janus + Parsi + Nora flow | +| Dante Evidence Ordering Service | Notion sub-page | 2026-04 | Third-party evidence providers, API design, S3 storage, polling state management | +| Janus - Design | Notion sub-page | 2025-03 | Rules engine design doc (links to external PRD) | +| Evidence order and timeouts | Notion sub-page | 2024-01 | Per-product timeout table; timeout impact analysis | +| Evidence ordering in Underwriting engine | Notion sub-page | 2023-12 | Evidence-by-product table; reuse logic and sharing rules | +| PIA logic for all products | Notion sub-page | 2025-12 | Product-specific PIA criteria and implementation notes | +| Code-Level Decision Triggers | Notion sub-page | 2026-04 | Full table of code-level decision overrides and rationale | +| Decision Types | Notion sub-page | 2024-07 | Decision type mapping across Maestro / Nora / Decision Service | +| Decision service design doc | Notion sub-page | 2026-04 | Data model, entity schema, enum mappings, backfill plan | +| Underwriting Guidelines — For non-UW Teams | Notion sub-page | 2026-02 | BMI → health class table; tobacco class logic | +| Ameritas Choice \| IUL \| LGA Prime — UW Guidelines | Notion sub-page | 2024-03 | Feature differences across Choice, IUL, LGA Prime | + +## 13. Change Log + +| Version | Date | Author | Summary | +|---------|------|--------|---------| +| v2.0 | 2026-05-13 | Pankaj Soni | Full draft from all Notion UW 2.0 sub-pages; covers QE flow, evidence ordering, timeouts, PIA logic, code-level triggers, decision data model, BMI/tobacco tables | 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