PatientPortal

Patient Engagement & Wellness Self-Service Platform

A comprehensive patient engagement platform built with Flask and a React-style SPA frontend. PatientPortal enables patients to manage their health profiles, track medications, view lab results, set wellness goals, and communicate securely with healthcare providers.

---

Features

Patient Profile Management

• Complete demographic information management
• Emergency contact details
• Insurance information (provider, policy, group)
• Medical details: blood type, allergies, height/weight
• Soft-delete (deactivation) for data integrity

Health Records Timeline

• Chronological view of all health events
• Record types: visits, diagnoses, treatments, procedures, immunizations, referrals
• Provider and facility tracking
• Follow-up date management
• Color-coded timeline visualization

Medication Tracker

• Active medication list with dosage and frequency
• Schedule-based reminders (supports various frequencies)
• Adherence tracking (doses taken vs. scheduled)
• Adherence percentage with visual progress bars
• Refill date tracking and pharmacy info
• One-click dose recording

Lab Results Dashboard

• Results with reference ranges and visual indicators
• Automatic interpretation: Normal, High, Low, Critical High, Critical Low
• Color-coded status badges for quick assessment
• Historical trend tracking per test type
• Support for common lab tests (glucose, hemoglobin, cholesterol, TSH, HbA1c, etc.)

Wellness Plan

• BMI Calculator: Real-time BMI with category classification and health tips
• Step Tracking: Daily step count vs. customizable goal
• Water Intake: Daily hydration monitoring
• Sleep Quality: Hours tracked against recommended goals
• Calorie Balance: Intake vs. expenditure tracking
• Mood Logging: Daily mood self-reporting
• Progress rings and goal completion visualization

Health Score Engine

• Composite health score (0-100) calculated from:
  • BMI category (25% weight)
  • Physical activity / step goals (20%)
  • Medication adherence (25%)
  • Lab results in normal range (20%)
  • Sleep quality (10%)
• Letter grade (A-F) with descriptive labels
• Personalized health recommendations
• Score gauge visualization on dashboard

Secure Messaging

• Patient-provider messaging simulation
• Message threading with subject lines
• Read/unread status tracking
• Priority levels (normal, high, urgent)
• Category tagging (results, prescription, appointment, general)
• Compose new messages with provider selection
• Unread count badge in navigation

Dashboard

• Health score gauge with grade and recommendations
• BMI overview with category indicator
• Wellness progress rings (steps, water, sleep)
• Medication reminder list (next 5 upcoming)
• Recent lab results summary
• Unread message count
• Quick-glance stat cards

---

Tech Stack

Component	Technology
Backend	Python 3.11+ / Flask 3.0
Database	SQLite via Flask-SQLAlchemy
ORM	SQLAlchemy 2.0
Frontend	Vanilla JS SPA (React-style)
Styling	Custom CSS (healthcare theme)
Testing	pytest + pytest-cov
Container	Docker / Docker Compose
CI/CD	GitHub Actions

---

Project Structure

patientportal/
|-- app.py                           # Flask entry point
|-- config.py                        # Configuration settings
|-- requirements.txt                 # Python dependencies
|-- Dockerfile                       # Container build
|-- docker-compose.yml               # Container orchestration
|-- start.sh                         # Quick-start script
|-- LICENSE                          # MIT License
|-- .gitignore
|-- .github/workflows/ci.yml         # CI pipeline
|-- models/
|   |-- __init__.py
|   |-- database.py                  # DB init & helpers
|   |-- schemas.py                   # SQLAlchemy models
|-- routes/
|   |-- __init__.py
|   |-- api.py                       # REST API endpoints
|   |-- views.py                     # SPA serving routes
|-- services/
|   |-- __init__.py
|   |-- health_tracker.py            # Health scoring engine
|   |-- patient_service.py           # Business logic layer
|-- frontend/
|   |-- index.html                   # SPA shell
|   |-- static/
|       |-- css/app.css              # Healthcare UI theme
|       |-- js/app.js                # SPA application logic
|-- tests/
|   |-- conftest.py                  # Test fixtures
|   |-- test_api.py                  # API endpoint tests
|   |-- test_models.py               # Model tests
|   |-- test_services.py             # Service tests
|-- seed_data/
    |-- data.json                    # Sample data

