--- title: BeatSense emoji: 🩺 colorFrom: blue colorTo: indigo sdk: docker app_port: 7860 pinned: false license: mit short_description: Cardiovascular risk workstation (FastAPI + Next.js) ---

BeatSense — Cardiovascular Risk Intelligence

_{Scan to open the Hugging Face Space}

> **BeatSense** is a cardiovascular risk assessment platform born from a question: what would a coronary risk tool actually feel like if it were built for the nurses station of a real hospital, instead of for a notebook demo? > > Around a trained scikit-learn model (918 patients, twelve clinical features), it ships three coordinated surfaces: a FastAPI service that exposes the model and persists every assessment, a Next.js 16 clinical workstation with sidebar navigation, dark mode, English and Spanish, and a result rendered as a printable thermal-style ticket ready to clip to the patient record, plus a legacy Streamlit dashboard kept alive for quick demos. The model itself is a Logistic Regression with a custom 0.4 decision threshold, picked because in cardiology a false negative is far more dangerous than a false positive, an interpretable choice that recovers 94% of true positives. > > The repo is end-to-end: notebooks for EDA and training, a typed REST API, a production-grade clinical UI, internationalization with zero hardcoded strings, and theme tokens out of the box. --- ## Table of Contents | | | |---|---| | Overview | Live Demo | | Features | Architecture | | Project Structure | Tech Stack | | Dataset | Model Selection | | Getting Started | Make Targets | | API Reference | Frontend Highlights | | Internationalization | Theming | | Testing | Docker | --- ## Overview **BeatSense** predicts the probability of coronary heart disease from clinical patient data. It ships three independent surfaces sharing the same trained model: - A **FastAPI** REST backend that wraps the production model (models/modelo_coronario.pkl). - A **Next.js 16** clinical workstation UI — sidebar, ticket-style report, dark mode, EN/ES — for nurses and clinicians. - A legacy **Streamlit** dashboard (still operational) for quick demos. The trained model is a **Logistic Regression** with a custom decision threshold of 0.4, chosen because in cardiology the cost of a false negative (missing a sick patient) far exceeds that of a false positive. --- ## Live Demo

