A full-stack clinical decision support system that surfaces early diabetes risk signals from routine patient data.
Combines an interpretable ML model with a modern React frontend, presenting results tailored for both clinicians and patients.

• Why Clinical Insight Engine?
• Key Features
• Architecture
• Tech Stack
• Getting Started
  • Prerequisites
  • Installation
  • Database Setup
  • Python Environment
  • Prepare Dataset
  • Run the App
  • Shutdown
• Project Structure
• API Reference
• ML Pipeline
• Single-Patient Prediction
• Environment Variables
• Troubleshooting
• Roadmap
• Contributing
• Contributors

Diabetes affects over 500 million adults worldwide, yet early risk signals are often buried in routine clinical data. Clinical Insight Engine bridges that gap:

Collects clinically relevant inputs:

Age · Gender · Hypertension · Heart Disease · Smoking History · BMI · HbA1c · Blood Glucose

• Stores assessments with full timestamps
• Enables longitudinal patient risk tracking over time

• Interactive bar charts for factor contributions
• Diabetes correlation heatmap for data exploration

graph TB
    subgraph Client["🖥️ Client — React + TypeScript"]
        UI["Risk Assessment Form"]
        CV["Clinician View"]
        PV["Patient View"]
        VIZ["Data Visualizations"]
        HIST["Assessment History"]
    end

    subgraph Server["⚙️ Server — Express.js"]
        API["REST API Routes"]
        VAL["Zod Validation"]
        ORM["Drizzle ORM"]
        PY["Python Bridge"]
    end

    subgraph ML["🧠 ML Pipeline — Python"]
        PROC["Data Preprocessing"]
        MODEL["Logistic Regression"]
        INTERP["Feature Interpretation"]
        CACHE["Model Cache (pickle)"]
    end

    subgraph DB["🗄️ PostgreSQL"]
        ASSESS["Assessments Table"]
    end

    Client -->|"HTTP Requests"| API
    API --> VAL --> ORM
    API --> PY -->|"spawn process"| ML
    ORM --> DB
    ML -->|"risk scores + factors"| PY
    CACHE -.->|"load cached model"| MODEL

If you have Docker installed, you can skip the manual installation of Node.js, Python, and PostgreSQL entirely. Running the application requires just a single command.

Simply run the following command in the project root:

docker compose up

This command will:

• Spin up a PostgreSQL 16 database container with persistent storage.
• Build the app container including Node.js 20 and a Python 3 virtual environment with all scikit-learn/pandas dependencies.
• Wait for the database to be healthy, then run migrations (npm run db:push).
• Automatically seed the database with sample clinical assessments (in development mode).
• Launch the full-stack server with live-reloading (HMR) enabled.

Once started, open your browser and navigate to:

• Web App & REST API: http://localhost:3000

To stop the services while preserving your data:

docker compose down

To stop the services and completely reset the database (deleting persistent volumes):

docker compose down -v

If you update package.json or requirements.txt dependencies, trigger a clean rebuild:

docker compose up --build

git clone https://github.com/gopaljilab/Clinical-Insight-Engine.git
cd Clinical-Insight-Engine
npm install

Linux / macOS

cp .env.example .env

Windows (PowerShell)

Copy-Item .env.example .env

Windows (Command Prompt)

copy .env.example .env

If .env.example doesn't exist, create .env manually and add:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/clinical_insight_engine

NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000

DEV_CLINICIAN_EMAIL=developer@cardioguard.local
DEV_CLINICIAN_PASSWORD=DevSecurePassword123!

NEXT_PUBLIC_LOCAL_ENCRYPTION_KEY=your_local_32_character_secret_key_here

# Install PostgreSQL
sudo apt update && sudo apt install postgresql postgresql-contrib

# Start & enable the service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database & set password
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'postgres';"
sudo -u postgres psql -c "CREATE DATABASE clinical_insight_engine;"

