From 05638437b378bd14d6ee896b07d6d1d1ddfa5af0 Mon Sep 17 00:00:00 2001
From: Bruno Silva <bsilva@wirediv.com>
Date: Fri, 17 Jul 2026 13:10:18 -0400
Subject: [PATCH] added README content

---
 README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)

diff --git a/README.md b/README.md
index e69de29..2d9b666 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,115 @@
+# 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.