--- ## Features | Surface | Highlights | |---|---| | 🤖 **ML pipeline** | EDA + survival analysis (Kaplan–Meier, Cox), preprocessing, 4 models compared, Optuna tuning, full notebooks. | | 🚀 **REST API** | FastAPI service with /predict, /history, /stats, /eda, /model-info, persistent CSV history, CORS enabled. | | 🩺 **Clinical UI** | Next.js 16 + Tailwind v4 + shadcn-style components. Sidebar navigation, nurse-station header, KPI dashboard, filtered patient table, EDA charts, model insights. | | 🖨️ **Printable ticket** | Risk result rendered as a thermal-printer ticket: monospace font, dashed dividers, barcode, window.print(). | | 🌍 **i18n** | English (default) + Spanish, zero hardcoded strings, JSON dictionaries, cookie + Accept-Language detection. | | 🌓 **Dark mode** | First-class next-themes integration, dark by default, no flash on first paint. | | 📦 **Containerized** | Docker / docker-compose for the Streamlit surface. | | 🛠️ **Dual toolchain** | uv for Python, pnpm for the Next.js workspace. One make dev boots both servers. | --- ## Architecture ``` ┌─────────────────────────┐ HTTPS/REST ┌────────────────────────┐ │ Next.js 16 frontend │ ────────────────▶ │ FastAPI service │ │ • App Router │ │ • /predict │ │ • Server + Client │ │ • /history /stats │ │ Components │ │ • /eda /model-info │ │ • TanStack Query │ ◀──────────────── │ • Loads .pkl + scaler │ └─────────────┬───────────┘ JSON └───────────┬────────────┘ │ │ │ static assets │ joblib.load ▼ ▼ ┌──────────┐ ┌─────────────────────┐ │ /public │ │ models/ │ │ logu1.png│ │ • modelo_coronario │ └──────────┘ │ • scaler_coronario │ └─────────────────────┘ ▲ │ persists │ ┌─────────┴───────────┐ │ docs/ │ │ historial_pacientes │ └──────────────────────┘ ``` --- ## Project Structure ``` BeatSense/ ├── api/ # FastAPI backend │ └── main.py # /predict, /history, /stats, /eda, /model-info │ ├── app.py # Legacy Streamlit app (still works) │ ├── frontend/ # Next.js 16 clinical workstation │ ├── public/ │ │ └── logu1.png # Logo (auto-cropped for tight framing) │ ├── src/ │ │ ├── app/ │ │ │ ├── layout.tsx # Root layout — ThemeProvider lives here │ │ │ ├── globals.css # Tailwind v4 + design tokens + print CSS │ │ │ └── [lang]/ # Locale-scoped routes │ │ │ ├── layout.tsx # CRM shell (Sidebar + Header) + Providers │ │ │ ├── page.tsx # Dashboard (KPIs + recent + pie chart) │ │ │ ├── new-evaluation/ # Clinical form → ticket result │ │ │ ├── patients/ # Filterable history table + CSV export │ │ │ ├── eda/ # Dataset analytics (Recharts) │ │ │ ├── model/ # Model metrics + comparison │ │ │ └── settings/ # Language + theme switcher │ │ ├── components/ │ │ │ ├── ui/ # Button, Card, Input, Label, Select, Badge │ │ │ ├── layout/ # Sidebar, Header, PageHeader, toggles │ │ │ ├── forms/ # EvaluationForm (RHF + Zod) │ │ │ ├── ticket/ # Printable result ticket │ │ │ ├── charts/ # EDA charts │ │ │ ├── dashboard/ # Dashboard client widgets │ │ │ ├── patients/ # Patient table │ │ │ ├── model/ # Model insights │ │ │ ├── settings/ # Settings panel │ │ │ └── providers.tsx # ThemeRoot + I18nProvider + QueryClient │ │ ├── i18n/ │ │ │ ├── config.ts # Locale list + defaultLocale │ │ │ ├── context.tsx # Client-side useT() hook │ │ │ ├── dictionaries.ts # Server-only loader │ │ │ └── dictionaries/ │ │ │ ├── en.json │ │ │ └── es.json │ │ ├── lib/ │ │ │ ├── api.ts # Typed REST client (TanStack-friendly) │ │ │ └── utils.ts # cn() helper │ │ └── proxy.ts # Next 16 middleware: locale routing │ ├── package.json │ └── tsconfig.json │ ├── data/ # Heart Disease dataset (918 records) │ ├── heart.csv # Raw │ ├── heart_procesado_g.csv # Processed by Gema │ ├── heart_procesado_i.csv # Processed by Isrodam │ └── heart_processed_R.csv # Processed by Roberto │ ├── models/ # Persisted scikit-learn artifacts │ ├── modelo_coronario.pkl │ ├── scaler_coronario.pkl │ └── model_R.pkl │ ├── notebook/ # EDA + training notebooks │ ├── eda_heart_disease_p.ipynb # EDA + survival analysis (Paloma) │ ├── eda_heart_failure_g.ipynb # EDA (Gema) │ ├── eda_heart_failure_i.ipynb # EDA (Isrodam) │ ├── eda_heart_failure_R.ipynb # EDA (Roberto) │ ├── entrenamiento_modelo_final.ipynb │ ├── entrenamiento_modelo_g.ipynb │ └── entrenamiento_modelo_i.ipynb │ ├── report/ # Evaluation reports (PDF) ├── docs/historial_pacientes.csv # Patient history (written by /predict) ├── src/img/qr_app.png # QR code to live demo ├── assets/ # Static assets (lottie, etc.) ├── .streamlit/ # Streamlit theming ├── Makefile # uv + pnpm orchestration ├── dockerfile ├── docker-compose.yml ├── pyproject.toml # uv-managed Python deps └── uv.lock ``` --- ## Tech Stack ### Backend / ML - **Python 3.11** managed with **uv** - **FastAPI** + **Uvicorn** — REST API - **scikit-learn** — Logistic Regression, RF, KNN; StandardScaler - **XGBoost** — alternative model evaluated - **Optuna** — hyperparameter search - **pandas / numpy** — data wrangling - **joblib** — model persistence - **Streamlit** — legacy interactive dashboard - **pytest** — tests ### Frontend - **Next.js 16** (App Router, Turbopack, Server Components) - **React 19** + **TypeScript 5** - **Tailwind CSS v4** with custom design tokens - **shadcn-style UI** built on **Radix UI** primitives - **TanStack Query 5** — server-state caching - **React Hook Form 7** + **Zod 4** — typed forms with runtime validation - **Recharts** — analytics charts - **next-themes** — dark/light theme - **next-intl-style i18n** using Next.js native dictionaries - **lucide-react** — icon set - **pnpm 10** — workspace package manager ### DevOps - **Make** — single command interface - **Docker / docker-compose** — containerised Streamlit deployment - **GitHub Actions** — CI/CD - **Render** — production hosting (Streamlit demo) --- ## Dataset 918 records, 12 features: | Variable | Description | Type | |---|---|---| | Age | Patient age | Numeric | | Sex | Sex (M/F) | Categorical | | ChestPainType | Type (ATA, NAP, ASY, TA) | Categorical | | RestingBP | Resting blood pressure (mm Hg) | Numeric | | Cholesterol | Serum cholesterol (mg/dl) | Numeric | | FastingBS | Fasting blood sugar > 120 mg/dl (0/1) | Binary | | RestingECG | Resting ECG result | Categorical | | MaxHR | Max heart rate achieved | Numeric | | ExerciseAngina | Exercise-induced angina (Y/N) | Binary | | Oldpeak | ST depression | Numeric | | ST_Slope | ST segment slope | Categorical | | HeartDisease | **Target** — heart disease (0/1) | Binary | The production model uses **12 engineered features** (Age, Sex, MaxHR, FastingBS, ExerciseAngina, one-hot of ChestPainType, one-hot of ST_Slope). Only Age and MaxHR are scaled. --- ## Model Selection | Model | Accuracy | Recall (class 1) | ROC-AUC | Notes | |---|---|---|---|---| | **Logistic Regression** *(threshold 0.4)* | **88 %** | **0.94** | **0.926** | ✅ Selected | | Random Forest | ~87 % | ~0.88 | ~0.91 | Higher raw accuracy, lower recall | | K-NN | ~82 % | ~0.83 | ~0.87 | Scale-sensitive | | XGBoost | ~86 % | ~0.87 | ~0.90 | Strong, less interpretable | ### Why Logistic Regression? 1. **Highest recall (0.94)** — at threshold 0.4 it catches 94% of truly sick patients. A false negative in cardiology is far worse than a false positive. 2. **No overfitting** — train/test gap of only 0.007. 5-fold CV: 84.74% ± 2.91%. 3. **Clinical transparency** — linear coefficients let clinicians see exactly which features drive each prediction. > Full analysis: > >

