PathPulse AI

PathPulse AI is a real-time surface stability classification and fall risk analysis application tailored for wheelchair users and elderly mobility. By harnessing inertial measurement unit (IMU) sensor data (accelerometer and gyroscope) directly from a browser-capable device, PathPulse AI uses machine learning to classify surface types (Stable, Moderate, Unstable), compute safety scores, and track routes dynamically.

---

🚀 Key Features

• Real-Time IMU Sensor Acquisition: Capture device motion events (acceleration and rotation rate) directly through standard browser APIs.
• Interactive Live Waveform Canvas: High-fidelity HTML5 Canvas rendering of live gyro impulses and acceleration inputs.
• Machine Learning Analysis: An ensemble VotingClassifier (comprising RandomForestClassifier, ExtraTreesClassifier, and GradientBoostingClassifier) trained on IMU feature signatures.
• Mobility Risk Scoring: Calculates custom safety metrics:
  • Fall Risk Index (0% - 100%)
  • Wheelchair Score (0 - 100)
  • Elderly Score (0 - 100)
• User Dashboard & Analytics: Custom user homepages showing daily average risk trends (rendered as dynamic SVGs), historical routes, activity distributions, and audit logs.
• Labeling & Dataset Builder: Easily record, review, label, and export training data for model retraining.
• One-Click Startup: Auto-managing batch script (start.bat) that handles virtual environment activation, dependency checks, dataset preparation, auto-training, and server launch.
• Mobile Device Tunneling: Secure local-to-public tunneling using Cloudflare Quick Tunnels (start_public.bat) for easy mobile device field-testing.

---

🛠 Tech Stack

• Backend Framework: FastAPI (Python 3.10+)
• Database ORM: SQLAlchemy (SQLite by default, PostgreSQL supported)
• Machine Learning: scikit-learn, pandas, numpy, joblib
• Frontend Layer: Vanilla HTML5, CSS (Premium responsive themes with Dark Mode toggle), Modern typography (Sora and Plus Jakarta Sans), and JavaScript (dynamic data binding and HTML5 Canvas canvas drawing).

---

📂 Project Structure

PathPulse AI/
│
├── frontend/                     # Frontend templates and static assets
│   ├── static/
│   │   ├── css/app.css           # Custom styling (layouts, themes, and animations)
│   │   └── js/app.js             # Core frontend controller (IMU polling, canvas rendering, APIs)
│   └── templates/
│       ├── index.html            # User homepage with KPI summaries
│       ├── dashboard.html        # Historical stats and SVG charts
│       ├── analysis.html         # Live sensor recording and classification panel
│       ├── routes.html           # Route history list
│       ├── settings.html         # User profile manager
│       ├── login.html            # User login page
│       └── register.html         # User registration page
│
├── main.py                       # FastAPI application (routing, session, auth, api endpoints)
├── ml_model.py                   # Model interface (inference, feature normalization, score scaling)
├── train_model.py                # Model training script (voting classifier, dataset synthesis)
├── signal_features.py            # Feature extraction (RMS, variance, entropy, peak frequency, tilt)
├── database.py                   # SQLAlchemy connection configuration
├── models.py                     # SQLAlchemy models (User, Route, TrainingSample, ActivityLog)
├── collect_training_data.py      # Database exporter tool
├── requirements.txt              # Project dependencies
├── Dockerfile                    # Containerization instructions
├── DEPLOYMENT.md                 # Server deployment instructions
├── start.bat                     # Quick-launch script (automatic environment/model setup)
└── start_public.bat              # Quick-tunnel script (Cloudflare Tunnel for mobile testing)

---

⚙️ Installation & Running Local

1. The Quick Start (Windows)

Double-click start.bat or run:

.\start.bat

This batch script will:

1. Locate or create a Python virtual environment (.venv).
2. Install dependencies listed in requirements.txt.
3. Check for the presence of a trained model (model.pkl). If missing, it will auto-train one on a synthetic dataset (28,000 samples) to bootstrap the classifier.
4. Auto-rotate session secrets for security.
5. Open your default web browser to http://127.0.0.1:8000/login and start the backend service.

2. Manual Setup (Any OS)

If you prefer to configure the project manually, execute:

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# or: .venv\Scripts\activate  # On Windows

# Install packages
pip install -r requirements.txt

# (Optional) Pre-train the model if model.pkl does not exist
python train_model.py --samples 28000

# Start server
python run.py

---

📱 Mobile Field Testing (Cloudflare Quick Tunnel)

Because desktop environments lack physical accelerometer/gyroscope hardware, testing real-time surface measurement requires a mobile device.

To connect your phone to your local dev environment:

1. Keep the local website running.
2. Run start_public.bat in a separate terminal:

   .\start_public.bat

3. The script downloads Cloudflare's tunneling client and hosts a temporary public link (e.g., https://*.trycloudflare.com).
4. Copy the public link and open it in your mobile phone's browser.
5. Navigate to the Analysis page, tap Record & Predict, and grant motion/gyroscope permissions to start capturing real-world vibrations!

---

📊 Training Custom Models

To train the machine learning models on custom collected data:

1. Use the Analysis page on your mobile device to record various route surfaces.
2. Provide ground-truth labels (Stable, Moderate, Unstable) and save them to the database.
3. Export the collected database samples to a training-ready CSV:

   python collect_training_data.py export --out data/my_custom_dataset.csv

4. Retrain the classifier using the exported data:

   python train_model.py --data data/my_custom_dataset.csv

5. Restart the FastAPI server to reload the newly trained model cache.

---

🐳 Docker Deployment

The application is fully containerized. To deploy or run locally using Docker:

1. Build the Docker Image:

   docker build -t pathpulse-ai .

2. Run the Container:

   docker run -d --name pathpulse-ai -p 8000:8000 \
     -e SESSION_SECRET=choose-a-strong-secret \
     -e DATABASE_URL=sqlite:////app/data/microstability.db \
     -v pathpulse_data:/app/data \
     pathpulse-ai

For detailed deployment guides (including cloud hosting platforms like Render or PostgreSQL configurations), refer to DEPLOYMENT.md.