🩺 AI Dialysis Digital Twin

Predictive patient simulation powered by AI — helping clinicians visualize dialysis risks before they happen.

---

🚀 Live Demo

Environment	URL	Status
Frontend	http://localhost:3000	✅ Running
Backend API	http://localhost:5000	✅ Running
Health Check	GET /health	✅ {"status":"OK"}

🔐 Note: This is a clinical decision support tool. All outputs require physician review.

---

✨ Key Features

🧬 Digital Twin Simulation Engine

• Toxin Buildup Modeling: Simulates uremic toxin accumulation over time using patient-specific parameters
• Fluid Accumulation Tracking: Predicts fluid retention based on intake and dialysis history
• Dynamic Risk Classification: Automatically categorizes risk as 🔵 Low / 🟡 Medium / 🔴 High

🤖 AI-Powered Clinical Insights

• LLM Integration: Connects to OpenAI-compatible endpoints for natural language explanations
• Context-Aware Guidance: Generates patient-specific recommendations based on simulation output
• Safety-First Prompts: Built-in medical disclaimer and non-diagnostic guardrails

📊 Interactive Visualization Dashboard

• Real-Time Charts: Live updating line graphs for toxin and fluid trends (Recharts)
• Scenario Testing: One-click "Skip Dialysis", "Delay 24h", and "Reset" simulations
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices

💾 Persistent Patient History

• MongoDB Storage: Saves all simulation runs with timestamps
• Audit Trail: Track patient parameter changes and risk progression over time

---

🛠️ Tech Stack

Backend (Node.js + Express)

Technology	Purpose	Version
Express.js	REST API framework	^4.18.2
Mongoose	MongoDB ODM	^8.0.0
Axios	HTTP client for LLM API	^1.6.0
dotenv	Environment variable management	^16.3.1
cors	Cross-origin request handling	^2.8.5

Frontend (React + Vite)

Technology	Purpose	Version
React 18	UI library	^18.2.0
Vite	Build tool & dev server	^5.0.0
Tailwind CSS	Utility-first styling	^3.4.0
Recharts	Interactive data visualization	^2.10.3
Axios	API communication	^1.6.0
Lucide React	Icon library	^0.294.0

Infrastructure

Component	Technology
Database	MongoDB (Local or Atlas)
LLM Provider	OpenAI-compatible API (Ollama, LiteLLM, etc.)
Deployment Ready	Docker, Vercel, Render, Railway

---

📐 Architecture Overview

┌─────────────────────────────────────────────────┐
│                 Frontend (React)                 │
│  ┌─────────────────────────────────────────┐   │
│  │  • Input Form (Patient Parameters)      │   │
│  │  • Scenario Buttons (Skip/Delay/Reset)  │   │
│  │  • Recharts Visualization (Toxin/Fluid) │   │
│  │  • AI Insight Card (Markdown Rendered)  │   │
│  └─────────────────────────────────────────┘   │
└─────────────┬─────────────────┬─────────────────┘
              │ HTTP/JSON       │
              ▼                 ▼
┌─────────────────────┐ ┌─────────────────────┐
│   Backend (Node)    │ │   LLM API Service   │
│  ┌───────────────┐  │ │  ┌───────────────┐  │
│  │ Simulation    │  │ │  │ Prompt        │  │
│  │ Engine        │──┼─┼─►│ Engineering   │  │
│  │ • Toxin Model │  │ │  │ • System Msg  │  │
│  │ • Fluid Model │  │ │  │ • Safety      │  │
│  │ • Risk Logic  │  │ │  │ • Formatting  │  │
│  └───────┬───────┘  │ │  └───────┬───────┘  │
│          │          │ │          │          │
│  ┌───────▼───────┐  │ │  ┌───────▼───────┐  │
│  │ MongoDB       │  │ │  │ Response      │  │
│  │ • Simulation  │  │ │  │ Parsing &     │  │
│  │   History     │  │ │  │ Cleaning      │  │
│  └───────────────┘  │ │  └───────────────┘  │
└─────────────────────┘ └─────────────────────┘

---

⚙️ Installation & Setup

Prerequisites

• Node.js ≥ 18.x
• npm ≥ 9.x
• MongoDB ≥ 7.0 (local or Atlas)
• LLM API Access (Ollama, OpenAI-compatible endpoint)

---

🔧 Backend Setup

# 1. Navigate to backend directory
cd ai-dialysis-digital-twin-backend

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
nano .env  # Edit with your values (see below)

# 4. Start MongoDB (if running locally)
sudo systemctl start mongod  # Linux
# or
brew services start mongodb-community  # macOS

# 5. Start development server
npm run dev

📋 Backend .env Configuration

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://127.0.0.1:27017/ai_dialysis_twin

# LLM API (OpenAI-compatible)
WEBUI_BASE_URL=https://chat.ivislabs.in/api
API_KEY= <our personal api key>
DEFAULT_MODEL=llama3.2-vision:latest

💡 Testing LLM Connection:

curl -X POST $WEBUI_BASE_URL/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"'$DEFAULT_MODEL'","messages":[{"role":"user","content":"Hello"}]}'

---

🎨 Frontend Setup

# 1. Navigate to frontend directory
cd ai-dialysis-digital-twin-frontend

# 2. Install dependencies
npm install

# 3. Start development server
npm run dev

📋 Frontend .env.local (Optional)

# Override API base URL if backend is on different host
VITE_API_BASE=http://localhost:5000

✅ Default: Uses Vite proxy (/simulate → http://localhost:5000/simulate)

---

📡 API Documentation

POST /simulate

Run patient simulation and return predictive data

Request Body

{
  "age": 65,
  "weight": 75,
  "hours_since_dialysis": 24,
  "fluid_intake": 1.5
}

Response

{
  "success": true,
  "simulationId": "6789abcd1234...",
  "toxin_levels_over_time": [5.0, 7.8, 10.6, ...],
  "fluid_levels_over_time": [0.15, 0.21, 0.27, ...],
  "hours": [0, 1, 2, ...],
  "risk_level": "Low"
}

Risk Classification Logic

Risk Level	Toxin Threshold (mg/dL)	Clinical Interpretation
🔵 Low	< 45	Within acceptable post-dialysis range
🟡 Medium	45 - 74	Elevated; monitor closely
🔴 High	≥ 75	Critical; immediate clinical review recommended

---

POST /ai-advice

Generate human-readable AI explanation of simulation results

Request Body

{
  "risk_level": "Low",
  "current_toxin": 15.2,
  "current_fluid": 0.51,
  "hours": 24
}

Response

{
  "success": true,
  "advice": "Fluid Accumulation: This measures how much extra fluid...\n\nRisk Classification: Low\n\nRecommendation: Continue current dialysis schedule..."
}

🛡️ Safety Note: All AI responses include mandatory disclaimer: "For clinical support only. Not a substitute for professional medical advice."

---

GET /health

Server health check endpoint

Response

{
  "status": "OK",
  "timestamp": "2026-04-27T10:30:00.000Z"
}

---

🗂️ Project Structure

ai-dialysis-digital-twin/
├── 📁 ai-dialysis-digital-twin-backend/
│   ├── 📄 server.js                 # Express app entry point
│   ├── 📄 .env                      # Environment variables
│   ├── 📄 package.json              # Backend dependencies
│   ├── 📁 controllers/              # Request handlers
│   │   └── 📄 simulationController.js
│   ├── 📁 models/                   # Mongoose schemas
│   │   └── 📄 Simulation.js
│   ├── 📁 routes/                   # API route definitions
│   │   └── 📄 simulation.js
│   ├── 📁 services/                 # Business logic
│   │   ├── 📄 simulationEngine.js   # Toxin/fluid formulas
│   │   └── 📄 llmService.js         # LLM API integration
│   └── 📁 utils/                    # Helpers
│       ├── 📄 db.js                 # MongoDB connection
│       └── 📄 errorMiddleware.js    # Global error handler
│
└── 📁 ai-dialysis-digital-twin-frontend/
    ├── 📄 vite.config.js            # Vite + proxy config
    ├── 📄 tailwind.config.js        # Tailwind CSS config
    ├── 📄 package.json              # Frontend dependencies
    ├── 📁 src/
    │   ├── 📄 main.jsx              # React entry point
    │   ├── 📄 App.jsx               # Root component
    │   ├── 📄 index.css             # Global styles + Tailwind
    │   ├── 📁 pages/
    │   │   └── 📄 Dashboard.jsx     # Main application page
    │   ├── 📁 components/
    │   │   ├── 📄 InputForm.jsx     # Patient data form
    │   │   ├── 📄 SimulationChart.jsx # Recharts visualization
    │   │   ├── 📄 AIInsightCard.jsx # LLM response display
    │   │   └── 📄 ScenarioButtons.jsx # Skip/Delay/Reset controls
    │   ├── 📁 services/
    │   │   └── 📄 api.js            # Axios API client
    │   └── 📁 utils/
    │       ├── 📄 constants.js      # Colors, thresholds, config
    │       └── 📄 formatText.js     # Markdown cleaning utility
    └── 📁 public/                   # Static assets

---

🎯 Usage Guide

Step 1: Launch Application

# Terminal 1: Backend
cd ai-dialysis-digital-twin-backend && npm run dev

# Terminal 2: Frontend  
cd ai-dialysis-digital-twin-frontend && npm run dev

# Open browser: http://localhost:3000

Step 2: Enter Patient Parameters

Field	Description	Example
Age	Patient age in years	65
Weight	Current weight in kg	75
Hours Since Dialysis	Time elapsed since last session	24
Fluid Intake	Daily fluid consumption in liters	1.5

Step 3: Run Simulation

1. Click "🚀 Run Digital Twin Simulation"
2. Wait ~2 seconds for backend processing
3. View interactive charts updating in real-time

Step 4: Explore Scenarios

Button	Effect	Use Case
⏭️ Skip Dialysis	Simulates missing next session (72h total)	Assess emergency risk
⏰ Delay by 24h	Pushes next session by 1 day (48h total)	Evaluate scheduling flexibility
🔄 Reset	Returns to post-dialysis baseline (0h)	Compare against current state

Step 5: Review AI Insights

• 🟢 Green badge: Low risk — continue current protocol
• 🟡 Amber badge: Medium risk — increase monitoring frequency
• 🔴 Red badge: High risk — immediate clinical consultation advised

💡 Pro Tip: Click scenario buttons after initial simulation to instantly compare risk trajectories.

---

🧪 Testing

Backend API Tests

# Test simulation endpoint
curl -X POST http://localhost:5000/simulate \
  -H "Content-Type: application/json" \
  -d '{"age":65,"weight":75,"hours_since_dialysis":36,"fluid_intake":1.8}'

# Test AI advice endpoint
curl -X POST http://localhost:5000/ai-advice \
  -H "Content-Type: application/json" \
  -d '{"risk_level":"Medium","current_toxin":52.3,"current_fluid":1.2,"hours":36}'

# Health check
curl http://localhost:5000/health

Frontend Manual Testing Checklist

• Form validation prevents invalid inputs
• Charts render with smooth animations
• Risk badge color matches classification logic
• AI insight card displays cleaned markdown (no ** symbols)
• Scenario buttons update charts without page reload
• Responsive layout works on mobile (320px width)

---

🔐 Security & Compliance Notes

Data Handling

• ✅ No PHI (Protected Health Information) stored — all data is demo/simulated
• ✅ Patient identifiers are auto-generated UUIDs, not real names/IDs
• ✅ MongoDB connection uses local/Atlas with authentication recommended for production

AI Safety Guardrails

• ✅ System prompt explicitly prohibits diagnostic statements
• ✅ All AI responses include mandatory medical disclaimer
• ✅ Risk thresholds based on simplified clinical guidelines (not diagnostic criteria)

Production Recommendations

# For production deployment:
NODE_ENV=production
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/ai_dialysis?retryWrites=true
CORS_ORIGIN=https://your-production-domain.com
RATE_LIMIT=100  # Requests per hour per IP

---

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request with detailed description

Code Standards

• Backend: ESLint + Prettier config available on request
• Frontend: Tailwind utility classes preferred over custom CSS
• Commits: Conventional Commits format (feat:, fix:, docs:)

---

👥 Team & Credits

Role	Contributor
Full-Stack Development	[Your Name/Team Name]
Clinical Logic Design	Nephrology Consultant Review
UI/UX Design	Medical Dashboard Best Practices
AI Integration	OpenAI-Compatible LLM Providers

🙏 Special thanks to the open-source community: Express, Mongoose, React, Tailwind, Recharts, and Lucide.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

MIT License

Copyright (c) 2026 AI Dialysis Digital Twin Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

⚠️ Medical Disclaimer

🩺 IMPORTANT: This application is a educational demonstration tool only.

• ❌ NOT a medical device
• ❌ NOT FDA-cleared or CE-marked
• ❌ NOT intended for diagnosis, treatment, or clinical decision-making
• ✅ FOR hackathon demonstration, educational purposes, and concept validation

All clinical decisions must be made by qualified healthcare professionals using approved medical devices and evidence-based guidelines. Always consult a nephrologist for dialysis management.

---

🆘 Support & Troubleshooting

Common Issues

Problem	Solution
404 Not Found on /simulate	Verify backend is running on port 5000; check vite.config.js proxy config
MongoDB connection error	Ensure mongod service is running; verify MONGODB_URI in .env
AI insights show ** symbols	Confirm formatText.js utility is imported in AIInsightCard.jsx
Charts not rendering	Check that backend response includes hours, toxin_levels_over_time, fluid_levels_over_time arrays of equal length
Tailwind styles not applying	Verify content array in tailwind.config.js includes "./src/**/*.{js,ts,jsx,tsx}"

Get Help

1. Check browser DevTools → Console & Network tabs
2. Review backend terminal logs for error messages
3. Test API endpoints directly with curl (see Testing section)
4. Open an issue in this repository with:
   • Exact error message
   • Steps to reproduce
   • Node.js/npm versions (node -v, npm -v)

---

🌟 Why This Project Stands Out

✅ Hackathon-Ready: Complete MERN stack, fully functional in <5 minutes
✅ Clinically Grounded: Simplified but realistic dialysis physiology models
✅ AI-Enhanced: LLM integration with safety guardrails, not just a wrapper
✅ Production-Prepared: Modular architecture, error handling, environment config
✅ Evaluator-Friendly: Clear documentation, one-command setup, visual demo flow

---

🚀 Ready to demo?

# Backend
cd backend && npm run dev

# Frontend  
cd frontend && npm run dev

# Open: http://localhost:3000

Built with ❤️ for better patient outcomes 🩺💙