🏥 MediBot - AI-Powered Healthcare Platform

A complete healthcare management monorepo featuring AI-powered medical assistance, patient records, appointment scheduling, and telemedicine. Includes backend API, AI agent with LLM models, web dashboard, and mobile app.

🎯 New to the project? Jump to our platform-specific setup guides:

Windows Setup Guide - Complete guide for Windows users

macOS Setup Guide - Complete guide for macOS users

Linux Setup Guide - Complete guide for Linux users

Troubleshooting Guide - Common issues and solutions

⚡ Quick Start (5 Minutes)

📖 Platform-Specific Guides Available:

Windows Users: See SETUP-WINDOWS.md for detailed Windows setup

macOS Users: See SETUP-MACOS.md for detailed macOS setup

Linux Users: See SETUP-LINUX.md for detailed Linux setup

Option 1: Automated Setup (macOS/Linux)

# 1. Clone repository
git clone https://github.com/NoelKhan/medibot-backend.git Medibot-MBSE
cd Medibot-MBSE

# 2. Start all services automatically
chmod +x scripts/development/*.sh
./scripts/development/start-all-services.sh

# 3. Verify services
./scripts/utilities/check-services.sh

Option 2: Docker (All Platforms - Recommended for Windows)

# 1. Clone repository
git clone https://github.com/NoelKhan/medibot-backend.git Medibot-MBSE
cd Medibot-MBSE/infrastructure/docker

# 2. Start all services with Docker
docker-compose up -d

# 3. Check status
docker-compose ps

🎉 Done! Access your services:

🌐 Web Dashboard: http://localhost:5173 (or http://localhost:3000 for Docker)
🔌 Backend API: http://localhost:3001/api/health
🤖 AI Agent: http://localhost:8000/health

📋 Table of Contents

What's Included
Prerequisites
Installation Guide
Testing
Deployment
- Docker (Recommended)
- Kubernetes (Production)
CI/CD Pipeline
Troubleshooting
Quick Reference

📖 Additional Guides:

Windows Setup - Detailed Windows installation guide
macOS Setup - Detailed macOS installation guide
Linux Setup - Detailed Linux installation guide
Troubleshooting - Common issues and solutions

🎯 What's Included

Component	Technology	Port	Purpose
Backend API	NestJS + TypeORM + PostgreSQL + Redis	3001	Patient records, appointments, authentication
AI Agent	Python FastAPI + Ollama + LangChain	8000	Medical symptom analysis, triage, AI chat
Web Dashboard	React 18 + Vite + Material-UI v7	5173	Healthcare provider interface
Mobile App	React Native + Expo	-	Patient mobile application

Key Features:

💬 AI medical chatbot with symptom analysis
📅 Appointment scheduling and management
📊 Patient health records and history
🎯 Emergency triage assessment
📱 Cross-platform mobile support
🔐 Secure authentication

📋 Prerequisites

System Requirements

Component	Minimum	Recommended
RAM	8GB	16GB+
Disk Space	10GB	20GB+
OS	macOS 11+, Windows 10+, Ubuntu 20.04+	Latest versions

Required Software

📦 Node.js 18.x or 20.x

macOS:

brew install node@20

Windows:

Download installer from nodejs.org
Run installer and follow prompts
Restart terminal after installation

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify:

node --version    # Should show v20.x.x
npm --version     # Should show 10.x.x

🐍 Python 3.11+

macOS:

brew install python@3.11

Windows:

Download installer from python.org
✅ IMPORTANT: Check "Add Python to PATH" during installation
Restart terminal after installation

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip

Verify:

python3 --version    # Should show 3.11.x or higher
pip3 --version       # Should show pip version

🐘 PostgreSQL 14+

macOS:

brew install postgresql@14
brew services start postgresql@14

Windows:

Download installer from postgresql.org
Run installer (remember the password you set!)
Add PostgreSQL bin to PATH: C:\Program Files\PostgreSQL\14\bin

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify:

psql --version    # Should show 14.x or higher

# macOS/Linux: Test connection
psql postgres

# Windows (PowerShell): Test connection
& "C:\Program Files\PostgreSQL\14\bin\psql.exe" -U postgres

🔴 Redis 7+

macOS:

brew install redis
brew services start redis

Windows:

Download from redis.io/download or use WSL2
Easiest: Use Docker: docker run -d -p 6379:6379 redis:7-alpine

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

Verify:

redis-cli ping    # Should return "PONG"

🤖 Ollama (for AI)

macOS:

brew install ollama
ollama serve

Windows:

Download installer from ollama.ai/download
Run installer
Ollama will start automatically

Linux:

curl -fsSL https://ollama.ai/install.sh | sh
ollama serve

Verify:

# Check if Ollama is running
curl http://localhost:11434/api/tags
# Should return JSON with model list

Optional Software

🐳 Docker & Docker Compose (Recommended for Windows users)

All Platforms:

Download Docker Desktop
Install and start Docker Desktop
Docker Compose is included

Verify:

docker --version
docker-compose --version

📱 Expo CLI (for mobile development)

All Platforms:

npm install -g expo-cli
expo --version

Quick Prerequisites Check

Run this to verify all installations:

macOS/Linux:

echo "Node: $(node --version)"
echo "Python: $(python3 --version)"
echo "PostgreSQL: $(psql --version)"
echo "Redis: $(redis-cli --version)"
echo "Ollama: $(curl -s http://localhost:11434/api/tags | grep -o 'models' || echo 'Not running')"

Windows (PowerShell):

Write-Host "Node: $(node --version)"
Write-Host "Python: $(python --version)"
Write-Host "PostgreSQL: $(psql --version)"
Write-Host "Redis: $(redis-cli --version)"
Write-Host "Ollama: $(try { (Invoke-WebRequest -Uri http://localhost:11434/api/tags).StatusCode } catch { 'Not running' })"

🛠️ Installation Guide

1. Backend + Database

Step 1.1: Start PostgreSQL & Redis

macOS

# Start services
brew services start postgresql@14
brew services start redis

# Create database
createdb medibot_db

Windows

# PostgreSQL starts automatically after installation
# Check if running:
Get-Service -Name postgresql*

# Create database (PowerShell)
& "C:\Program Files\PostgreSQL\14\bin\createdb.exe" -U postgres medibot_db

# Or use pgAdmin (GUI) to create database named 'medibot_db'

# Start Redis (if using Docker)
docker run -d -p 6379:6379 --name redis redis:7-alpine

# Or if installed via WSL
wsl redis-server

Linux

# Start services
sudo systemctl start postgresql
sudo systemctl start redis-server

# Create database
sudo -u postgres createdb medibot_db

Step 1.2: Install Backend Dependencies

# Navigate to backend folder
cd medibot-backend

# Install dependencies
npm install

Step 1.3: Configure Environment

macOS/Linux:

cp .env.example .env
nano .env  # or use your preferred editor

Windows:

copy .env.example .env
notepad .env  # or use VS Code: code .env

Required .env settings:

# Database Configuration
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password     # Use the password you set during PostgreSQL installation
DATABASE_NAME=medibot_db

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379

# AI Agent
AI_AGENT_URL=http://localhost:8000

# Security
JWT_SECRET=your-super-secret-key-change-this

# Server
PORT=3001
NODE_ENV=development

Step 1.4: Run Database Migrations

# Run migrations to create tables
npm run migration:run

Step 1.5: Start Backend

macOS/Linux:

npm run start:dev

Windows (PowerShell):

npm run start:dev

Step 1.6: Test Backend

macOS/Linux:

curl http://localhost:3001/api/health

Windows (PowerShell):

Invoke-WebRequest -Uri http://localhost:3001/api/health | Select-Object -Expand Content

Expected Response:

{"status":"ok","info":{"database":{"status":"up"},...}}

2. AI Agent + LLM Models

Step 2.1: Install Ollama

macOS

# Install Ollama
brew install ollama

# Start Ollama service
ollama serve

Windows

Download installer from ollama.ai/download
Run the installer
Ollama starts automatically as a service
Verify it's running by opening http://localhost:11434 in your browser

Linux

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama
ollama serve

Step 2.2: Choose Your AI Model

Pick based on your computer's RAM:

Model	Size	RAM Needed	Best For	Install Command
BioMistral ⭐	4.1GB	8GB	Medical-specific, best accuracy	`ollama pull biomistral`
Llama 3.2	2GB	8GB	Fast, general purpose	`ollama pull llama3.2`
MedLlama2	3.8GB	8GB	Medical-specific (alternative)	`ollama pull medllama2`
Llama 2 (7B)	3.8GB	8GB	Medical fine-tuning	`ollama pull llama2:7b`
Llama 3.1	4.7GB	16GB	Advanced	`ollama pull llama3.1`
Mistral	4.1GB	8GB	Fast & efficient	`ollama pull mistral`

Recommended (All Platforms):

ollama pull biomistral

Verify:

ollama list
ollama run biomistral "What causes headaches?"

Step 2.3: Setup AI Agent

macOS/Linux:

cd medibot-backend/python/aiagent

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Windows (PowerShell):

cd medibot-backend\python\aiagent

# Create virtual environment
python -m venv venv

# Activate virtual environment
.\venv\Scripts\Activate.ps1

# If you get execution policy error, run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Install dependencies
pip install -r requirements.txt

Step 2.4: Configure AI Agent

macOS/Linux:

cp .env.example .env
nano .env

Windows:

copy .env.example .env
notepad .env

Required .env for AI Agent:

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=biomistral
API_HOST=0.0.0.0
API_PORT=8000
BACKEND_URL=http://localhost:3001
MAX_TOKENS=2000
TEMPERATURE=0.7

Step 2.5: Start AI Agent

macOS/Linux:

# Make sure venv is activated
source venv/bin/activate

# Start AI Agent
python3 -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Windows:

# Make sure venv is activated
.\venv\Scripts\Activate.ps1

# Start AI Agent
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Step 2.6: Test AI Agent

macOS/Linux:

curl http://localhost:8000/health

Windows (PowerShell):

Invoke-WebRequest -Uri http://localhost:8000/health | Select-Object -Expand Content

Expected Response:

{"status":"healthy","services":{"ollama":"connected",...}}

3. Web Dashboard (Optional)

Step 3.1: Install Dependencies

cd medibot-web
npm install

Step 3.2: Configure Environment

macOS/Linux:

cp .env.example .env

Windows:

copy .env.example .env

Required .env:

VITE_API_URL=http://localhost:3001/api
VITE_AI_AGENT_URL=http://localhost:8000

Step 3.3: Start Web App

npm run dev

Access: http://localhost:5173

Default credentials:

Email: admin@medibot.com
Password: admin123

4. Mobile App (Optional)

📱 Note: Mobile app requires React 19.1.0 for Expo SDK 54 compatibility

Step 4.1: Install Dependencies

cd medibot-mobile
npm install

# Ensure React 19.1.0 is installed (required for Expo SDK 54)
npm list react  # Should show react@19.1.0

# If React version is incorrect, install the correct version:
npm install react@19.1.0 react-dom@19.1.0 --save-exact

# Install Expo CLI globally (if not already installed)
npm install -g expo-cli

Step 4.2: Configure Environment

macOS/Linux:

cp .env.example .env

Windows:

copy .env.example .env

Step 4.3: Find Your Computer's IP Address

⚠️ Important: Mobile devices need your computer's actual IP address, not localhost

macOS

# Method 1: Using ifconfig
ifconfig | grep "inet " | grep -v 127.0.0.1

# Method 2: Using System Preferences
# Go to System Preferences → Network → Your connection
# Look for "IP Address"

Windows

# Method 1: Using ipconfig
ipconfig | findstr IPv4

# Method 2: Using Settings
# Settings → Network & Internet → Properties
# Look for "IPv4 address"

Linux

# Method 1: Using ip command
ip addr show | grep "inet " | grep -v 127.0.0.1

# Method 2: Using hostname
hostname -I

Step 4.4: Update Environment Variables

Edit .env with your IP address:

# Replace YOUR_COMPUTER_IP with the IP address you found
API_URL=http://192.168.1.100:3001/api        # Example IP
AI_AGENT_URL=http://192.168.1.100:8000      # Example IP

Example:

If your IP is 192.168.1.100, use:
- API_URL=http://192.168.1.100:3001/api
- AI_AGENT_URL=http://192.168.1.100:8000

Step 4.5: Start Mobile App

npm start

This will:

Start the Metro bundler
Display a QR code
Provide options to run on emulator/simulator

Step 4.6: Test on Physical Device

Install Expo Go on your phone:
- iOS: Download from App Store
- Android: Download from Play Store
Scan QR Code:
- iOS: Use Camera app to scan QR code from terminal
- Android: Use Expo Go app to scan QR code
Troubleshooting Connection:
- Make sure phone and computer are on the same WiFi network
- Check firewall isn't blocking ports 3001, 8000, 8081
- Try running with tunnel: npm start -- --tunnel

Step 4.7: Run on Emulator/Simulator

Android Emulator (All Platforms):

# Start Android emulator first (Android Studio)
# Then run:
npm run android

iOS Simulator (macOS only):

# Requires Xcode to be installed
npm run ios

Windows Subsystem for Android (Windows 11):

# If you have WSA installed
npm run android

🧪 Testing

Quick Health Check for All Services

macOS/Linux

# Automated health check (if scripts work)
./scripts/utilities/check-services.sh

# Or manually check ports
lsof -i:3001  # Backend
lsof -i:8000  # AI Agent
lsof -i:5173  # Web

# Check service health
curl http://localhost:3001/api/health
curl http://localhost:8000/health

Windows (PowerShell)

# Check if ports are in use
netstat -ano | findstr :3001  # Backend
netstat -ano | findstr :8000  # AI Agent
netstat -ano | findstr :5173  # Web

# Check service health
Invoke-WebRequest -Uri http://localhost:3001/api/health
Invoke-WebRequest -Uri http://localhost:8000/health

# Or open in browser
Start-Process "http://localhost:3001/api/health"
Start-Process "http://localhost:8000/health"
Start-Process "http://localhost:5173"

Test AI Integration

macOS/Linux

curl -X POST http://localhost:3001/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"content": "I have a fever and cough"}'

Windows (PowerShell)

$body = @{
    content = "I have a fever and cough"
} | ConvertTo-Json

Invoke-WebRequest -Uri http://localhost:3001/api/chat/message `
  -Method POST `
  -ContentType "application/json" `
  -Body $body

Should return AI analysis with symptoms and recommendations.

Run Test Suites

All Platforms:

# Test all services (macOS/Linux only)
./scripts/testing/test-all.sh

# Test individual services
cd medibot-backend && npm test
cd medibot-web && npm test  
cd medibot-mobile && npm test

🚀 Deployment

Docker (All-in-One) - Recommended for All Platforms

Perfect for: Testing, demos, simple deployments, Windows users

Prerequisites:

Docker Desktop installed and running

Step 1: Navigate to Docker folder

cd infrastructure/docker

Step 2: Start all services

docker-compose up -d

Step 3: View logs (optional)

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f aiagent

Step 4: Check status

docker-compose ps

Access services:

Backend: http://localhost:3001
AI Agent: http://localhost:8000
Web: http://localhost:3000
PostgreSQL: localhost:5432
Redis: localhost:6379

Stop services:

docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

Update after code changes:

docker-compose down
docker-compose build
docker-compose up -d

Kubernetes (Production)

Perfect for: Production, auto-scaling, high availability, cloud deployments

Prerequisites:

kubectl installed
Access to a Kubernetes cluster (AWS EKS, GKE, AKS, or local with Minikube)

Step 1: Create Namespace

kubectl create namespace medibot-prod

Step 2: Create Secrets

PostgreSQL Secret

kubectl create secret generic postgres-secret \
  --from-literal=username=postgres \
  --from-literal=password=your-secure-password \
  -n medibot-prod

JWT Secret

kubectl create secret generic jwt-secret \
  --from-literal=secret=your-jwt-secret-key \
  -n medibot-prod

API Keys (if needed)

kubectl create secret generic api-keys \
  --from-literal=openai-key=your-key \
  -n medibot-prod

Step 3: Deploy Services

cd infrastructure/k8s

# Deploy in order
kubectl apply -f backend/postgres-statefulset.yaml -n medibot-prod
kubectl apply -f backend/redis-deployment.yaml -n medibot-prod
kubectl apply -f backend/ollama-statefulset.yaml -n medibot-prod
kubectl apply -f backend/backend-deployment.yaml -n medibot-prod
kubectl apply -f backend/ai-agent-deployment.yaml -n medibot-prod
kubectl apply -f web/web-deployment.yaml -n medibot-prod
kubectl apply -f ingress.yaml -n medibot-prod
kubectl apply -f hpa.yaml -n medibot-prod

Step 4: Verify Deployment

# Check all resources
kubectl get all -n medibot-prod

# Check pods status
kubectl get pods -n medibot-prod

# Check services
kubectl get svc -n medibot-prod

# Check logs if needed
kubectl logs -f deployment/backend -n medibot-prod

Step 5: Access Services

With LoadBalancer:

kubectl get svc -n medibot-prod
# Look for EXTERNAL-IP

With Port Forwarding (for testing):

# Backend
kubectl port-forward svc/backend 3001:3001 -n medibot-prod

# AI Agent
kubectl port-forward svc/ai-agent 8000:8000 -n medibot-prod

# Web
kubectl port-forward svc/web 3000:80 -n medibot-prod

Automated Deployment

Use the deploy script:

macOS/Linux:

cd infrastructure/k8s
chmod +x deploy.sh
./deploy.sh

Windows (PowerShell):

cd infrastructure\k8s
# Run commands from deploy.sh manually
# Or use WSL: wsl ./deploy.sh

Cloud Platform Deployment

AWS (Elastic Container Service)

Quick Deploy to AWS ECS

Setup AWS CLI:
```
aws configure
```

Deploy Backend:

cd medibot-backend
aws ecs register-task-definition --cli-input-json file://ecs-task-definition.json

Use GitHub Actions:
- Push to main branch
- Workflow automatically deploys to ECS
- Check .github/workflows/backend-cicd.yml

Google Cloud (GKE)

Quick Deploy to GKE

Create GKE cluster:

gcloud container clusters create medibot-cluster \
  --num-nodes=3 \
  --zone=us-central1-a

Get credentials:

gcloud container clusters get-credentials medibot-cluster

Deploy with kubectl:
```
kubectl apply -f infrastructure/k8s/
```

Azure (AKS)

Quick Deploy to AKS

Create AKS cluster:

az aks create \
  --resource-group medibot-rg \
  --name medibot-cluster \
  --node-count 3 \
  --enable-addons monitoring

Get credentials:

az aks get-credentials \
  --resource-group medibot-rg \
  --name medibot-cluster

Deploy with kubectl:
```
kubectl apply -f infrastructure/k8s/
```

Heroku (Simple Deployment)

Deploy Backend to Heroku

# Install Heroku CLI
# macOS: brew install heroku
# Windows: Download from heroku.com

# Login
heroku login

# Create apps
heroku create medibot-backend
heroku create medibot-web

# Add PostgreSQL
heroku addons:create heroku-postgresql:hobby-dev --app medibot-backend

# Add Redis
heroku addons:create heroku-redis:hobby-dev --app medibot-backend

# Deploy backend
cd medibot-backend
git push heroku main

# Deploy web
cd medibot-web
git push heroku main

🔄 CI/CD Pipeline

Our GitHub Actions workflows automatically build, test, and deploy all components.

🎯 Features

✅ Automated builds on every push to main or develop
✅ Docker images published to GitHub Container Registry (ghcr.io)
✅ Parallel execution for faster builds
✅ Security scanning with npm audit and Snyk
✅ Self-hosted runner support for cost savings and performance

📦 Pipeline Stages

Backend Pipeline (.github/workflows/backend-cicd.yml):

Lint & Type Check
Unit & Integration Tests
Security Audit
Build Docker Image → ghcr.io/noelkhan/medibot-backend
Deploy to Production/Staging

AI Agent Pipeline (.github/workflows/ai-agent-cicd.yml):

Lint & Type Check
Unit Tests
Build Docker Image → ghcr.io/noelkhan/medibot-ai-agent
Deploy to Kubernetes

Web Pipeline (.github/workflows/web-cicd.yml):

Lint & Build
Build Docker Image → ghcr.io/noelkhan/medibot-web
Deploy to Vercel (dev) or Kubernetes (prod)

Mobile Pipeline (.github/workflows/mobile-cicd.yml):

Lint & Type Check
Run Tests
Build APK with Expo
Upload artifacts

🖥️ Self-Hosted Runners

All workflows support self-hosted runners! Switch between GitHub-hosted and self-hosted runners for:

💰 Cost savings - Unlimited build minutes
⚡ Better performance - Custom hardware
🔒 Enhanced security - Private network
🎛️ Custom configuration - Pre-installed tools

Quick Setup:

# Switch to self-hosted runners
gh variable set RUNNER_TYPE --body "self-hosted"

# Switch back to GitHub-hosted (default)
gh variable set RUNNER_TYPE --body "ubuntu-latest"

📖 Full Documentation: .github/SELF-HOSTED-RUNNERS.md

Setup guides for Linux, macOS, Windows, and Docker
Security best practices
Monitoring and troubleshooting
Custom labels for specialized runners (GPU, high-memory, etc.)

Setup GitHub Secrets

Add these in Settings → Secrets and variables → Actions:

Secret	Description
`EXPO_TOKEN`	Expo authentication token
`KUBE_CONFIG`	Base64 encoded kubeconfig
`VITE_API_URL`	Web app API URL (e.g., https://api.medibot.com)
`VITE_AI_AGENT_URL`	AI agent URL (e.g., https://ai.medibot.com)
`BACKEND_URL`	Backend health check URL
`AI_AGENT_URL`	AI health check URL

Trigger workflow:

git push origin main  # Auto-triggers
# Or manually via GitHub Actions tab

🔧 Troubleshooting

Common Issues - All Platforms

"Port already in use" Error

macOS/Linux

# Find and kill process using port 3001
lsof -ti:3001 | xargs kill -9

# For other ports
lsof -ti:8000 | xargs kill -9  # AI Agent
lsof -ti:5173 | xargs kill -9  # Web

Windows (PowerShell)

# Find process ID using port 3001
netstat -ano | findstr :3001

# Kill process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Example:
taskkill /PID 12345 /F

Backend Issues

Database Connection Failed

macOS

# Check if PostgreSQL is running
brew services list | grep postgresql

# Start PostgreSQL if not running
brew services start postgresql@14

# Verify database exists
psql -l | grep medibot_db

# Create if missing
createdb medibot_db

Windows

# Check if PostgreSQL service is running
Get-Service -Name postgresql*

# Start service if stopped
Start-Service postgresql-x64-14  # Adjust version number

# Create database using pgAdmin or:
& "C:\Program Files\PostgreSQL\14\bin\createdb.exe" -U postgres medibot_db

Linux

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

# Create database
sudo -u postgres createdb medibot_db

Redis Connection Failed

macOS

# Check if Redis is running
brew services list | grep redis

# Start Redis
brew services start redis

# Test connection
redis-cli ping  # Should return PONG

Windows

# If using Docker
docker ps | findstr redis
docker start redis  # If stopped

# Or start Redis container
docker run -d -p 6379:6379 --name redis redis:7-alpine

# Test connection
redis-cli ping

Linux

# Check if Redis is running
sudo systemctl status redis-server

# Start Redis
sudo systemctl start redis-server

# Test connection
redis-cli ping

"Module not found" or "Cannot find package"

All Platforms:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json  # macOS/Linux
# Or
Remove-Item -Recurse -Force node_modules, package-lock.json  # Windows PowerShell

npm install

AI Agent Issues

Ollama Not Running

macOS

# Start Ollama
ollama serve

# Or run in background
nohup ollama serve > /dev/null 2>&1 &

Windows

Check if Ollama is running in system tray
If not, search for "Ollama" in Start Menu and launch it
Or restart the Ollama service:
1. Open Task Manager
2. Go to Services tab
3. Find "Ollama" and restart it

Linux

# Start Ollama
ollama serve

# Or run as systemd service
sudo systemctl start ollama

Model Not Found

All Platforms:

# List installed models
ollama list

# Pull required model
ollama pull llama3.2

# Verify model works
ollama run llama3.2 "Hello"

Connection Refused to Ollama

All Platforms:

# Check if Ollama is listening
curl http://localhost:11434/api/tags

# Or in browser: http://localhost:11434

Windows alternative:

Invoke-WebRequest -Uri http://localhost:11434/api/tags

Python Virtual Environment Issues

macOS/Linux

cd medibot-backend/python/aiagent

# Remove old venv
rm -rf venv

# Create new venv
python3 -m venv venv

# Activate
source venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

Windows (PowerShell)

cd medibot-backend\python\aiagent

# Remove old venv
Remove-Item -Recurse -Force venv

# Create new venv
python -m venv venv

# Activate (if execution policy error, see below)
.\venv\Scripts\Activate.ps1

# If you get execution policy error:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Reinstall dependencies
pip install -r requirements.txt

Web App Issues

Build Errors

All Platforms:

cd medibot-web

# Clear cache and reinstall
rm -rf node_modules package-lock.json .vite  # macOS/Linux
# Or
Remove-Item -Recurse -Force node_modules, package-lock.json, .vite  # Windows

npm install
npm run dev

API Connection Failed

Check Backend is Running:
- macOS/Linux: curl http://localhost:3001/api/health
- Windows: Invoke-WebRequest http://localhost:3001/api/health

Verify .env file:

VITE_API_URL=http://localhost:3001/api
VITE_AI_AGENT_URL=http://localhost:8000

Restart Dev Server:
```
# Stop with Ctrl+C, then:
npm run dev
```

Mobile App Issues

Can't Connect to Backend

Common Causes:

Using localhost instead of IP address
- ❌ Wrong: http://localhost:3001
- ✅ Correct: http://192.168.1.100:3001 (your computer's IP)
Phone and computer on different WiFi networks
- Make sure both devices are on the same network
Firewall blocking connections
- macOS: System Preferences → Security & Privacy → Firewall → Allow Node.js
- Windows: Windows Defender Firewall → Allow an app → Add Node.js
- Linux: sudo ufw allow 3001 and sudo ufw allow 8000

Metro Bundler Errors

All Platforms:

# Clear Metro bundler cache
npm start -- --clear

# Or with Expo
expo start -c

# If that doesn't work, clear watchman (macOS/Linux)
watchman watch-del-all

Expo Go Connection Issues

Try Tunnel Mode:
```
npm start -- --tunnel
```
Check Expo CLI is up to date:
```
npm install -g expo-cli@latest
```
Restart Everything:
- Close Expo Go app
- Stop Metro bundler (Ctrl+C)
- Run npm start again
- Reopen Expo Go

Docker Issues

Port Conflicts

All Platforms:

# Stop all Docker containers
docker-compose down

# Check for processes using ports
# macOS/Linux:
lsof -i:3001
lsof -i:8000

# Windows:
netstat -ano | findstr :3001
netstat -ano | findstr :8000

Build Failures

All Platforms:

# Clean build
docker-compose down -v  # Remove volumes
docker-compose build --no-cache
docker-compose up

Container Won't Start

# View logs
docker-compose logs backend
docker-compose logs aiagent
docker-compose logs web

# Restart specific service
docker-compose restart backend

Still Having Issues?

Check Prerequisites Again:
- Verify all required software is installed and running
- Check versions match requirements
Review Logs:
- Backend: Check terminal output
- AI Agent: Check terminal output
- Docker: docker-compose logs -f
Try Docker Method:
- If local setup is problematic, use Docker Compose
- It handles all dependencies automatically
Get Help:
- Create an issue: https://github.com/NoelKhan/medibot-backend/issues
- Include:
  - Your OS and version
  - Error messages
  - Steps you've already tried

📁 Project Structure

Medibot-MBSE/
├── medibot-backend/           # NestJS Backend
│   ├── src/                   # API source code
│   ├── migrations/            # Database migrations
│   └── python/aiagent/        # AI Agent (FastAPI)
├── medibot-web/               # React Web Dashboard
│   └── src/
│       ├── pages/             # Page components
│       ├── components/        # Reusable components
│       └── services/          # API services
├── medibot-mobile/            # React Native Mobile
│   └── src/
│       ├── screens/           # Screen components
│       └── services/          # API services
├── infrastructure/
│   ├── docker/                # Docker Compose
│   └── k8s/                   # Kubernetes manifests
├── scripts/                   # Automation scripts
│   ├── backend/
│   ├── web/
│   ├── mobile/
│   ├── deployment/
│   ├── development/
│   ├── testing/
│   └── utilities/
└── .github/workflows/         # CI/CD pipelines

🚀 What's Next?

Explore Features
- Chat with AI assistant
- Create appointments
- Manage patient records
- View analytics
Customize
- Modify AI prompts: medibot-backend/python/aiagent/prompts/
- Update UI themes
- Add custom features
Deploy to Cloud
- Use Docker Compose for simple deployments
- Use Kubernetes for production scale
- Enable CI/CD for automated deployments
Scale
- Kubernetes HPA included
- Add monitoring/logging
- Configure SSL certificates

� Quick Reference

Essential Commands by Platform

Start All Services

macOS/Linux (Automated)

cd /path/to/Medibot-MBSE
./scripts/development/start-all-services.sh

Windows or All Platforms (Docker)

cd infrastructure/docker
docker-compose up -d

Manual Start (All Platforms)

Terminal 1 - Backend:

cd medibot-backend
npm run start:dev

Terminal 2 - AI Agent:

cd medibot-backend/python/aiagent

# macOS/Linux
source venv/bin/activate

# Windows
.\venv\Scripts\Activate.ps1

# Then (all platforms)
python -m uvicorn app:app --host 0.0.0.0 --port 8000 --reload

Terminal 3 - Web (Optional):

cd medibot-web
npm run dev

Terminal 4 - Mobile (Optional):

cd medibot-mobile
npm start

Check Service Status

macOS/Linux:

# Check if running
lsof -i:3001  # Backend
lsof -i:8000  # AI Agent
lsof -i:5173  # Web

# Health checks
curl http://localhost:3001/api/health
curl http://localhost:8000/health

Windows (PowerShell):

# Check if running
netstat -ano | findstr :3001  # Backend
netstat -ano | findstr :8000  # AI Agent
netstat -ano | findstr :5173  # Web

# Health checks
Invoke-WebRequest -Uri http://localhost:3001/api/health
Invoke-WebRequest -Uri http://localhost:8000/health

Docker:

docker-compose ps
docker-compose logs -f

Stop All Services

macOS/Linux (Automated):

./scripts/development/stop-all.sh

Windows or All Platforms (Docker):

cd infrastructure/docker
docker-compose down

Manual (All Platforms):

Press Ctrl+C in each terminal window running a service

Environment Files Quick Setup

macOS/Linux:

# Backend
cd medibot-backend && cp .env.example .env

# AI Agent
cd python/aiagent && cp .env.example .env

# Web
cd ../../medibot-web && cp .env.example .env

# Mobile
cd ../medibot-mobile && cp .env.example .env

Windows (PowerShell):

# Backend
cd medibot-backend; copy .env.example .env

# AI Agent
cd python\aiagent; copy .env.example .env

# Web
cd ..\..\medibot-web; copy .env.example .env

# Mobile
cd ..\medibot-mobile; copy .env.example .env

Install All Dependencies

macOS/Linux:

# Backend
cd medibot-backend && npm install

# AI Agent
cd python/aiagent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Web
cd ../../medibot-web && npm install

# Mobile
cd ../medibot-mobile && npm install

Windows (PowerShell):

# Backend
cd medibot-backend; npm install

# AI Agent
cd python\aiagent
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Web
cd ..\..\medibot-web; npm install

# Mobile
cd ..\medibot-mobile; npm install

Reset Everything (Clean Start)

macOS/Linux:

# Stop all services
./scripts/development/stop-all.sh

# Remove node_modules
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

# Remove Python venv
rm -rf medibot-backend/python/aiagent/venv

# Reinstall
cd medibot-backend && npm install
cd python/aiagent && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
cd ../../medibot-web && npm install
cd ../medibot-mobile && npm install

Windows (PowerShell):

# Stop services (Ctrl+C in each terminal)

# Remove dependencies
Get-ChildItem -Path . -Include node_modules -Recurse -Force | Remove-Item -Recurse -Force
Remove-Item -Recurse -Force medibot-backend\python\aiagent\venv

# Reinstall
cd medibot-backend; npm install
cd python\aiagent; python -m venv venv; .\venv\Scripts\Activate.ps1; pip install -r requirements.txt
cd ..\..\medibot-web; npm install
cd ..\medibot-mobile; npm install

Docker (All Platforms):

cd infrastructure/docker
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

Common URLs

Service	URL	Purpose
Backend API	http://localhost:3001/api	Main API endpoints
Backend Health	http://localhost:3001/api/health	Backend status check
AI Agent	http://localhost:8000	AI agent API
AI Agent Health	http://localhost:8000/health	AI agent status
AI Docs	http://localhost:8000/docs	FastAPI documentation
Web App	http://localhost:5173	Web dashboard (dev)
Web App (Docker)	http://localhost:3000	Web dashboard (production)
Ollama API	http://localhost:11434	Ollama API

Default Credentials

Web Dashboard:

Email: admin@medibot.com
Password: admin123

PostgreSQL (local):

Username: postgres
Password: (set during installation)
Database: medibot_db
Port: 5432

Redis (local):

Host: localhost
Port: 6379
Password: (none for local)

📞 Support & Contributing

Getting Help

Check Troubleshooting Section above first
Search existing issues: https://github.com/NoelKhan/medibot-backend/issues
Create new issue if problem persists
Join discussions: https://github.com/NoelKhan/medibot-backend/discussions

When Reporting Issues

Please include:

OS and version (e.g., Windows 11, macOS 14, Ubuntu 22.04)
Node.js version: node --version
Python version: python --version or python3 --version
Error messages (full error text)
Steps to reproduce
What you've already tried from troubleshooting

Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

License

MIT License - see LICENSE file for details

🎯 What's Next?

For Developers

Explore the Code:
- Backend: medibot-backend/src/
- AI Agent: medibot-backend/python/aiagent/
- Web: medibot-web/src/
- Mobile: medibot-mobile/src/
Customize Features:
- Modify AI prompts: medibot-backend/python/aiagent/prompts/
- Update themes: medibot-web/src/theme/ or medibot-mobile/src/theme/
- Add new API endpoints: medibot-backend/src/modules/
Run Tests:
```
npm test  # In any component folder
```

For Deployment

Development: Use Docker Compose
Staging/Production: Use Kubernetes
CI/CD: GitHub Actions configured (see .github/workflows/)

For Scaling

Horizontal Pod Autoscaling: Already configured in infrastructure/k8s/hpa.yaml
Database Replication: Configure PostgreSQL primary-replica
Caching: Redis configured for session and data caching
Load Balancing: Kubernetes ingress with multiple replicas

Built with ❤️ for better healthcare access

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github		.github
docs		docs
infrastructure		infrastructure
medibot-backend		medibot-backend
medibot-mobile		medibot-mobile
medibot-web		medibot-web
scripts		scripts
tests/load		tests/load
.gitignore		.gitignore
DEPLOYMENT-GUIDE.md		DEPLOYMENT-GUIDE.md
K8S_TEST_RESULTS.md		K8S_TEST_RESULTS.md
README.md		README.md
SETUP-LINUX.md		SETUP-LINUX.md
SETUP-MACOS.md		SETUP-MACOS.md
SETUP-WINDOWS.md		SETUP-WINDOWS.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
VERIFICATION_SUMMARY.txt		VERIFICATION_SUMMARY.txt

Folders and files

Latest commit

History

Repository files navigation

🏥 MediBot - AI-Powered Healthcare Platform

⚡ Quick Start (5 Minutes)

Option 1: Automated Setup (macOS/Linux)

Option 2: Docker (All Platforms - Recommended for Windows)

📋 Table of Contents

🎯 What's Included

📋 Prerequisites

System Requirements

Required Software

Optional Software

Quick Prerequisites Check

🛠️ Installation Guide

1. Backend + Database

Step 1.1: Start PostgreSQL & Redis

Step 1.2: Install Backend Dependencies

Step 1.3: Configure Environment

Step 1.4: Run Database Migrations

Step 1.5: Start Backend

Step 1.6: Test Backend

2. AI Agent + LLM Models

Step 2.1: Install Ollama

Step 2.2: Choose Your AI Model

Step 2.3: Setup AI Agent

Step 2.4: Configure AI Agent

Step 2.5: Start AI Agent

Step 2.6: Test AI Agent

3. Web Dashboard (Optional)

Step 3.1: Install Dependencies

Step 3.2: Configure Environment

Step 3.3: Start Web App

4. Mobile App (Optional)

Step 4.1: Install Dependencies

Step 4.2: Configure Environment

Step 4.3: Find Your Computer's IP Address

Step 4.4: Update Environment Variables

Step 4.5: Start Mobile App

Step 4.6: Test on Physical Device

Step 4.7: Run on Emulator/Simulator

🧪 Testing

Quick Health Check for All Services

Test AI Integration

Run Test Suites

🚀 Deployment

Docker (All-in-One) - Recommended for All Platforms

Kubernetes (Production)

Step 1: Create Namespace

Step 2: Create Secrets

Step 3: Deploy Services

Step 4: Verify Deployment

Step 5: Access Services

Automated Deployment

Cloud Platform Deployment

AWS (Elastic Container Service)

Google Cloud (GKE)

Azure (AKS)

Heroku (Simple Deployment)

🔄 CI/CD Pipeline

🎯 Features

📦 Pipeline Stages

🖥️ Self-Hosted Runners

Setup GitHub Secrets

🔧 Troubleshooting

Common Issues - All Platforms

"Port already in use" Error

Backend Issues

Database Connection Failed

Redis Connection Failed

"Module not found" or "Cannot find package"

AI Agent Issues

Ollama Not Running

Model Not Found

Connection Refused to Ollama

Python Virtual Environment Issues

Web App Issues

Build Errors

API Connection Failed

Packages