Anthropic / Claude API Integration

Relevant source files

The following files were used as context for generating this wiki page:

• artifacts/api-server/src/routes/anthropic/index.ts
• artifacts/api-server/src/routes/anthropic/systemPrompt.ts
• lib/api-spec/openapi.yaml
• attached_assets/Pasted-Make-a-focused-security-pass-on-the-Ragna-conversation-_1774838250254.txt
• attached_assets/Pasted-Build-the-next-major-intelligence-architecture-for-Hosp_1774852812580.txt
• artifacts/api-server/src/intelligence/hospice/documentationCoach.ts

The Anthropic / Claude API Integration provides the core conversational intelligence for the Hospice Roadmap platform, personified as an AI companion named Ragna. This system leverages Anthropic's Claude models to offer personalized, compassionate, and clinically grounded support to caregivers and patients navigating hospice care.

The integration serves as a bridge between the mobile application and a sophisticated intelligence engine. It manages multi-turn conversations, synthesizes long-term memory of patient contexts, and processes real-time symptom data to generate empathetic yet technically accurate guidance.

Sources: artifacts/api-server/src/routes/anthropic/systemPrompt.ts, replit.md:25-27

Architecture and Data Flow

The integration is built as a layered intelligence engine within an Express API server. It sits between incoming user messages from the mobile client and the Anthropic API.

Conversation Life Cycle

1. Identity Verification: Every request must include a valid x_client_id header to ensure data isolation.
2. Context Assembly: The server retrieves message history and combines it with patientContext (symptoms, goals of care, etc.).
3. Intelligence Planning: A planner module analyzes the input to inject specific clinical knowledge blocks into the system prompt.
4. Model Interaction: The system sends the prompt to Claude (typically claude-3-5-sonnet-20240620) and streams the response back to the user via Server-Sent Events (SSE).

The following diagram illustrates the flow of a single message request through the integration:

The diagram shows the sequential processing of a message from the mobile client to the database persistence.
Sources: artifacts/api-server/src/routes/anthropic/index.ts:111-180, attached_assets/Pasted-Build-the-next-major-intelligence-architecture-for-Hosp_1774852812580.txt:130-140

API Endpoints

The system exposes RESTful endpoints for managing conversations and generating AI-driven insights. All endpoints are scoped to a clientId.

Endpoint	Method	Description
/conversations	GET	Lists all conversations belonging to the current client.
/conversations	POST	Creates a new conversation thread.
/conversations/{id}	GET	Retrieves a specific conversation including its message history.
/conversations/{id}/messages	POST	Sends a message to Ragna and initiates a streaming response.
/profile-synthesize	POST	Updates Ragna's "living understanding" of the family based on memory.
/conversations/{id}/memory	POST	Extracts key facts and emotional tone from a transcript.
/score-hospice	POST	Analyzes interview data to evaluate potential hospice providers.

Sources: lib/api-spec/openapi.yaml:18-100, artifacts/api-server/src/routes/anthropic/index.ts:31-300

Ragna: The System Prompt

The "Ragna" persona is defined by a comprehensive system prompt that enforces strict behavioral, emotional, and clinical boundaries.

Core Identity and Behavioral Rules

Ragna is personified as a 58-year-old Norwegian hospice nurse. The system prompt requires her to:

• Acknowledge Emotion First: Comfort must precede information.
• Avoid "AI" Language: She must never refer to herself as an AI or use robotic phrasing.
• Clinical Mastery: She possesses physician-level knowledge of palliative care, pharmacology (opioids, benzodiazepines, etc.), and disease trajectories (Cancer, CHF, COPD, Dementia).

Intelligence Injection

The system prompt is dynamically extended with "Intelligence Packages" that include:

• Knowledge Blocks: Contextually relevant information on symptom management or documentation (e.g., from the DocumentationCoach).
• Response Plans: Structured instructions on what to say, what to avoid, and when to escalate to 911 or a hospice nurse.

Sources: artifacts/api-server/src/routes/anthropic/systemPrompt.ts:1-70, artifacts/api-server/src/intelligence/hospice/documentationCoach.ts, attached_assets/Pasted-Build-the-next-major-intelligence-architecture-for-Hosp_1774852812580.txt:142-155

Security and Multi-tenancy

The integration implements "device-scoped ownership" rather than a full account system. Security is enforced through a persistent clientId generated and stored locally on the mobile device.

Implementation Details

• Request Validation: The server uses requireClientId to validate the x_client_id header against a regex (^client_[a-z0-9_]+$).
• Database Scoping: Every database query for conversations or messages includes a filter on clientId.
• CORS Configuration: The API server explicitly allows the x_client_id header in its CORS policy.

This diagram demonstrates the client identification and data isolation mechanism.
Sources: artifacts/api-server/src/routes/anthropic/index.ts:11-30, attached_assets/Pasted-Make-a-focused-security-pass-on-the-Ragna-conversation-_1774838250254.txt:37-60

Memory and Profile Synthesis

The system uses a recursive memory process to maintain a "living understanding" of the user's journey.

1. Memory Extraction: After a conversation, the /memory endpoint extracts key facts, emotional tone, and main topics from the transcript into a JSON structure.
2. Profile Synthesis: The /profile-synthesize endpoint takes these new memories and the existing profile to generate a 3-5 sentence updated narrative.
3. Instructional Use: This synthesized profile is injected back into the system prompt for future interactions, allowing Ragna to say things like, "I remember we talked about John's breathing last time."

Sources: artifacts/api-server/src/routes/anthropic/index.ts:313-400, artifacts/api-server/src/routes/anthropic/systemPrompt.ts:710-730

Summary

The Anthropic / Claude API Integration is a sophisticated intelligence layer that transforms a standard LLM into a specialized hospice companion. By combining strict persona constraints, dynamic clinical knowledge injection, and device-scoped memory synthesis, the system provides users with personalized, safe, and compassionate guidance throughout the end-of-life journey.