Care

Care management service — coordinates care episodes, provider appointments, prescriptions, and diagnostic referrals.

Overview

The Care service models the post-triage care delivery journey. Once a member completes a triage session (or presents directly), a care episode is opened to track the full course of treatment. Within an episode, the care team can book appointments with providers, issue prescriptions, and create referrals to diagnostic facilities or specialists.

Episodes are the root aggregate. They carry a care type (GP, specialist, urgent care, etc.) and optionally reference the triage session that originated them. All appointments, prescriptions, and referrals are scoped to an episode, providing a cohesive view of a member's care journey.

The service integrates with Provider to look up available appointment slots and validate provider participation before booking. A Kafka producer publishes care events for downstream notification and analytics.

Responsibilities

• Open and manage care episodes linked to triage sessions or direct member requests
• Book and manage provider appointments within episodes
• Manage provider availability slots for appointment scheduling
• Issue and track prescription records
• Create and track diagnostic referrals (lab, imaging, specialist)
• Publish care events for Notifications and analytics consumers
• Expose internal endpoints for member portal to list a member's active episodes

Database

Schema: care

Table	Purpose
episodes	Care episode root with member, care type, status, and optional triage session reference
appointments	Provider appointments within an episode (PENDING → CONFIRMED → ATTENDED/CANCELLED/NO_SHOW)
provider_slots	Provider availability slots (AVAILABLE → BOOKED/BLOCKED)
prescriptions	Prescription records linked to an episode (ISSUED → FILLED/VOID)
diagnostics_referrals	Referrals to labs or specialists (REFERRED → BOOKED → COMPLETED/CANCELLED)

API Routes

Method	Path	Auth	Description
POST	/episodes	JWT	Open a new care episode
GET	/episodes	JWT	List episodes (filterable by party, status, care type)
GET	/episodes/{locator}	JWT	Get episode by locator
PATCH	/episodes/{locator}/close	JWT	Close an episode with a summary
PATCH	/episodes/{locator}/cancel	JWT	Cancel an episode
POST	/episodes/{locator}/appointments	JWT	Book an appointment within an episode
GET	/episodes/{locator}/appointments	JWT	List appointments for an episode
PATCH	/appointments/{locator}/confirm	JWT	Confirm an appointment
PATCH	/appointments/{locator}/attend	JWT	Mark appointment as attended
PATCH	/appointments/{locator}/cancel	JWT	Cancel an appointment
PATCH	/appointments/{locator}/no-show	JWT	Mark appointment as no-show
POST	/providers/{providerLocator}/slots	JWT	Add a provider availability slot
GET	/providers/{providerLocator}/slots	JWT	List slots for a provider
PATCH	/slots/{locator}/block	JWT	Block a provider slot
POST	/episodes/{locator}/prescriptions	JWT	Issue a prescription
GET	/episodes/{locator}/prescriptions	JWT	List prescriptions for an episode
PATCH	/prescriptions/{locator}/fill	JWT	Mark a prescription as filled
PATCH	/prescriptions/{locator}/void	JWT	Void a prescription
POST	/episodes/{locator}/referrals	JWT	Create a diagnostic referral
GET	/episodes/{locator}/referrals	JWT	List referrals for an episode
PATCH	/referrals/{locator}/book	JWT	Book a referral appointment
PATCH	/referrals/{locator}/complete	JWT	Mark referral as completed
PATCH	/referrals/{locator}/cancel	JWT	Cancel a referral
GET	/internal/episodes/{locator}	Internal	Fetch episode for member portal (no JWT)
GET	/internal/members/{partyLocator}/episodes	Internal	List all episodes for a member

Events

Publishes

Topic	When
care.episode.opened	A new care episode is created
care.episode.closed	An episode is closed with a care summary
care.appointment.booked	An appointment is booked
care.appointment.attended	An appointment is marked as attended

Consumes

The Care service does not consume Kafka events.

Dependencies

Service	How used
Provider	Fetches provider details and validates slot availability before booking appointments

Key Design Decisions

Episode as the coordination unit: All care activities (appointments, prescriptions, referrals) are scoped to an episode rather than directly to a member. This allows a single member to have multiple concurrent care pathways (e.g., one for a respiratory issue, one for a follow-up from a prior condition) without data mixing.

Triage session linkage is optional: Episodes can be opened without a triage session locator, supporting cases where a member books directly (annual check-up, specialist referral from GP, etc.) or where care is initiated by an admin.