Member Eligibility Verification

Context

A healthcare provider contacts an insurer to confirm whether a member has active coverage before care is delivered. A Provider Relations representative receives the Member ID and is expected to provide a timely, consistent answer.

Workflow Insurance is the fictional organization used for this reference implementation. The member and coverage records are synthetic.

Existing Workflow

The representative typically must:

1. locate the member;
2. retrieve coverage information;
3. compare effective and termination dates with the current date;
4. apply eligibility rules;
5. communicate the outcome to the provider.

Each step is straightforward, but the workflow is repetitive, relies on institutional knowledge, and can produce inconsistent decisions when performed manually across multiple systems.

Intended Outcomes

• reduce repeated navigation and manual comparison;
• return a decision within the representative’s Salesforce workflow;
• apply the same eligibility rules for every request;
• make the decision capability reusable by future applications;
• retain a clear boundary between user experience, integration, business logic, and data access.

Version 1 Scope

Version 1 accepts one Member ID, retrieves one synthetic member and coverage record, evaluates current eligibility, and returns a clear result. Claims, benefits, deductibles, prior authorization, provider search, multiple coverage records, historical eligibility, runtime AI, and production deployment are outside scope.

Overview

The reference implementation keeps Provider Relations representatives in Salesforce while delegating eligibility decisions to a reusable backend service. Salesforce collects the Member ID and presents the result. The FastAPI service retrieves synthetic member and coverage data, evaluates coverage dates, and returns the decision through an OpenAPI-defined contract.

User Flow

1. The representative opens Member Eligibility Verification in the Salesforce Provider Relations application.
2. The representative enters a Member ID and selects Verify Eligibility.
3. The Lightning Web Component validates the input and calls an Apex controller.
4. The Apex integration service sends POST /api/v1/eligibility/verify through a Named Credential.
5. FastAPI retrieves the member and coverage records.
6. The eligibility service evaluates the coverage window for the current date.
7. Salesforce displays the returned status, reason, member information, coverage information when available, and request information.

Supported Outcomes

Responsibility Boundary

Salesforce owns presentation, input handling, callout orchestration, and result rendering. It does not compare coverage dates or determine eligibility. FastAPI is the only component that applies business rules, which prevents duplicated decisions across channels.

Demonstrated Scope

The working implementation includes a Salesforce Lightning experience, Apex integration, Named Credential configuration, FastAPI API and service layers, synthetic JSON repositories, an OpenAPI 3.1 contract, automated tests, architecture documentation, and a single live eligible end-to-end validation.

Architecture Summary

The solution separates the Salesforce user experience from eligibility decision-making. Salesforce is a presentation and integration client. FastAPI exposes the contract-defined API and owns all eligibility rules. Repository classes isolate the synthetic JSON data source so it can be replaced without moving business logic into the client.

Provider Relations Representative
  → Salesforce Lightning Web Component
  → Apex Controller
  → Apex Integration Service
  → Salesforce Named Credential
  → FastAPI Eligibility API
  → Eligibility Service
  → Member and Coverage Repositories
  → Synthetic JSON Data

Component Responsibilities

Principal Decisions

• API first: the OpenAPI contract was defined before backend and Salesforce implementation.
• Single business-rule owner: eligibility logic exists only in the backend service.
• Thin clients and routes: Salesforce and the FastAPI route orchestrate; neither duplicates domain decisions.
• Repository isolation: JSON is a deliberate Version 1 source behind repository boundaries, not a permanent database choice.
• Contract-alignment testing: automated backend tests compare the generated OpenAPI document with the authoritative contract.
• Externalized endpoint: Apex uses a Named Credential rather than hardcoding a URL or secret.
• No invented production controls: Version 1 does not claim authentication, cloud hosting, database infrastructure, or observability that was not built.

Security and Deployment Boundary

The OpenAPI contract defines no security scheme, and Version 1 uses a No Authentication Named Credential for trusted demonstration communication. The FastAPI process ran locally; a temporary Cloudflare Tunnel made it reachable for one live Salesforce validation. This is demonstration infrastructure, not a target production architecture.

