116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# CTM Concierge — Patient Journey Tracker
|
|
|
|
An internal desktop application built for CTM medical clinic to monitor international patient travel and medical journeys in real time. The app is packaged as a cross-platform desktop application using Electron, powered by React and Vite, with a map visualizer using MapLibre GL.
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
```mermaid
|
|
graph TD
|
|
Renderer[React Frontend / Renderer Process]
|
|
Preload[Preload Script / Context Bridge]
|
|
Main[Electron Main Process]
|
|
MapLibre[MapLibre GL / OpenFreeMap Tiles]
|
|
|
|
Renderer -->|Safe API| Preload
|
|
Preload -->|IPC Messages| Main
|
|
Renderer -->|Map Rendering| MapLibre
|
|
```
|
|
|
|
- **Shell (Electron 33)**: Runs the application natively on Windows, macOS, and Linux with security best practices enabled (`contextIsolation`, no raw Node.js integration in the renderer, sandboxing, and restrictive Content Security Policy).
|
|
- **Frontend (React 18 & Vite)**: Single-page application rendering the active user interface.
|
|
- **Mapping (MapLibre GL & React Map GL)**: A full-screen interactive world map using free tile layers from OpenFreeMap (using the 'Fiord' theme).
|
|
- **Styling**: Structured modular layout via a responsive CSS grid and flexbox, using theme-controlled CSS variables in `src/index.css`.
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```text
|
|
├── electron/
|
|
│ ├── main.js # Electron main process (lifecycle, IPC handlers, browser window)
|
|
│ └── preload.js # Sandboxed script exposing restricted APIs to the renderer
|
|
├── src/
|
|
│ ├── assets/ # Client-side assets (e.g., country centroid JSON definitions)
|
|
│ ├── components/ # Reusable React UI components
|
|
│ │ ├── Dashboard.jsx # Metrics cards and Live Patient Board list
|
|
│ │ ├── Sidebar.jsx # Navigation bar and user/physician profile context
|
|
│ │ └── TripTracker.jsx # Interactive MapLibre world map & active patient logs
|
|
│ ├── App.jsx # App root layout shell & page navigation controller
|
|
│ ├── index.css # CSS styles, layout grid, CSS custom properties (variables)
|
|
│ └── main.jsx # React application entry point
|
|
├── package.json # Dependencies, scripts, and electron-builder configs
|
|
└── vite.config.js # Vite builder setup with Electron integration plugins
|
|
```
|
|
|
|
---
|
|
|
|
## Core Features
|
|
|
|
### 1. Interactive Patient World Map
|
|
Located in `src/components/TripTracker.jsx`, this component renders patient destinations across the globe:
|
|
- **Centroid Coordinates**: Destructuring ISO-2 country codes (e.g., `TH`, `GH`, `MX`) to map them to coordinates using a centroid lookup dataset (`src/assets/countries.json`).
|
|
- **Interactive Markers**: Displays pulsed, color-coded rings corresponding to the patient's status. Clicking a marker centers the map using a smooth transition (`flyTo`) and displays a detailed information popup.
|
|
- **English Label Translation**: Coerces country names on the map to display in English.
|
|
- **Visual De-cluttering**: Automatically hides non-essential map layers (continents, states, roads, cities) when loading, leaving a clinical visual representation focused strictly on the patient country destinations.
|
|
|
|
### 2. Live Patient Board & Stats Dashboard
|
|
Located in `src/components/Dashboard.jsx`, this acts as the clinic's command center:
|
|
- **Stat Cards**: Dynamic counters highlighting patient states (`In Pre-Travel`, `In Transit`, `At Risk`, `In Post-Travel`) with growth/decay indicators.
|
|
- **Live Board Table**: A tabular view of all patients, showing their email, scheduled departure/arrival dates, and status badges.
|
|
|
|
### 3. IPC Bridge Security
|
|
IPC communication is strictly isolated using `electron/preload.js`:
|
|
- Exposes a safe bridge (`window.api`) containing only three functions: `send`, `invoke`, and `receive`.
|
|
- Channels are strictly whitelisted to prevent unauthorized renderer execution.
|
|
|
|
#### Whitelisted Send Channels
|
|
- `patient:update-status`
|
|
- `patient:fetch-list`
|
|
- `schedule:fetch`
|
|
- `app:ready`
|
|
|
|
#### Whitelisted Receive Channels
|
|
- `patient:status-updated`
|
|
- `patient:list-response`
|
|
- `schedule:response`
|
|
- `app:get-version`
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- [Node.js](https://nodejs.org/) (LTS recommended)
|
|
|
|
### Installation
|
|
1. Clone the repository to your local system.
|
|
2. Install the package dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Development
|
|
Launch the Vite hot-reloading dev server and the Electron application instance:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production Build & Package
|
|
To compile files and package the application for target platforms using `electron-builder`:
|
|
```bash
|
|
npm run build
|
|
```
|
|
The output installers will be created in the `release/` directory.
|
|
|
|
- **Linux**: Targets AppImage and Debian packages (`.deb`).
|
|
- **Windows**: Targets NSIS installer package.
|
|
- **macOS**: Targets DMG installer package.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This software is **UNLICENSED** and private. All rights reserved.
|