---

Quick Start

Option 1: Direct Python

# Clone the repository
git clone https://github.com/yourusername/patientportal.git
cd patientportal

# Run the start script
chmod +x start.sh
./start.sh

Option 2: Manual Setup

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py

Option 3: Docker

# Build and run with Docker Compose
docker-compose up --build

# Or build manually
docker build -t patientportal .
docker run -p 8019:8019 patientportal

The application will be available at http://localhost:8019

---

API Reference

Patients

Method	Endpoint	Description
GET	/api/patients	List all patients
GET	/api/patients/:id	Get patient by ID
POST	/api/patients	Create new patient
PUT	/api/patients/:id	Update patient
DELETE	/api/patients/:id	Deactivate patient

Health Records

Method	Endpoint	Description
GET	/api/patients/:id/records	List health records
POST	/api/patients/:id/records	Create health record

Medications

Method	Endpoint	Description
GET	/api/patients/:id/medications	List medications
POST	/api/patients/:id/medications	Create medication
POST	/api/medications/:id/dose	Record a dose taken

Lab Results

Method	Endpoint	Description
GET	/api/patients/:id/labs	List lab results
POST	/api/patients/:id/labs	Create lab result

Wellness

Method	Endpoint	Description
GET	/api/patients/:id/wellness	List wellness entries
POST	/api/patients/:id/wellness	Create/update entry

Messages

Method	Endpoint	Description
GET	/api/patients/:id/messages	List messages
POST	/api/patients/:id/messages	Send message
PUT	/api/messages/:id/read	Mark as read

Dashboard & Utilities

Method	Endpoint	Description
GET	/api/patients/:id/dashboard	Dashboard summary
POST	/api/health/bmi	Calculate BMI
POST	/api/health/score	Calculate health score
POST	/api/health/interpret-lab	Interpret lab result

---

Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=. --cov-report=term-missing

# Run specific test file
pytest tests/test_api.py -v
pytest tests/test_services.py -v

---

Health Score Methodology

The composite health score is calculated using weighted components:

Component	Weight	Scoring Criteria
BMI	25%	Based on BMI category (normal=100, overweight=70, etc.)
Activity	20%	Daily step goal achievement percentage
Medication Adherence	25%	Doses taken vs. doses scheduled
Lab Results	20%	Percentage of results in normal range
Sleep Quality	10%	Sleep goal achievement percentage

Grades:

• A (90-100): Excellent health metrics
• B (80-89): Good overall health
• C (70-79): Fair, room for improvement
• D (60-69): Needs attention
• F (below 60): Significant improvement needed

---

Lab Result Interpretation

Results are automatically categorized:

Status	Condition	Color
Normal	Within reference range	Green
Low	Below reference range	Orange
High	Above reference range	Red
Critical Low	At or below critical threshold	Dark Red
Critical High	At or above critical threshold	Dark Red

---

Configuration

Environment variables:

Variable	Default	Description
PATIENTPORTAL_PORT	8019	Server port
PATIENTPORTAL_DEBUG	false	Debug mode
DATABASE_URL	SQLite local	Database connection string
SECRET_KEY	dev key	Flask secret key

---

Design Decisions

• SPA Architecture: Hash-based routing provides a smooth, modern UX without page reloads
• SQLite: Zero-config database, perfect for development and small deployments
• Health Score Engine: Weighted composite scoring provides actionable health insights
• Lab Interpretation: Automatic categorization reduces manual review burden
• Medication Reminders: Schedule-based reminder generation from frequency metadata

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

Built as a showcase for patient engagement and digital wellness platform capabilities, demonstrating expertise in healthcare IT, self-service portals, and wellness tracking systems.