# Install PostgreSQL
brew install postgresql

# Start the service
brew services start postgresql

# Create database & set password
psql postgres -c "ALTER USER postgres WITH PASSWORD 'postgres';"
psql postgres -c "CREATE DATABASE clinical_insight_engine;"

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/clinical_insight_engine

Push the database schema:

npm run db:push

The server runs a PostgreSQL preflight check on startup. If you see Database startup check failed, verify that:

• PostgreSQL service is running
• DATABASE_URL in .env is correct
• The migration above has been run
• Port 5432 is not blocked

# Create virtual environment
python3 -m venv .venv

# Activate
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Create virtual environment
py -m venv .venv

# Activate
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

If the dataset already exists in the project:

# Linux / macOS
cp attached_assets/diabetes_dataset.csv ./diabetes_dataset.csv

# Windows (PowerShell)
Copy-Item attached_assets/diabetes_dataset.csv ./diabetes_dataset.csv

If the dataset is missing, generate synthetic data:

# Linux / macOS
python3 -c "from analyze import create_synthetic_data; create_synthetic_data()"

# Windows
py -c "from analyze import create_synthetic_data; create_synthetic_data()"

# Start the full-stack dev server
npm run dev

Stop the dev server:

Ctrl + C

Deactivate the Python environment:

deactivate

Clinical-Insight-Engine/
│
├── client/                        # React frontend
│   └── src/
│       ├── components/            # Reusable UI components
│       ├── pages/                 # Route-level page components
│       ├── hooks/                 # Custom React hooks
│       │   ├── use-assessments.ts # TanStack Query hooks for API calls
│       │   └── use-toast.ts       # Toast notification state
│       ├── lib/                   # Utilities & API client
│       │   ├── queryClient.ts     # Global fetch config + React Query setup
│       │   └── utils.ts           # cn() Tailwind class merge utility
│       └── utils/
│           ├── search_filters.ts  # Patient search & filter logic
│           └── date_fix.ts        # Safe date parser helper
│
├── server/                        # Express.js backend
│   ├── index.ts                   # Server entry point & startup
│   ├── routes.ts                  # API route definitions
│   ├── storage.ts                 # Data access layer (DB queries)
│   ├── db.ts                      # Drizzle ORM + PostgreSQL pool
│   ├── static.ts                  # Serves built React frontend
│   ├── vite.ts                    # Vite dev server integration (HMR)
│   └── db_fix.ts                  # Clean process exit on DB errors
│
├── shared/                        # Shared between client & server
│   ├── schema.ts                  # Drizzle DB schema + Zod types
│   └── routes.ts                  # Shared API request/response schemas
│
├── script/
│   └── build.ts                   # esbuild + Vite production build script
│
├── attached_assets/               # Static assets (dataset, images)
│   └── diabetes_dataset.csv
│
├── analyze.py                     # ML pipeline — training & inference
├── main.py                        # Python entry point
├── diabetes_dataset.csv           # Training dataset (root copy)
├── correlation_heatmap.png        # Diabetes feature correlation heatmap
├── patient.json                   # Sample patient input for CLI prediction
│
├── drizzle.config.ts              # Drizzle ORM configuration
├── vite.config.ts                 # Vite bundler configuration
├── tailwind.config.ts             # Tailwind CSS configuration
├── tsconfig.json                  # TypeScript configuration
├── postcss.config.js              # PostCSS configuration
├── components.json                # shadcn/ui component registry
├── pyproject.toml                 # Python project metadata
├── requirements.txt               # Python dependencies
├── package.json                   # Node.js dependencies & scripts
├── package-lock.json              # Locked dependency versions
├── uv.lock                        # uv Python lock file
│
├── README.md                      # Project documentation
├── ANALYSIS_README.md             # ML analysis documentation
├── CONTRIBUTING.md                # Contribution guidelines
└── CODE_OF_CONDUCT.md             # Community code of conduct

