gamify-ccda

Transform your health records into an interactive achievement system! This tool parses CCDA (Consolidated Clinical Document Architecture) health record exports and generates a gamified HTML dashboard with badges, statistics, and visualizations.

About This Project

This repository was created to explore the capabilities of Claude AI in software development. Users may use it to generate their own badges for their own health data if they wish.

⚠️ Important Privacy & Security Notes:

• Do not share your health data with anyone - Your medical records contain sensitive personal information
• Use secure passwords when exporting data from your healthcare provider
• Password protection helps protect files at rest - choose strong, unique passwords
• All processing happens locally on your machine - your data never leaves your computer

Features

• 📊 Interactive Dashboard: View your health encounters over time with activity heatmap and insights
• 🗺️ Location Map: Visualize all your healthcare facilities with distance tracking (requires geocoding)
• 🏆 101 Achievement Badges: Earn badges across 16 categories (6 distance badges require geocoding)
• 📅 Yearly & Lifetime Stats: Track your health journey with comprehensive analytics
• ⏰ Time Travel: View your data as of any historical date with --when flag
• 🔒 Secure: Processes password-protected ZIP files locally
• 🎨 Beautiful UI: Clean, responsive HTML output

Quick Start

Installation

go build -o gamify-ccda ./cmd/gamify-ccda

Usage

# Generate HTML dashboard from your CCDA export
./gamify-ccda generate your-health-records.zip

# Browse encounters in terminal
./gamify-ccda browse your-health-records.zip

# Specify output directory
./gamify-ccda generate your-health-records.zip -o my-dashboard

# View data as of a specific date (time travel)
./gamify-ccda --when 2023-12-31 generate your-health-records.zip

# Enable verbose logging
./gamify-ccda -v generate your-health-records.zip

# Enable geocoding for map and distance features (disabled by default)
./gamify-ccda generate --enable-geocoding your-health-records.zip

Open output/index.html in your browser to view your health dashboard!

Badge Categories

Earn badges across 16 categories tracking different aspects of your healthcare journey:

• ⏰ Temporal (10): Time-based patterns (early morning, lunch hour, weekend, after hours, etc.)
• 📍 Location (7): Facility visit patterns (wanderer, loyalist, boomerang, yo-yo, etc.)
• 🎉 Holiday (7): Visits on special days (New Year's, Valentine's, Halloween, Christmas, etc.)
• 💻 Visit Modality (6): How you receive care (in-person, virtual, phone, hybrid)
• 👨‍⚕️ Provider Continuity (3): Provider relationships and loyalty
• 🏥 Specialty (10): Specialist care patterns
• 🔬 Lab & Testing (14): Lab work and preventive screening
• 📊 Vitals (4): Vital sign monitoring and tracking
• 💊 Medication (6): Medication management
• 💉 Immunization (3): Vaccination records
• 🩺 Diagnosis (4): Health condition tracking
• 🌟 Wellness (3): Overall healthcare engagement
• 🚗 Distance & Travel (6): Healthcare travel patterns and distances
• 🏆 Achievement & Milestone (9): Major milestones and meta-achievements
• 🎖️ Visit Frequency Milestones (5): Visit count milestones (Bronze, Silver, Gold, Platinum, Diamond)
• 🍂 Seasonal (4): Seasonal healthcare patterns (Spring, Summer, Fall, Winter)

How It Works

1. Export: Download your health records as a CCDA/IHE_XDM ZIP file from your healthcare provider
2. Parse: The tool extracts and parses comprehensive health data (encounters, diagnoses, vitals, labs, medications, immunizations)
3. Geocode (optional): When enabled, geocodes facility addresses to calculate distances and generate map visualizations
4. Analyze: Aggregates data into yearly buckets and evaluates 101 badge criteria across 16 categories
5. Visualize: Generates a beautiful HTML dashboard with interactive heatmaps, maps, and achievement tracking

CCDA Compatibility

This tool works with standard CCDA R2.1 exports in IHE_XDM format. It has been tested with:

• Kaiser Permanente exports
• Any healthcare provider using standard CCDA format

Development

# Run tests
go test ./...

# Run tests with coverage
go test -v -cover ./...

# Run specific package tests
go test ./pkg/analysis/badges/

Contributing

See CLAUDE.md for architecture details and development guidelines.

Future badge ideas are tracked in BADGE_IDEAS.md.

Privacy & Security

Your health data is sensitive. This tool is designed with privacy in mind:

• ✅ All processing happens locally on your machine
• ✅ No data is sent to external servers (except when geocoding is enabled)
• ⚠️ Optional geocoding sends facility addresses to OpenStreetMap when enabled
• ✅ Supports password-protected ZIP files
• ✅ Generated HTML can be viewed offline

Best Practices:

• Use strong, unique passwords when exporting data from your healthcare provider
• Store your health record exports in a secure location
• Do not commit health data files to version control
• Do not share your health records or generated dashboards containing personal information

Geocoding & External Services:

When geocoding is enabled (via --enable-geocoding flag or config preference), facility and home addresses are sent to OpenStreetMap's Nominatim API to calculate distances and generate the map visualization. See OpenStreetMap's Privacy Policy for details.

• Geocoding is disabled by default
• Results are cached locally in ~/.cache/gamify-ccda/geocode-cache.json
• You can use the tool without geocoding - distance badges and map page will be skipped