--- ## Getting Started ### Prerequisites - Python >=3.11, <3.13 -

- Node.js >=20 ### Install ```bash # Python deps make install # Frontend deps make frontend-install ``` ### Run everything (recommended) ```bash make dev ``` This spawns:

### Run individually ```bash make api # FastAPI only make frontend # Next.js only make streamlit # Legacy Streamlit dashboard ``` --- ## Make Targets | Target | Purpose | |---|---| | make install | uv sync — install Python deps | | make frontend-install | pnpm install — install frontend deps | | make dev | Run **both** FastAPI + Next.js in parallel | | make api | Run FastAPI only (uvicorn :8000) | | make frontend | Run Next.js only (pnpm dev :3000) | | make frontend-build | Production build of Next.js | | make streamlit | Run legacy Streamlit app | | make docker-up / docker-down / docker-build / docker-logs | Docker Compose lifecycle | | make jupyter | Launch JupyterLab | | make test | Run pytest | | make clean | Remove caches and .next/ | --- ## API Reference

Base URL

| Method | Path | Description | |---|---|---| | GET | /health | Liveness + model load status | | POST | /predict | Run cardiovascular risk prediction | | GET | /history | Return all saved patient assessments | | GET | /stats | Aggregate KPIs (totals, high-risk %, today) | | GET | /eda | Aggregated EDA payload for charts | | GET | /model-info | Metrics of the selected model + alternatives | ### POST /predict payload ```json { "patient_id": "P-001", "age": 55, "sex": "M", "chest_pain_type": "ASY", "max_hr": 130, "fasting_bs": 0, "exercise_angina": "Y", "st_slope": "Flat", "resting_bp": 140, "cholesterol": 240, "resting_ecg": "Normal", "oldpeak": 1.2 } ``` Response: ```json { "patient_id": "P-001", "timestamp": "2026-06-08T10:32:41", "probability": 94.28, "classification": "HIGH", "threshold": 40.0, "probabilities": [0.057, 0.943] } ``` --- ## Frontend Highlights - **/[lang]** Clinical dashboard — KPI cards, recent assessments, risk distribution pie. - **/[lang]/new-evaluation** Clinical form in three sections (Identification, Vitals, Symptoms/ECG) with RHF + Zod validation. On submit, the answer renders as a printable **ticket** (window.print() switches the print stylesheet so only the ticket prints, like a thermal receipt). - **/[lang]/patients** Searchable, filterable history table (high / low / all). CSV export client-side. - **/[lang]/eda** Charts: age histogram, sex distribution, chest pain distribution, scatter Max HR vs Age coloured by outcome. - **/[lang]/model** Selected model card, comparison bar chart, rationale paragraph. - **/[lang]/settings** Language + theme switcher. The layout is a **CRM/EHR shell** with a sticky dark sidebar (logo + navigation + institution badge), a header bar with patient search, shift indicator, language switch, theme toggle and a faux nurse-station avatar. --- ## Internationalization - Built on **Next.js 16 native dictionaries** (app/[lang]/...). - All UI strings live in frontend/src/i18n/dictionaries/{en,es}.json. - Locale is resolved in this order by frontend/src/proxy.ts: 1. locale cookie (set by the language switcher), 2. Accept-Language header, 3. fallback to **English**. - useT() exposes the dictionary to client components. Add a new locale by creating {xx}.json, adding xx to locales in src/i18n/config.ts, and registering it in src/i18n/dictionaries.ts. --- ## Theming - Dark mode is the **default**. - Theme tokens are defined as CSS variables in globals.css (:root for light, .dark for dark) and bridged to Tailwind v4 via @theme inline. - ThemeProvider is mounted at the **root layout** to avoid hydration issues with next-themes. --- ## Testing ```bash make test # pytest cd frontend && pnpm build # type-check + production build ``` --- ## Docker ```bash make docker-up # Build and run Streamlit container make docker-logs # Stream logs make docker-down # Stop ``` > Containerising the Next.js + FastAPI duo is on the roadmap. ---