Medical Care Timeline

Medical Care Timeline is a visual tool for exploring patients' hospital episodes in a clear, interactive way.

Instead of reading many rows across many tables, you can open one case and see the full journey as a timeline, review key events, follow clinical evolution, and inspect details when needed.

Run Locally

If you want to try the app on your own machine:

0. Clone the repository.
1. Create a Python virtual environment and install the backend dependencies.
2. Install the frontend dependencies with npm.
3. Start the backend.
4. Start the frontend.
5. Open http://localhost:5173 in your browser.

git clone https://github.com/diegomarzaa/medical-care-timeline.git
cd medical-care-timeline

Backend setup:

python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

cd backend
uvicorn main:app --reload --port 8000

Run the frontend in another terminal:

cd frontend
npm install
npm run dev

What You Can Do

• Open one or many case IDs at the same time.
• Explore the episode as a visual timeline.
• Review numeric evolution in charts.
• Inspect the same events in a table.
• Click any event to focus it and read more detail.
• Save, reuse, import, and export configurations.
• Use your own data or try the bundled synthetic demo dataset.

How Data Can Be Loaded

Medical Care Timeline supports different ways of loading data, so teams can use the one that fits their workflow best.

1. Remote PostgreSQL through SSH: Used when the database lives on a remote server.
2. Direct PostgreSQL connection: Used when the application can connect directly to the database without an SSH tunnel.
3. Local CSV files: Used when data is available as CSV exports. Easiest method for fast reviewing.
4. Synthetic demo dataset: Used for testing before loading your own data. IDs are automatically suggested.

Typical Workflow

1. Load your data.
2. Choose the episode ID column.
3. Configure the layers you want to see.
4. Open one or more case IDs.
5. Switch between views depending on what you want to inspect.

Layer Configuration

The layer editor is where Medical Care Timeline becomes useful for different projects and datasets.

You can:

• Choose the episode identifier column.
• Create point events and range events.
• Build parent and child layers to organize the timeline.
• Pick colors and labels.
• Choose what appears on hover and what appears in the detail panel.
• Add filters so a layer only shows the rows you care about.
• Create evolution series for point layers, so values can be displayed as charts.
• Configure the episode summary shown when no event is selected.
• Save configurations in the app, import JSON files, or export them for reuse.

Available Views

Timeline

Best for understanding the overall episode flow, admissions, movements, treatments, and important clinical events over time.

Evolution

Best for following numeric changes across time, such as assessment scores or other series configured in point layers.

Table

Best for scanning events in a more traditional format, filtering by layer, and exporting to CSV.

Combined views

You can also work in:

• Timeline + Evolution
• Timeline + Table

This is useful when you want both the visual story and the detailed values at the same time.

Best Use Cases

Medical Care Timeline is especially useful for:

• Clinical pathway review
• Case exploration and discussion
• Data validation
• Demonstrations and presentations
• Comparing how different configurations change what a case reveals

Coming Soon

Docker

A simple Docker-based setup is planned so the full app can be started more easily with fewer local installation steps.