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.
Overview
Problem
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).
Solution
- ✓Single‑patient and batch prediction flows with resilient input validation
- ✓Exploratory analytics (correlations, distributions, outlier detection)
- ✓Role‑aware views and dashboards for different stakeholder needs
- ✓Built‑in security controls: CSRF, session timeout, MFA, rate limiting
User Experience Flow
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
Simulations
"What‑if" projections (e.g., age curves) for patient risk trajectories
Business Value
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.
Evidence Library
A curated visual tour of the dataset, system architecture, and security controls so stakeholders can see the story — not just read it.
Data Signals
EDA assets that explain cohort composition, feature interactions, and the clinical signal behind the Random Forest model.
Age distribution by chest pain type
Shows how typical ages shift across chest pain segments so we can reason about confounding effects and composite features.
Architecture & Flow
C4 slices, ERDs, and runtime flows that help engineers orient themselves before touching the repo.
C4 Level 1 — Context
Situates Heartlytics among users, auth providers, and research tooling to define the project boundary.
Security & Governance
Process diagrams and crypto flows that operationalize RBAC, MFA, OTP hygiene, and envelope encryption.
BPMN for two-step verification
Business process that drives MFA enrollment and verification paths, including failure handling.
Security & Compliance
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).
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.
Roles & Permissions
SuperAdmin
Full access to all modules
Admin
Admin panel only
Doctor
Clinical workflows and research
User
Basic prediction access
Tech Stack
Backend
Visualization & Reports
Security
Frontend
Setup
Quick Start
Get Heartlytics running locally in minutes
Prerequisites
Python 3.11+, pip, a virtualenv, and optional SMTP credentials for email flows.
Installation
Disclaimer
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.