Skip to content

Commit e0908a8

Browse files
bihellzinbihellzin
committed
Update README
1 parent dc48289 commit e0908a8

File tree

1 file changed

+126
-15
lines changed

1 file changed

+126
-15
lines changed

‎README.md‎

Lines changed: 126 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,39 @@
1-
# Medplum Transfer Center
2-
3-
This repo is for the Medplum transfer center demo. Currently this portal includes a dashboard for the transfer center, as well as patient intake, and physician onboarding for the portal.
1+
<h1 align="center">Medplum Transfer Center</h1>
2+
<p align="center">An open-source hospital transfer center portal built on the Medplum platform.</p>
3+
<p align="center">
4+
<a href="https://github.com/medplum/medplum-transfer-center-demo/actions">
5+
<img src="https://github.com/medplum/medplum-transfer-center-demo/actions/workflows/build.yml/badge.svg" />
6+
</a>
7+
<a href="https://github.com/medplum/medplum-transfer-center-demo/blob/main/LICENSE.txt">
8+
<img src="https://img.shields.io/badge/license-Apache-blue.svg" />
9+
</a>
10+
</p>
11+
12+
### What is the Medplum Transfer Center?
13+
14+
The Medplum Transfer Center is a **ready-to-use hospital transfer center demo app** that is open source. It provides a portal for managing patient transfers between facilities, including a transfer center dashboard, patient intake, and physician onboarding. It is meant for developers to clone, customize, and run.
15+
16+
### Features
17+
18+
- Completely free and open-source
19+
- Secure and compliant [Medplum](https://www.medplum.com) backend, which is also open source
20+
- Transfer center dashboard for managing incoming patient transfers
21+
- Patient intake workflow via FHIR Questionnaires
22+
- Physician onboarding for accepting transfer requests
23+
- Hospital location management (buildings, wards, rooms)
24+
- Real-time HL7 ADT message processing via Medplum Agent
25+
- Automated bed assignment workflows
26+
- All data represented in [FHIR](https://hl7.org/FHIR/)
427

528
## Repo Overview
629

7-
TODO: Enumerate bots, scripts and their use cases, important custom components such as the , etc.
30+
| Directory / File | Purpose |
31+
| --------------------------- | ------------------------------------------------------------------ |
32+
| `src/` | React application source code (pages, components, hooks, utils) |
33+
| `src/bots/` | Medplum bots for automating FHIR resource creation and HL7 parsing |
34+
| `data/core/` | Core FHIR bundle data (CodeSystems, ValueSets, Questionnaires) |
35+
| `scripts/` | Utility scripts for deploying bots and sending ADT messages |
36+
| `data/core/agent-data.json` | Medplum Agent and Endpoint resource definitions |
837

938
## Data Model
1039

@@ -50,29 +79,50 @@ This model allows us to use [FHIR search semantics](https://www.hl7.org/fhir/sea
5079

5180
Note that along with each location, we also denote an "alias" which is just the room number. This allows us to search for just the room number more directly while still displaying the full `Location.name` (eg. `3SURG 307`) by default for the user when facilitating things like user type-aheads in inputs or displaying locations in a table cell.
5281

53-
---
82+
## Getting Started
83+
84+
First, [fork](https://github.com/medplum/medplum-transfer-center-demo/fork) and clone the repo.
85+
86+
Next, install the app from your terminal:
87+
88+
```bash
89+
npm install
90+
```
91+
92+
### Environment Setup
93+
94+
Copy the example environment file and fill in your Medplum project credentials:
5495

55-
TODO: Include notes about other parts of the data model
96+
```bash
97+
cp .env.example .env
98+
```
5699

57-
## Development
100+
| Variable | Description |
101+
| ------------------------------- | -------------------------------------------------- |
102+
| `VITE_MEDPLUM_PROJECT_ID` | Your Medplum project ID (used by the frontend) |
103+
| `VITE_MEDPLUM_GOOGLE_CLIENT_ID` | Google OAuth client ID for login (optional) |
104+
| `MEDPLUM_CLIENT_ID` | Medplum client ID for bot deployment scripts |
105+
| `MEDPLUM_CLIENT_SECRET` | Medplum client secret for bot deployment scripts |
106+
| `DEPLOY_MEDPLUM_CLIENT_ID` | Medplum client ID used during CI/CD deployment |
107+
| `DEPLOY_MEDPLUM_CLIENT_SECRET` | Medplum client secret used during CI/CD deployment |
58108

59-
To run the development server for this app, type the following in your console of choice:
109+
Then, run the app:
60110

61111
```bash
62112
npm run dev
63113
```
64114

65-
This will host the Vite development server locally, which by default should be hosted on port 3000.
115+
This app should run on `http://localhost:3000/`
66116

67-
## Building for production
117+
## Building for Production
68118

69119
To build the app, run:
70120

71121
```bash
72122
npm run build
73123
```
74124

75-
## Upserting core data
125+
## Upserting Core Data
76126

77127
To upsert the core data into the Medplum server, run:
78128

@@ -81,9 +131,9 @@ npx medplum post '' "$(cat path/to/bundle.json)"
81131
# Example: npx medplum post '' "$(cat data/core/core-data.json)"
82132
```
83133

84-
### Core data
134+
### Core Data
85135

86-
The core data for the Hospital Regional Portal is stored in the `data/core` directory. This data is used to populate the Medplum server with the necessary resources for the portal to function. The core data includes the following resources:
136+
The core data for the Transfer Center is stored in the `data/core` directory. This data is used to populate the Medplum server with the necessary resources for the portal to function. The core data includes the following resources:
87137

88138
| Resource Type | Name |
89139
| ------------- | ---------------------------------------- |
@@ -100,9 +150,45 @@ The core data for the Hospital Regional Portal is stored in the `data/core` dire
100150
| Questionnaire | patient-intake-questionnaire |
101151
| Questionnaire | physician-onboarding-questionnaire |
102152

153+
## Questionnaires
154+
155+
[FHIR Questionnaires](https://hl7.org/fhir/r4/questionnaire.html) are structured forms defined as FHIR resources. They describe the fields, types, and validation rules for a form, while a `QuestionnaireResponse` stores the answers a user submitted. This separation keeps the form definition (the schema) independent from the collected data (the responses).
156+
157+
In this portal, Questionnaires drive every user-facing workflow. The frontend renders them using Medplum's `<QuestionnaireForm>` React component, and each submission produces a `QuestionnaireResponse` that triggers the corresponding bot via a FHIR Subscription (see [Bots](#bots) below).
158+
159+
| Questionnaire name | Title | Purpose |
160+
| ------------------------------------------ | ------------------------- | -------------------------------------------------- |
161+
| `patient-intake-questionnaire` | Patient Transfer Form | Captures incoming transfer request details |
162+
| `accepting-physician-intake-questionnaire` | Accepting Physician Form | Records the accepting physician's intake decision |
163+
| `patient-bed-assignment-questionnaire` | Patient Bed Assignment | Assigns an admitted patient to a specific bed/room |
164+
| `physician-onboarding-questionnaire` | Physician Onboarding Form | Onboards a new physician into the portal |
165+
| `create-location-lvl-questionnaire` | Create Location Form | Creates a new ward/level Location resource |
166+
| `create-location-ro-questionnaire` | Create Room Form | Creates a new room Location resource |
167+
168+
All Questionnaire definitions are bundled in [data/core/core-data.json](data/core/core-data.json) and uploaded to Medplum as part of the core data setup.
169+
103170
## Bots
104171

105-
The bots in this project are used to automate the creation of resources in the Medplum server.
172+
Bots are server-side TypeScript functions that run on the Medplum platform in response to events. This project uses two triggering mechanisms:
173+
174+
- **FHIR Subscriptions** — six bots are subscribed to the `create` event of a specific `QuestionnaireResponse`. When a user submits a form (Questionnaire) in the portal, Medplum fires the subscription and invokes the corresponding bot.
175+
- **Medplum Agent** — the ADT processing bot has no subscription. Instead, it is invoked directly by the Medplum Agent whenever an HL7 v2 ADT message arrives over MLLP.
176+
177+
The deploy script in [scripts/deploy-bots.ts](scripts/deploy-bots.ts) handles creating or updating each bot and its associated `Subscription` resource automatically when you run `npm run bots:deploy`.
178+
179+
### Bot Reference
180+
181+
| Bot | Trigger | Questionnaire |
182+
| ------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------ |
183+
| [patient-intake-bot.ts](src/bots/patient-intake-bot.ts) | `QuestionnaireResponse` created | `patient-intake-questionnaire` |
184+
| [accepting-physician-intake-bot.ts](src/bots/accepting-physician-intake-bot.ts) | `QuestionnaireResponse` created | `accepting-physician-intake-questionnaire` |
185+
| [patient-bed-assignment-bot.ts](src/bots/patient-bed-assignment-bot.ts) | `QuestionnaireResponse` created | `patient-bed-assignment-questionnaire` |
186+
| [physician-onboarding-bot.ts](src/bots/physician-onboarding-bot.ts) | `QuestionnaireResponse` created | `physician-onboarding-questionnaire` |
187+
| [location-lvl-bot.ts](src/bots/location-lvl-bot.ts) | `QuestionnaireResponse` created | `create-location-lvl-questionnaire` |
188+
| [location-room-bot.ts](src/bots/location-room-bot.ts) | `QuestionnaireResponse` created | `create-location-ro-questionnaire` |
189+
| [adt-processing-bot.cts](src/bots/adt-processing-bot.cts) | Medplum Agent (HL7 ADT over MLLP) | — |
190+
191+
### Building and Deploying
106192

107193
Before running any of the bot commands, make sure to set the environment variables in the `.env` file.
108194

@@ -137,6 +223,7 @@ npx medplum post '' "$(cat data/core/agent-data.json)"
137223
```
138224

139225
This will create:
226+
140227
- An **Endpoint** resource configured for HL7 v2 MLLP on port 56000
141228
- An **Agent** resource that routes incoming HL7 messages to your ADT processing bot
142229

@@ -146,13 +233,14 @@ This will create:
146233

147234
The Medplum Agent is required to receive HL7 messages. To run the agent locally, follow the instructions in the [Medplum Agent documentation](https://www.medplum.com/docs/agent).
148235

149-
Once the agent is running, you can send test ADT messages using the provided script to test the sample application:
236+
Once the agent is running, you can send ADT messages using the provided script to test the sample application:
150237

151238
```bash
152239
npm run send-adt <MESSAGE_TYPE> <ROOM_NUMBER>
153240
```
154241

155242
Available message types:
243+
156244
- `A01` - Patient admission
157245
- `A03` - Patient discharge
158246

@@ -162,3 +250,26 @@ Example:
162250
npm run send-adt A01 201 # Admit patient to room 201
163251
npm run send-adt A03 201 # Discharge patient from room 201
164252
```
253+
254+
## Account Setup
255+
256+
By default, your locally running Transfer Center app points to the hosted Medplum service. To use your own organization's Medplum project, [register a new Project on Medplum](https://www.medplum.com/docs/tutorials/register) and configure your environment variables accordingly (see [config.ts](src/config.ts)).
257+
258+
If you are using the Medplum Hosted service, you can log in to your Medplum instance and add the following identifiers to your [Project Site Settings](https://app.medplum.com/admin/sites):
259+
260+
- Google Client Id
261+
- Google Client Secret
262+
- Recaptcha Site Key
263+
- Recaptcha Secret Key
264+
265+
Contact the Medplum team ([support@medplum.com](mailto:support@medplum.com) or [Discord](https://discord.gg/medplum)) with any questions.
266+
267+
## About Medplum
268+
269+
[Medplum](https://www.medplum.com/) is an open-source, API-first EHR. Medplum makes it easy to build healthcare apps quickly with less code.
270+
271+
Medplum supports self-hosting and provides a [hosted service](https://app.medplum.com/).
272+
273+
- Read our [documentation](https://www.medplum.com/docs/)
274+
- Browse our [React component library](https://storybook.medplum.com/)
275+
- Join our [Discord](https://discord.gg/medplum)

0 commit comments

Comments
 (0)