API Specifications & Type Contracts
Relevant source files
The following files were used as context for generating this wiki page:
The Hospice Roadmap platform relies on a strictly defined API specification to ensure seamless communication between the Expo React Native mobile application and the Express API server. This architecture is centered around an OpenAPI 3.1.0 specification, which serves as the "single source of truth" for generating TypeScript types, Zod validation schemas, and React Query hooks.
Sources: replit.md:65-72, lib/api-spec/openapi.yaml:1-6
The core of the system's intelligence is driven by the Anthropic AI integration, which utilizes structured type contracts to inject patient context and hospice-specific knowledge into the LLM (Claude). These contracts ensure that the AI remains grounded in clinically approved knowledge blocks and follows a deterministic response plan based on the user's role and journey stage.
Sources: replit.md:82-93, artifacts/api-server/src/routes/anthropic/systemPrompt.ts:397-425
API Architecture and Codegen Flow
The project utilizes a monorepo structure where API definitions are decoupled from implementation. The lib/api-spec package contains the openapi.yaml file, which defines all available endpoints, request bodies, and response structures.
This diagram shows the automated pipeline where the OpenAPI specification drives the generation of client hooks for the mobile app and validation schemas for the server.
Sources: replit.md:27-31, replit.md:65-72
Core API Endpoints
The API is divided into functional tags: health for system monitoring and anthropic for AI-driven hospice assistance.
Anthropic AI Chat Operations
The Anthropic routes manage the lifecycle of a conversation with Ragna, the AI hospice companion. This includes creating sessions, retrieving message history, and initiating streaming responses.
| Endpoint | Method | Summary | Description |
|---|---|---|---|
/anthropic/conversations | GET | List Conversations | Returns an array of AnthropicConversation objects. |
/anthropic/conversations | POST | Create Conversation | Initializes a new chat session with a specific title. |
/anthropic/conversations/{id} | GET | Get Conversation | Retrieves a conversation and its full message history. |
/anthropic/conversations/{id}/messages | POST | Send Message | Sends a user message and returns a Server-Sent Events (SSE) stream. |
Sources: lib/api-spec/openapi.yaml:18-100
Data Models and Schemas
Type contracts are strictly enforced for both standard data entities and the complex "Intelligence Package" used by the AI engine.
Entity Schemas
The OpenAPI specification defines several critical schemas used across the application:
- AnthropicMessage: Represents a single exchange in a chat. Contains
id,conversationId,role(user/assistant),content, andcreatedAt. - HealthStatus: A simple status check returning
{ "status": "string" }. - SendAnthropicMessageBody: The contract for sending new messages, which requires both the user's
contentand thepatientContext.
Sources: lib/api-spec/openapi.yaml:104-165
Hospice Knowledge Block Schema
On the server side, the intelligence engine uses a HospiceKnowledgeBlock type to structure expert content. This is a critical contract for ensuring the AI has consistent metadata to work with.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (e.g., "HF001", "DP002"). |
domain | string | The category of knowledge (e.g., symptom_management, care_gap). |
urgency | string | Level of concern: routine, moderate, urgent, critical. |
journeyStages | string[] | Applicable stages like weeks_to_days or after_death. |
whatToWatchFor | string | Specific clinical red flags to monitor. |
hardStops | string[] | Immediate safety instructions (e.g., "Call 911"). |
Sources: artifacts/api-server/src/intelligence/hospice/catalog.ts:5-25, artifacts/api-server/src/intelligence/hospice/catalog.ts:251-270
AI Interaction Logic
When a message is sent to the /anthropic/conversations/{id}/messages endpoint, a complex sequence occurs to synthesize the final response based on the type contracts.
This diagram illustrates how the API server acts as an orchestrator, enriching the user's request with structured intelligence data before communicating with the AI provider.
Sources: replit.md:82-93, artifacts/api-server/src/routes/anthropic/systemPrompt.ts:397-425
Content Documentation Contracts
The mobile app maintains local data contracts for educational resources, ensuring consistent rendering of guidance content.
// artifacts/mobile/data/resources.ts:3-10
export const resources: Resource[] = [
{
id: "res-001",
title: "What Is Hospice Care?",
summary: "A clear, compassionate explanation...",
category: "understanding_hospice",
journeyStage: ["before", "during"],
tags: ["basics", "overview"],
readTime: 4,
isFeatured: true,
}
];
This structure ensures that the UI can filter and display resources based on the user's current journeyStage (before, during, or after hospice).
Sources: artifacts/mobile/data/resources.ts:4-38, replit.md:46-49
Conclusion
The API Specifications & Type Contracts within the Hospice Roadmap project form a robust foundation for a safety-critical healthcare application. By using an OpenAPI-driven codegen workflow, the project maintains strict synchronization between the mobile client and the intelligence-heavy server. This ensures that expert hospice knowledge is delivered accurately, role-aware, and within the prescribed clinical guardrails.