# 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.