Networking & Security Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- attached_assets/Pasted-Make-a-focused-security-pass-on-the-Ragna-conversation-_1774838250254.txt
- attached_assets/Pasted-Make-a-focused-networking-and-API-consistency-pass-acro_1774841954107.txt
- attached_assets/Pasted-Build-a-real-in-app-support-request-flow-for-the-React-_1774839229732.txt
- attached_assets/Pasted-Make-a-truth-alignment-pass-across-the-current-React-Na_1774837201847.txt
- replit.md
The Networking & Security Architecture of the Hospice Roadmap project is designed to provide consistent, device-scoped, and secure communication between the Expo React Native mobile application and the Express API server. It prioritizes data privacy through local storage by default while enabling secure server-backed features like the Ragna AI companion and provider search through encrypted transmissions and client identity verification.
The architecture centers on a shared API client that handles base URL resolution, request timeouts, and standardized error handling. Security is enforced via a persistent, device-generated x_client_id header, ensuring that user data—specifically AI conversations and support requests—remain scoped to the originating device without requiring a full account-based authentication system.
Client-Side Networking
The mobile application utilizes a centralized apiClient to manage all outgoing network requests. This ensures consistency across services such as AI interactions, CMS provider searches, and support submissions.
API Client Implementation
The apiClient.ts utility serves as the single source of truth for networking logic. It handles environment-aware base URL resolution, supporting both local Replit development and production environments. It standardizes headers, including Content-Type: application/json and Accept: application/json, alongside custom security headers like x_client_id.
The client manages request timeouts using AbortController signals, typically defaulting to 12,000ms for routine requests while allowing extensions for longer operations like AI streaming.
Sources: attached_assets/Pasted-Make-a-focused-networking-and-API-consistency-pass-acro_1774841954107.txt, replit.md
Network State Management
The system tracks connectivity via a useAppNetwork hook. This hook provides a reactive state for the application's online status, allowing the UI to display offline banners or disable network-dependent features when the internet is unreachable.
Sources: attached_assets/Pasted-Make-a-focused-networking-and-API-consistency-pass-acro_1774841954107.txt
Security and Identity Architecture
The project employs a device-scoped security model that identifies the originating device for every sensitive request without requiring traditional login credentials.
Device-Scoped Identity (x_client_id)
A persistent client ID is generated on the first run of the mobile application and stored in AsyncStorage under the key ragna_client_id. This ID follows the format client_<timestamp>_<random> and is sent as the x_client_id header in all requests to the Anthropic AI routes and support endpoints.
| Component | Description | Persistence |
|---|---|---|
| Generation | client_[a-z0-9_]+ format using timestamp and random noise. | AsyncStorage |
| Transmission | Included in x_client_id custom HTTP header. | Request-level |
| Validation | Regex verification on server: ^client_[a-z0-9_]+$. | Server-side middleware |
Sources: attached_assets/Pasted-Make-a-focused-security-pass-on-the-Ragna-conversation-_1774838250254.txt, attached_assets/Pasted-Build-a-real-in-app-support-request-flow-for-the-React-_1774839229732.txt
Scoped Data Access
The Express API enforces ownership by requiring the x_client_id header for all protected routes. The database schema for conversations includes a client_id field to ensure users can only list, read, or delete resources they created.
Server-Side Security Controls
The server-side architecture focuses on request validation, CORS policy management, and database-level security.
CORS and Header Management
The Express application is configured to explicitly allow the x_client_id header in its CORS policy. While maintaining compatibility with Replit and Expo development environments, it restricts allowed headers to Content-Type and x_client_id to prevent unauthorized cross-origin header injection.
Sources: attached_assets/Pasted-Make-a-focused-security-pass-on-the-Ragna-conversation-_1774838250254.txt, attached_assets/Pasted-Build-a-real-in-app-support-request-flow-for-the-React-_1774839229732.txt
Support Request Flow
Support requests are processed via a dedicated API endpoint (POST /api/support/support-requests). This flow captures diagnostic information and client identity, saving the request to the support_requests table with a status of "received".
| Field | Type | Constraint |
|---|---|---|
id | serial | Primary Key |
clientId | text | Not Null (Indexed) |
email | text | Not Null (Format validation) |
message | text | Min 10 characters |
status | text | Default "received" |
Sources: attached_assets/Pasted-Build-a-real-in-app-support-request-flow-for-the-React-_1774839229732.txt
Data Privacy and Transparency
The networking architecture is designed to align with the project's "Truth Alignment" goals. User-facing screens clearly distinguish between locally stored data and data transmitted for AI processing.
- Local Storage: Most information (role, journey stage, symptom tracking, goals of care) is stored locally on the device.
- Secure Transmission: Data used to personalize Ragna (e.g., patient context, journal entries) is transmitted over encrypted connections only when the AI feature is engaged.
- Third-Party Services: The architecture specifically avoids advertising networks and data brokers, using server-side proxies for AI (Anthropic) and provider data (CMS) to mask direct client details where possible.
Sources: attached_assets/Pasted-Make-a-truth-alignment-pass-across-the-current-React-Na_1774837201847.txt, replit.md
Conclusion
The Networking & Security Architecture for Hospice Roadmap establishes a robust foundation for healthcare navigation. By combining centralized client-side networking with device-level identity verification, the system ensures high availability and data integrity while respecting user privacy and maintaining development flexibility.