Eligibility

Owns member coverage records and accumulator tracking — the authoritative source for "is this member covered and how much have they spent?"

Overview

The Eligibility service projects and caches member coverage from enrollment events, providing fast lookups for other services that need to verify whether a member has active coverage and what their current cost-sharing position is.

When a policy is activated in Enrollment, Eligibility consumes the enrollment.policy.activated Kafka event and creates or updates MemberCoverage records. These records reflect the member's plan, effective dates, and network tier. Accumulators track running totals for deductibles, out-of-pocket maximums, and other benefit limits against each coverage term.

Because coverage is a projection of enrollment state, Eligibility can also bootstrap from Enrollment directly via HTTP if it needs to reconstruct its read model. In normal operation all updates flow through Kafka.

Responsibilities

• Project member coverage records from enrollment.policy.activated Kafka events
• Expose point-in-time eligibility checks for Claims, Care, and other services
• Track accumulator balances (deductible spent, out-of-pocket spent) per coverage term
• Provide internal endpoints for Claims to apply accumulator amounts at adjudication time
• Support administrative coverage lookups for the web admin panel

Database

Schema: eligibility

Table	Purpose
member_coverage	Coverage records per member/policy/term with effective dates and network tier
coverage_accumulators	Running totals for deductible, OOP max, and other benefit limits per term
projection_checkpoints	Kafka consumer offset tracking for the enrollment projection consumer

API Routes

Method	Path	Auth	Description
GET	/check	JWT	Check eligibility by query parameters
POST	/check	JWT	Check eligibility with a request body
GET	/coverage/list	JWT	List all coverage records (web admin)
GET	/coverage/{locator}	JWT	Get a coverage record by locator
GET	/members/{locator}/coverage	JWT	Get active coverage for a member
GET	/members/{locator}/coverage/list	JWT	List all coverage records for a member
GET	/members/{locator}/accumulators	JWT	Get accumulator totals for a member
GET	/members/{locator}/accumulators/list	JWT	List all accumulator records for a member
GET	/internal/members/{locator}/coverage	Internal	Fetch coverage for Claims/Care (no JWT)
PATCH	/internal/members/{locator}/accumulators/{termLocator}/apply	Internal	Apply adjudicated amounts to accumulators

Events

Publishes

The Eligibility service does not publish any Kafka events.

Consumes

Topic	Action taken
enrollment.policy.activated	Creates or updates MemberCoverage and initialises accumulator records for the new policy term

Dependencies

Service	How used
Enrollment	HTTP client used for bootstrap coverage fetch during read-model reconstruction

Key Design Decisions

Read model / projection pattern: Eligibility is a pure read-side projection of Enrollment state. It never writes back to Enrollment. This allows Claims and Care to query coverage at very low latency without touching the Enrollment database.

Internal accumulator application: When Claims adjudicates a service, it calls PATCH /internal/members/{locator}/accumulators/{termLocator}/apply to update running totals atomically. This endpoint is not JWT-protected; it is restricted to internal cluster traffic at the gateway.