Simplinsured

Conversational specialty-insurance prototype for guided risk discovery, underwriting, and quote comparison.

Simplinsured explores how a technical insurance workflow can feel understandable to a buyer without hiding material coverage details. It guides a user from an ambiguous risk description to structured underwriting answers, risk scoring, and three explainable coverage recommendations.

Problem Statement

Specialty insurance buyers often know the business problem they want covered but not the exact product, underwriting terminology, or information an insurer needs. Traditional forms expose the organizational complexity of insurance rather than guiding the user through it.

This prototype tests a different interaction model:

1. Identify the user's business context and risk.
2. Select a product-specific underwriting path.
3. Ask only the next relevant question.
4. Normalize free-text answers into canonical risk signals.
5. Explain coverage, exclusions, and final-review caveats before selection.

Architecture

flowchart LR
    U[Buyer] --> UI[Browser Experience]
    UI --> GUIDE[Guided Conversation]
    GUIDE --> KB[Coverage Knowledge Base]
    GUIDE --> RULES[Product-specific Underwriting Rules]
    GUIDE --> GEO[Open-Meteo Geocoding]
    RULES --> SCORE[Risk Scoring]
    KB --> RECS[Coverage Recommendations]
    SCORE --> RECS
    UI --> API[Python HTTP API]
    API --> DB[(SQLite)]
    DB --> ACCOUNT[Quotes, Claims, Billing, Documents]

Loading

Core Workflows

• Risk discovery: starts from a category, search query, or conversational request.
• Dynamic underwriting: selects five to eight questions based on the specialty line and prior answers.
• Answer normalization: handles synonyms, spelling variation, and typed natural-language responses.
• Explainable recommendations: shows policy basis, deductible, exclusions, endorsements, sublimits, and warranties.
• Quote continuity: saves a browser draft and can persist quotes to SQLite.
• Claims and account view: demonstrates claim intake, document checklists, billing references, and policy history.

Technical Decisions

Concern	Decision	Rationale
Prototype UI	Plain HTML, CSS, and JavaScript	Keeps the interaction model inspectable without framework overhead
Product logic	Separate catalog, knowledge base, and risk modules	Makes underwriting behavior easier to audit and extend
Location context	Open-Meteo geocoding	Demonstrates cross-border and distance-aware questions without paid infrastructure
Persistence	Python standard-library API + SQLite	Provides a zero-cost local path for product testing
Payment data	Generated token and masked reference only	Avoids storing raw card or UPI details in the prototype
Deployment	Docker + Cloud Run configuration	Demonstrates a portable hosted path while documenting ephemeral-storage limits

Tech Stack

• JavaScript, HTML, CSS
• Python standard library HTTP server
• SQLite with WAL and foreign keys
• Open-Meteo geocoding API
• Docker and Google Cloud Run configuration

Security Guardrails

• The prototype stores only masked payment references and generated test tokens.
• Authentication codes and demo accounts are illustrative, not production identity controls.
• Database writes use parameterized SQL.
• Static file paths are resolved under the repository root to reduce traversal risk.
• Real deployment would require managed identity, encrypted persistent storage, audit logs, CSRF controls, and a PCI-compliant payment provider.

Repository Structure

app.js             Browser workflow and screen state
catalog.js         Specialty-product catalog and underwriting paths
knowledge-base.js  Coverage explanations and glossary content
risk.js            Risk scoring and recommendation logic
services.js        External service adapters
server.py          Static server and SQLite API
scripts/           Deterministic data generation and understanding evaluation
assets/            Product identity assets

Run Locally

No third-party Python packages are required.

python3 server.py --host 127.0.0.1 --port 8099

Open http://127.0.0.1:8099.

For a browser-only walkthrough, open index.html; persistence will use local browser storage instead of SQLite.

Validation

Generate deterministic quote fixtures:

node scripts/generate-quote-fixtures.js --count 150 --server http://127.0.0.1:8099

Evaluate answer normalization and false-positive behavior:

node scripts/evaluate-chatbot-understanding.js

Health check:

curl http://127.0.0.1:8099/api/health

Deployment

The repository includes a Dockerfile and Cloud Build configuration. Replace the placeholders with your own project, region, and Artifact Registry repository:

gcloud builds submit \
  --config cloudbuild.yaml \
  --substitutions _SERVICE_NAME=simplinsured,_REGION=YOUR_REGION,_REPOSITORY=YOUR_REPOSITORY

Cloud Run's filesystem is ephemeral. Use Cloud SQL, Firestore, or another managed database before relying on saved records.

Current Limitations

• Underwriting and pricing content is illustrative and is not insurance advice or a bindable quote.
• Risk scoring is deterministic business logic, not an actuarially validated model.
• Demo access codes are not production authentication.
• SQLite is suitable for a local prototype, not multi-instance production traffic.

Future Improvements

• Versioned underwriting rules with reviewer approval and audit history
• Managed identity and policyholder consent controls
• Carrier/rater integrations behind a normalized quote schema
• Human underwriter escalation with structured context
• Experimentation metrics for completion, trust, and quote conversion

Disclaimer

This repository is a portfolio prototype. Product names, limits, prices, and coverage descriptions are illustrative and must not be used to purchase or bind insurance.