Heartlytics — Heart Disease Risk Prediction

Heartlytics is a full‑stack Flask web app that predicts heart disease risk using a trained Random Forest model. It offers single‑patient scoring, batch uploads with cleaning and EDA, interactive dashboards, simulations, and PDF exports — wrapped with RBAC, MFA, CSRF, strong password storage, and application‑level encryption for sensitive data.

Clinicians and researchers need a simple, privacy‑aware way to score heart disease risk across individual patients and cohorts.

Practical hurdles: data normalization across CSVs, repeatability of insights, secure handling of PII/PHI, and operational guardrails (RBAC, auditability, rate‑limits).

• Single‑patient and batch prediction flows with resilient input validation and cleaning.
• Exploratory analytics (correlations, distributions, outlier detection) to assess data quality and cohort patterns.
• Role‑aware views and dashboards for different stakeholder needs.
• Built‑in security controls: CSRF, session timeout, MFA, rate limiting, application‑level envelope encryption for patient data and MFA secrets.

• Sign up / Login: Password rules and strength hints; optional two‑step verification (TOTP or email code).
• Forgot password: enumeration‑safe OTP with resend cooldown, TTL, and attempt limits.
• Predict: Single‑patient form with guided validation and instant probability, risk band, and age‑projection simulation.
• Batch Upload: CSV upload → column mapping → cleaning log → EDA → predictions; tolerant of common UCI aliases and formats.
• Dashboard: KPIs, histograms/KDE, correlations, cluster summaries; export as a comprehensive PDF (with generated visuals).
• Simulations: “What‑if” projections (e.g., age curves) for patient risk trajectories.
• Research: Built‑in viewer for the bundled research paper with figures and references.
• Settings: Profile, password changes, MFA setup/recovery, and recent activity cues.

• Clinical efficiency: simplify triage and follow-ups with structured outputs and patient-level reports.
• Data operations: normalize messy CSVs and preserve consistency across analyses.
• Governance: RBAC, auditability, and encryption aid compliance alignment and stakeholder trust.
• Communication: exportable PDFs for patient handouts, referrals, or internal review.
• Extensible foundation: modular services and clear boundaries for integrating queues, external KMS, or managed databases.

• Authentication & Session: Flask-Login sessions; 30-minute idle timeout; login rate limits (per-IP/per-identifier). Passwords hashed with Argon2id; legacy PBKDF2 hashes upgraded on login.
• MFA & Recovery: TOTP app support with recovery codes; email-based MFA challenges (single-use, TTL, cooldown, masked delivery).
• CSRF & Headers: CSRF tokens for forms and API endpoints; hardened headers (no‑sniff/frame denial/referrer).
• OTP Hygiene: OTPs hashed with a server‑side pepper and compared in constant time; attempt caps and resend cooldowns.
• RBAC: Server‑side decorators for module access; navigation hides unauthorized links; strict mode available.
• Application‑Level Encryption: Envelope encryption (AES‑GCM) for patient data and MFA secrets; per‑item DEKs wrapped by a keyring (dev keyring by default; cloud KMS placeholders ready). Context binding in AAD; key versioning for rotation; cryptographic erasure via key disablement.
• Email Safety: Structured logging with masked addresses; transports via TLS; diagnostics events retained.
• Notes: Diagrams and DFDs clarify trust boundaries and data classes. This is not a medical device; see Disclaimer.

• Backend: Flask, Flask‑SQLAlchemy, Flask‑Login, Flask‑WTF.
• ML: scikit‑learn (Random Forest); pandas, numpy.
• Visualization: matplotlib, seaborn (server‑rendered PDFs).
• PDFs: ReportLab (dashboard and patient reports).
• Crypto: cryptography (AES‑GCM), argon2‑cffi; envelope encryption with keyring abstractions.
• Frontend: Bootstrap 5 theme, custom charts, light/dark theme with SSR awareness.

Prerequisites

• Python 3.11+, pip, a virtualenv, and optional SMTP credentials for email flows.

Install

# Create and activate a virtualenv
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Install
pip install -r requirements.txt

# Configure
cp .env.example .env
# then set in .env:
# FLASK_ENV=development
# SECRET_KEY=<random-hex>
# DATABASE_URI=sqlite:///instance/app.db
# SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD (optional)
# ENCRYPTION: ENCRYPTION_ENABLED=1, KMS_PROVIDER=dev

# Run (dev)
flask --app app run --debug  # http://127.0.0.1:5000/

Model

Ensure ml/model.pkl exists (repo provides it). If missing, UI will show “Model not loaded”. Replace with your trained model if desired.

Quick Test Drive

• Create an account, log in, try single Predict.
• For batch: Upload a UCI‑style CSV; map columns; review cleaning log and EDA; download PDF.
• Try MFA setup (TOTP) and the forgot‑password flow.

What worked

• Cohesive stack that balances data science and product needs.
• Security by design: CSRF, RBAC, MFA, and envelope encryption in the app layer.
• Resilient CSV handling that tolerates real‑world messiness.

Next improvements

• External KMS integrations (AWS/GCP/Azure) for production key management.
• Redis‑backed rate limiting and cool‑downs; job queue for heavy exports.
• Explainability (e.g., SHAP), drift monitoring, and model versioning.
• SSO/OIDC, consent management, and formal data retention windows.
• Compliance hardening (HIPAA/GDPR mappings), audit trails, and DPA templates.
• CI/CD, secret scanning, and multi‑env deploy scripts.

Heartlytics is a demonstration/portfolio project, not a medical device and not clinical advice. Do not use it to diagnose, treat, or manage health conditions. Production use would require thorough clinical validation, security hardening, regulatory alignment, and organizational controls beyond this codebase.