CMS Provider Proxy Route
Relevant source files
The following files were used as context for generating this wiki page:
- artifacts/api-server/src/routes/cms.ts
- replit.md
- artifacts/api-server/src/intelligence/hospice/planner.ts
- attached_assets/Pasted-Build-a-production-ready-native-iPhone-mobile-app-using_1773627288076.txt
- attached_assets/Pasted-Build-a-complete-new-feature-for-the-Hospice-Roadmap-mo_1774923100510.txt
- artifacts/mobile/data/resources.ts
The CMS Provider Proxy Route is a critical backend component within the artifacts/api-server that serves as a bridge between the mobile application and external United States government data sources. Its primary function is to facilitate the discovery of CMS-certified hospice providers and retrieve associated quality metrics while maintaining high performance through server-side optimization.
This proxy architecture enables the "Hospice Roadmap" application to support core user goals such as searching for hospice providers by geography and viewing granular provider details without exposing the mobile client to the complexities of raw government API structures.
Sources: replit.md:41-45, attached_assets/Pasted-Build-a-production-ready-native-iPhone-mobile-app-using_1773627288076.txt:30.
System Architecture and Logic
The proxy is implemented as an Express 5 route that handles incoming search queries from the mobile client. It transforms these queries into requests for the official CMS Provider Data APIs.
Technical Components
- API Framework: Express 5.
- External Integration: Connects to the CMS Provider Data API datasets (IDs:
yc9t-dgbk,252m-zfp9,gxki-hrr8). - Performance Optimization: Utilizes an in-memory cache on the server to store frequently accessed provider information and quality metrics, reducing latency for recurring geographic searches.
Sources: replit.md:41-43, replit.md:120-122.
Request Flow
The following diagram illustrates the data flow from the user's mobile interface through the proxy to the external data providers:
The proxy ensures that the mobile client receives normalized data regardless of the underlying changes in the CMS API schemas.
Sources: replit.md:41-43, replit.md:120-122.
Data Source Integration
The proxy routes specifically target datasets maintained by the Centers for Medicare & Medicaid Services. These datasets contain various metrics that help users make informed decisions about hospice care.
| Dataset Identifier | Content Category | Description |
|---|---|---|
yc9t-dgbk | Provider Directory | Basic information including location, name, and contact details. |
252m-zfp9 | Quality Metrics | Performance data based on clinical standards and patient outcomes. |
gxki-hrr8 | Quality Ratings | Standardized star ratings and comparison data for hospice agencies. |
Sources: replit.md:120-122, artifacts/mobile/data/resources.ts:608-615.
Mobile Frontend Integration
The mobile application interacts with the CMS Proxy through a dedicated service layer. This integration is surface-accessible in several key areas of the app's journey.
Key Entry Points
- Evaluation Screen: Users can navigate directly to the provider search from the hospice evaluation results view using the "Find CMS Certified Providers" action.
- Resource Center: Educational content provides links and context for interpreting CMS Compare data.
- Search Interface: Users search by geography (city, state, or zip code) to find local agencies.
Sources: attached_assets/Pasted-Build-a-complete-new-feature-for-the-Hospice-Roadmap-mo_1774923100510.txt:270-275, artifacts/mobile/data/resources.ts:600-610.
Sequence Diagram: Provider Lookup
Quality and Comparison Logic
Beyond basic directory information, the proxy provides data that supports the "Questions to Ask a Hospice Provider" framework. It retrieves scores from the CAHPS Hospice Survey, which are vital for user-driven quality assessment.
- Visit Frequency: Data on how often nurses and aides visit the home.
- Timeliness: Response times for after-hours calls.
- Patient Satisfaction: CAHPS scores published on
Compare.Medicare.gov.
Sources: artifacts/mobile/data/resources.ts:590-620.
Conclusion
The CMS Provider Proxy Route is the architectural foundation for provider transparency within the Hospice Roadmap project. By centralizing external API logic and implementing a cache, the project provides a resilient and fast mechanism for users to find credible, certified hospice care during a critical time of need.