# Health Check
curl -X GET http://localhost:3000/health

# Submit Assessment
curl -X POST http://localhost:3000/api/assessments \
  -H "Content-Type: application/json" \
  -d '{
    "gender": "Female",
    "age": 52,
    "hypertension": true,
    "heartDisease": false,
    "smokingHistory": "former",
    "bmi": 30.1,
    "hba1cLevel": 6.4,
    "bloodGlucoseLevel": 148
  }'

Allows submitting standard FHIR R4 JSON bundles containing patient demographic details, clinical vitals/lab values, and clinical notes.

• Patient: Extracts id, name, gender (mapped to Male/Female), and calculates patient age from birthDate.
• Observation: Extracts clinical values such as BMI, HbA1c, Blood Glucose, and flags hypertension and heartDisease using LOINC codes and display terms.
• DocumentReference: Extracts note titles, descriptions, and decoded base64 attachments, merging them into a unified clinical note transcript.

To ensure clinical decisions are traceable and verifiable, the pipeline extracts source citations for key clinical features. When note text is found in DocumentReference entries, the parser:

1. Performs regex/vitals and keyword scanning for Hypertension (e.g. BP measurements like 145/90 or keywords like hypertension), Heart Disease (e.g. CAD, myocardial infarction), and Smoking History (e.g. former smoker, never smoked).
2. Extracts the exact sentence snippet enclosing the evidence (source_snippet).
3. Computes the zero-indexed character bounds [start, end] within the raw concatenated text (source_index).
4. If no evidence is found, these values are returned as null.

A successful FHIR ingestion response returns the extracted clinical note and explainable insights:

{
  "status": "success",
  "id": 42,
  "clinical_note": "Routine visit. BP reading 145/95 noted. Quit smoking last year.",
  "explainable_insights": [
    {
      "insight": "Patient shows signs of hypertension",
      "source_snippet": "BP reading 145/95 noted",
      "source_index": [15, 38]
    },
    {
      "insight": "Patient shows signs of heart disease",
      "source_snippet": null,
      "source_index": null
    },
    {
      "insight": "Patient has a smoking history (former)",
      "source_snippet": "Quit smoking last year",
      "source_index": [40, 62]
    }
  ]
}

On the Clinician View tab of the results page, the clinical note is rendered in an interactive viewer:

• Interactive Highlights: Clicking any cited insight automatically highlights the matching text in the note.
• Auto-Scroll: The highlighted source text is scrolled smoothly into view.
• Keyboard Navigation:
  • Use Arrow Down / Arrow Right to move to the next cited insight.
  • Use Arrow Up / Arrow Left to move to the previous cited insight.
  • Press Escape to clear the selection and highlight.

curl -X POST http://localhost:3000/api/ingest/fhir \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Bundle",
    "type": "collection",
    "entry": [
      {
        "resource": {
          "resourceType": "Patient",
          "id": "pat-123",
          "name": [
            {
              "use": "official",
              "given": ["John", "Edward"],
              "family": "Smith"
            }
          ],
          "gender": "male",
          "birthDate": "1980-01-01"
        }
      },
      {
        "resource": {
          "resourceType": "Observation",
          "code": {
            "coding": [
              {
                "system": "http://loinc.org",
                "code": "39156-5",
                "display": "Body Mass Index"
              }
            ]
          },
          "valueQuantity": {
            "value": 24.5,
            "unit": "kg/m2"
          }
        }
      }
    ]
  }'

The machine learning pipeline (analyze.py) implements an interpretable risk assessment model:

graph LR
    A["📂 Raw Data"] --> B["🧹 Cleaning & Validation"]
    B --> C["⚙️ Feature Engineering"]
    C --> D["📏 StandardScaler"]
    D --> E["📊 Logistic Regression"]
    E --> F["🎯 Risk Score 0–100%"]
    E --> G["📋 Feature Importance"]
    F --> H["💾 Cached Model"]
    G --> H

