API Server Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Hospice Roadmap API server is a Node.js Express 5 application that serves as the backend backbone for the healthcare navigation platform. Its primary responsibilities include managing AI-driven conversations via Anthropic's Claude, acting as a proxy for CMS hospice provider data, and providing a structured intelligence engine that injects expert hospice knowledge into user interactions.
The server operates within a pnpm monorepo workspace and utilizes a PostgreSQL database with Drizzle ORM for data persistence. It is designed to support the mobile application by handling complex logic, such as AI response planning and multi-session memory synthesis, ensuring that users receive personalized and clinically grounded guidance throughout their hospice journey.
Sources: replit.md:20-30, lib/api-spec/openapi.yaml:1-10
Architecture and Components
The API server is structured as a modular Express application. It integrates with several internal workspace packages and external services to deliver its functionality.
Core Frameworks and Tools
- API Framework: Express 5.
- Database ORM: Drizzle ORM with PostgreSQL.
- AI Integration: Anthropic SDK for Claude (using
claude-3-5-sonnet-20240620andclaude-3-haiku-20240307models). - Validation: Zod for request/response schema enforcement.
- Documentation: OpenAPI 3.1.0 specification.
Sources: replit.md:31-40, artifacts/api-server/src/routes/anthropic/index.ts:10-15
Data Flow Diagram
The following diagram illustrates the high-level data flow between the Mobile App, API Server, Database, and Anthropic AI services.
The API server acts as the orchestrator, retrieving patient context and stored messages from the database before passing them to the AI model with injected hospice intelligence.
Sources: replit.md:41-55, artifacts/api-server/src/routes/anthropic/index.ts:120-150
Intelligence Engine & AI Orchestration
The server contains a sophisticated "Intelligence Engine" located in src/intelligence/hospice/. This engine intercepts incoming user messages and generates a ResponsePlan based on message content and patient context.
Knowledge Injection
Before a message is sent to Anthropic, the planner.ts module builds a context package. This package includes:
- Knowledge Blocks: Relevant information retrieved from over 35 hospice-specific knowledge blocks.
- Response Plan: Instructions for the AI on required sections (e.g., "What to do now", "When to call hospice").
- Care Gap Signals: Detection of potential failures in standard hospice care that require advocacy.
Sources: replit.md:110-125, artifacts/api-server/src/routes/anthropic/index.ts:125-135
AI Model Usage
The server utilizes different models based on the complexity of the task:
| Task | Model | Purpose |
|---|---|---|
| Chat Conversations | Claude 3.5 Sonnet | High-reasoning chat with streaming support. |
| Memory Generation | Claude 3 Haiku | Cost-effective extraction of key facts from transcripts. |
| Profile Synthesis | Claude 3 Haiku | Updating the "living profile" of the user. |
| Hospice Scoring | Claude 3.5 Sonnet | Analyzing provider interviews for quality. |
Sources: artifacts/api-server/src/routes/anthropic/index.ts:145, artifacts/api-server/src/routes/anthropic/index.ts:310, artifacts/api-server/src/routes/anthropic/index.ts:375
API Endpoints and Routing
The API is organized into functional routers. The primary interaction point is the /anthropic route group, which handles AI chat, memory, and profile synthesis.
Anthropic Routes (/api/anthropic)
| Endpoint | Method | Description |
|---|---|---|
/conversations | GET | Lists all conversations for the authenticated x-client-id. |
/conversations | POST | Creates a new conversation thread. |
/conversations/:id/messages | POST | Sends a user message and returns a Server-Sent Events (SSE) stream of the AI response. |
/conversations/:id/memory | POST | Triggers the extraction of key facts from a conversation transcript. |
/profile-synthesize | POST | Synthesizes a new "living profile" from recent observations. |
Sources: artifacts/api-server/src/routes/anthropic/index.ts:30-100, lib/api-spec/openapi.yaml:25-80
Security and Client Scoping
The API enforces device-scoped ownership using an x_client_id header. Requests without a valid client ID (regex: ^client_[a-z0-9_]+$) are rejected with a 401 Unauthorized status.
System Prompt and Persona
The AI's behavior is governed by the HOSPICE_SYSTEM_PROMPT. It defines the persona "Ragna," a 58-year-old Norwegian hospice nurse. The prompt provides a strict hierarchy for responses:
- Acknowledge emotion first.
- Offer comfort before solutions.
- Provide wise, practical counsel in short sentences.
- End with an open door for further conversation.
Sources: artifacts/api-server/src/routes/anthropic/systemPrompt.ts:1-35
Conclusion
The API server provides a robust backend for the Hospice Roadmap platform, moving beyond a simple chatbot to act as an expert system. By combining Express 5, Drizzle ORM, and a layered intelligence architecture with Anthropic's models, it ensures that caregivers and patients receive secure, personalized, and clinically relevant support throughout the end-of-life journey.