Before production use, the architecture would require explicit authentication and authorization, persistent hosting, managed data storage, secrets management, audit and operational telemetry, resilience controls, privacy review, and environment-specific deployment design.

Architecture Views

• System Context — actor and system boundary.
• Container Architecture — deployable and logical containers.
• Request Sequence — successful and error runtime paths.
• Version 1 Deployment — what was actually exercised.

Contract-First Delivery

The OpenAPI 3.1 contract defines one operation: POST /api/v1/eligibility/verify. It specifies request validation, the three successful business statuses, structured errors, nullable coverage fields, examples, and the supported HTTP responses. Backend and Salesforce models trace to this contract.

FastAPI Backend

The Python 3.13 backend uses FastAPI and Pydantic v2. Its layers are deliberately small:

• the API route accepts and returns contract models;
• dependency providers assemble repositories and the eligibility service;
• the eligibility service owns business rules;
• member and coverage repositories read synthetic JSON data;
• exception handlers produce consistent 400, 404, and 500 responses with correlation identifiers;
• OpenAPI post-processing removes FastAPI’s default 422 response because runtime validation is deliberately translated to 400.

The backend is a local reference service, not a deployed production service.

Salesforce Client

The Salesforce implementation uses a Lightning Web Component, Apex controller, Apex integration service, request and response wrappers, structured integration exceptions, and a Named Credential. The user experience includes an instructional empty state, loading and duplicate-submit handling, keyboard submission, eligible and ineligible presentations, unable-to-determine behavior, member-not-found handling, and generic technical-error handling.

Salesforce applies no eligibility date logic. Status-to-label and status-to-icon mappings are presentation concerns for values already determined by the backend.

AI-Assisted Engineering

AI assisted specification refinement, contract design, code generation, testing, documentation, architecture packaging, and review. Reusable FastAPI and Salesforce development skills, together with task-specific prompts, made the work traceable and repeatable.

Human review and real execution remained the quality gates. Contract tests, local test suites, Salesforce deployment, Apex tests, user-interface refinement, and live integration exposed defects that generation or static review alone did not reveal.

There is no runtime AI, AI application, or AI agent in the delivered eligibility capability.

Engineering Artifacts

The authoritative repository includes:

• six product and architecture specifications;
• one OpenAPI contract;
• backend source and unit, integration, and contract tests;
• Salesforce source, Apex tests, and LWC Jest tests;
• Salesforce configuration guides;
• two reusable Claude Code skills and their references;
• thirteen project and reusable-skill creation prompts;
• seven engineering journals;
• four Mermaid architecture views;
• screenshots, demo material, and a walkthrough.

The website package copies only the public API contract, selected screenshots, and adapted architecture diagrams. Application source remains in GitHub.

Evidence Summary

Backend Coverage

The backend suite verifies:

• unknown-member behavior;
• eligible coverage including effective and termination boundary dates;
• not-yet-effective and terminated coverage;
• unable-to-determine behavior when coverage is absent;
• 200, 400, 404, and 500 HTTP handling;
• rejection of missing, empty, and unexpected request fields;
• path, operation, response-code, request-field, enum, and required-field alignment between generated OpenAPI and the source contract.

Salesforce Coverage

The Apex suite covers successful and nullable responses, 400, 404, and 500 responses, missing backend error messages, malformed bodies, undocumented status codes, callout exceptions, controller success, blank input, and translated errors.

The current LWC Jest suite covers initial, loading, and duplicate-submit states; eligible, ineligible, and unable-to-determine outcomes; Enter-key submission; member-not-found behavior; backend errors; and generic error fallback.

Live End-to-End Validation

One manual live scenario was exercised:

Salesforce LWC
→ Apex Controller
→ Apex Integration Service
→ Named Credential
→ Temporary Cloudflare Tunnel
→ Local FastAPI Service
→ Eligibility Service
→ Synthetic JSON Repositories
→ Contract Response
→ Salesforce Result