To prevent ingestion, extraction, NLP, and prediction pipelines from crashing or truncating notes when encountering legacy character sets or invalid sequences, a robust text sanitization layer is integrated at all boundaries (dataset imports, API payloads, CLI inputs, and daemon loops).

Clinical records are typically aggregated from disparate Electronic Health Records (EHR) systems, legacy laboratory reports, and clinician templates. These exports often use legacy encodings (e.g., Windows CP1252, ISO-8859-1) or copy-pasted smart quotes/dashes from word processors. If these raw streams are processed directly by modern UTF-8 parsers without sanitization, they raise UnicodeDecodeError exceptions, crash the daemon, or silently truncate vital note data.

1. Safe Byte Decoding: Gracefully decodes byte streams using UTF-8. If malformed sequences are encountered, they are logged as warnings and replaced rather than throwing fatal exceptions. Fallbacks to CP1252/Latin-1 are triggered dynamically if needed.
2. Unicode Normalization: Normalizes all characters to standard Unicode Normalization Form KC (NFKC).
3. Null Bytes Removal: Strips null bytes (\x00) to prevent C-level string truncation bugs in downstream tools.
4. Control Characters Cleanup: Discards non-printable control characters (Unicode category Cc and Cf) while fully preserving formatting whitespaces (\t, \n, \r).
5. Smart Quote & Dash Normalization: Converts curly quotes (“, ”, ‘, ’) and typographic dashes (–, —) to standard ASCII equivalents.
6. Unusual Whitespace Normalization: Normalizes zero-width spaces (\u200b), non-breaking spaces (\xa0), and other Unicode spaces into standard ASCII spaces or empty strings.
7. Medical Symbol Preservation: Fully preserves essential medical symbols like degrees (°), micro/mu (μ), plus-minus (±), and percentages (%) to maintain data integrity.

# Linux/macOS
python3 analyze.py

# Windows
py analyze.py

Create a patient JSON file:

{
  "gender": "Female",
  "age": 52,
  "hypertension": true,
  "heartDisease": false,
  "smokingHistory": "former",
  "bmi": 30.1,
  "hba1cLevel": 6.4,
  "bloodGlucoseLevel": 148
}

Run prediction:

# Linux/macOS
python3 analyze.py predict_file patient.json

# Windows
py analyze.py predict_file patient.json

Security: .env.local is git-ignored and should never be committed. Production builds do not expose dev credentials.

Request limits: JSON and URL-encoded API payloads are limited to 256kb by default. Add route-specific upload handling before increasing this global limit. Production sessions: When the app runs behind a TLS-terminating reverse proxy or load balancer, Express trusts one proxy hop in production so secure session cookies are issued from X-Forwarded-Proto: https requests.

• 📈 Longitudinal patient risk tracking across visits
• 💡 Counterfactual reasoning — "What single change reduces risk most?"
• 🔬 Cohort discovery and population-level insights
• 🏥 Integration with Electronic Health Records (EHR)
• ⚖️ Advanced bias detection and ML fairness metrics
• ☁️ Cloud deployment (Vercel / Render)

We love contributions! Whether it's a bug fix, a new feature, or improved docs — every PR makes a difference.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guide and Code of Conduct before submitting.

Gopal Gupta Computer Science Engineer · Full-Stack Developer · Data Science & ML Enthusiast

• All schema changes must go through drizzle-kit generate.

• Improve heading hierarchy for better readability
• Ensure consistent spacing between sections
• Use proper Markdown formatting for code blocks and lists
• Align all installation and usage steps properly

• Introduction
• Features
• Tech Stack
• Installation
• Usage
• Project Structure
• Contribution Guidelines
• License

• Add badges (optional): build, license, contributors
• Add screenshots for better UI understanding
• Standardize code blocks for commands

Improve onboarding experience for new contributors and users by making README more structured, readable, and professional.