Synthetic Member ID M100234 returned Eligible, Medical coverage, and member name Sarah Johnson in Salesforce. The tunnel was temporary and the backend remained local.

Evidence Boundaries

• The ineligible, unable-to-determine, 400, 404, and 500 paths are covered at component boundaries but were not each exercised through the complete live Salesforce-to-FastAPI path.
• The deployment was a Salesforce org plus a developer-machine backend, not a persistent production environment.
• No load, penetration, disaster-recovery, privacy-compliance, or production-operability test is claimed.
• No production authentication or authorization was implemented.
• All demonstrated member and coverage data is synthetic.

Historical Count Reconciliation

The Salesforce generation journal records six LWC Jest tests at that milestone. Later UI refinement expanded the current suite to ten tests. Website content must use the current total and may describe the earlier total only as historical evidence.

Contract Tests Expose Integration Drift

Automated comparison between the FastAPI-generated schema and the source OpenAPI contract found two issues before release: nullable coverage fields were initially treated as required, and FastAPI documented a 422 response even though runtime validation returned 400. The fixes kept documentation and behavior aligned.

Real Execution Finds Different Defects

The first Salesforce deployment revealed that Jest files needed to be excluded from metadata deployment. LWC test execution then exposed a module-resolution mismatch and a validation guard that treated the test stub’s undefined return value as invalid. These defects were not apparent from source review alone.

One Owner for Business Rules Reduces Risk

Keeping coverage-date comparisons in the backend avoided two implementations of the same rule. Salesforce remained responsible for the user workflow and integration, making the service reusable by future channels.

Presentation Quality Is an Engineering Concern

The working Salesforce component required a focused refinement pass to become a credible enterprise demonstration. Information hierarchy, state differentiation, spacing, keyboard behavior, error messages, and domain-aligned application naming materially improved usability without changing the architecture.

Validation Claims Need Precise Scope

Component tests, org compilation, org tests, and live end-to-end verification are different evidence types. Recording them separately prevents a single successful scenario from being interpreted as proof of production readiness or complete branch coverage.

AI-Assisted Engineering Still Requires Governance

Prompts and reusable skills accelerated delivery, but specifications, explicit authority boundaries, traceability, human review, and executable tests determined what was accepted. AI-generated output was treated as a candidate engineering artifact, not proof of correctness.

Reference Implementations Benefit From Honest Constraints

Synthetic data, a local backend, a temporary tunnel, and absent production authentication are deliberate Version 1 boundaries. Making them visible strengthens the implementation as a learning asset and defines the work required for production evolution.

The implementation repository contains more than application source. These assets can support the website, future engineering work, and technical walkthroughs without copying the application itself.

Product and Architecture Specifications

API Contract

contracts/member-eligibility.yaml is a reusable OpenAPI 3.1 contract with request, success, error, enum, nullable-field, example, and status-code definitions. A verified copy is included at api/member-eligibility.yaml with provenance in api/README.md.

Architecture Diagrams

The source repository contains four Mermaid views:

• system context;
• container architecture;
• runtime request sequence;
• validated Version 1 deployment.

Concise website adaptations are included under diagrams/. Mermaid source should remain available so future content builds can render responsive SVG or PNG derivatives.

Screenshots

The source contains five screenshots. Three are copied because they provide direct product or API evidence:

• empty Salesforce verification workflow;
• eligible result in Salesforce;
• Swagger/OpenAPI interface.

The project-structure and repository-README screenshots are not copied because they duplicate information better represented by live GitHub links and become stale quickly. See screenshots/README.md.

Engineering Journals

Seven journals record backend generation, Salesforce integration, architecture packaging, UI refinement and live validation, README productization, sequence-diagram design, and deployment-diagram design. They are indexed in engineering-journal.md.

Reusable Claude Code Skills

The repository contains two project-independent skills:

• fastapi-application-developer — specification validation, layered FastAPI implementation, Pydantic modeling, error handling, security basics, testing, and traceability templates;
• salesforce-integration-developer — explicit execution modes, target-org safety, contract-driven Apex and LWC integration, Named Credentials, testing, error handling, UI guidance, and project templates.

These should be linked as engineering assets if the website later publishes reusable skills. They are not copied into the showcase package because they are versioned implementation tooling rather than page media.

Prompt Assets

The repository contains eleven task prompts covering contract design, backend generation, Salesforce generation, skill refinement, architecture packaging, Salesforce UI refinement, README productization, and four architecture views. Two additional prompts define the reusable FastAPI and Salesforce skills.

Prompts are evidence of the AI-assisted engineering workflow. They should be linked from technical journal content, not presented as runtime application components.

Salesforce Configuration Guides

Three guides document Named Credential setup, why no External Credential is needed for Version 1, and permission-set requirements. They are valuable migration references but must not be presented as deployable production security configuration.

Test and Traceability Assets

• backend unit tests for coverage-date business rules;
• backend API integration tests for request and error behavior;
• OpenAPI contract-alignment tests;
• Apex callout, parsing, translation, and controller tests;
• LWC state, result, keyboard, and error tests;
• generated Salesforce coverage artifacts;
• requirement-to-artifact traceability recorded in engineering journals.

Test source remains in GitHub. The website publishes current evidence and limitations in Validation, not copied test code or coverage reports.

Demonstration and Publishing Assets

The source also includes a case study, website showcase draft, demo script, seven narration clips, LinkedIn draft, NotebookLM walkthrough guide, and enterprise showcase standard. These are useful editorial inputs but are not copied because this package replaces them with concise, specification-aligned website content.

The authoritative repository contains seven engineering journal entries. Together they record generation inputs, architectural decisions, actual validation, defects, corrections, assumptions, and reusable lessons. The website should present the summaries below and link to the source entries rather than duplicate their full content.

Backend Implementation

FastAPI Backend Generation

Records the contract-driven backend structure, requirement traceability, and the original 19-test validation. Contract-alignment tests caught incorrect required-field behavior for nullable coverage data and removed an inaccurate generated 422 response.

Read the source journal

Salesforce Integration

Salesforce Integration Generation

Documents the Lightning Web Component, Apex controller and integration service, contract-shaped wrappers, Named Credential guidance, Salesforce deployment, Apex test execution, LWC Jest execution, architecture decisions, and resolved defects. It also distinguishes metadata-only, connected-validation, and deployment evidence.

Read the source journal

Salesforce UI Polish

Explains how the existing working component was refined into a clearer Provider Relations experience without altering the integration architecture. It records state presentation, accessibility improvements, Salesforce application packaging, and the single live eligible end-to-end validation.

Read the source journal

Architecture and Validation

Architecture Documentation Packaging

Describes how technical architecture evidence was simplified for executive and website use, which validation claims were retained, and which claims were excluded because evidence did not support them.

Read the source journal

Sequence Diagram

Records the decisions behind the runtime sequence view, including success, member-not-found, and technical-failure branches and the explicit FastAPI business-logic boundary.

Read the source journal

Deployment Diagram

Records the actual Version 1 runtime boundaries: Salesforce Cloud, HTTPS communication, and a local developer-machine backend using synthetic JSON. It excludes invented production infrastructure.

Read the source journal

Productization and Lessons Learned

README Productization

Explains how the repository landing page was structured for technical leaders, which business and validation claims were included, which unsupported claims were omitted, and how scope constraints were made visible.

Read the source journal

Cross-Journal Findings

• Contract-first development provided a stable integration boundary.
• Real execution found issues that static review did not.
• Eligibility logic remained isolated in the backend.
• Salesforce deployment and testing required explicit environment authorization.
• User-interface refinement improved demonstration quality without changing architecture.
• Validation language is most credible when it states evidence type and limitations.
• Reusable prompts and skills capture process knowledge beyond the application source.