thechart/docs/FEATURES.md

TheChart - Features Documentation

Overview

TheChart is a comprehensive medication tracking application that allows users to monitor medication intake, symptom tracking, and visualize treatment progress over time.

Core Features

🏥 Modular Medicine System

TheChart features a dynamic medicine management system that allows complete customization without code modifications.

Features:

• Dynamic Medicine Management: Add, edit, and remove medicines through the UI
• Configurable Properties: Each medicine has customizable display names, dosages, colors, and quick-dose options
• Automatic UI Updates: All interface elements update automatically when medicines change
• JSON Configuration: Human-readable medicines.json file for easy management

Medicine Configuration:

Each medicine includes:

• Key: Internal identifier (e.g., "bupropion")
• Display Name: User-friendly name (e.g., "Bupropion")
• Dosage Info: Dosage information (e.g., "150/300 mg")
• Quick Doses: Common dose amounts for quick selection
• Color: Hex color for graph display (e.g., "#FF6B6B")
• Default Enabled: Whether to show in graphs by default

Default Medicines:

Medicine	Dosage	Default Graph	Color
Bupropion	150/300 mg	✅	Red (#FF6B6B)
Hydroxyzine	25 mg	❌	Teal (#4ECDC4)
Gabapentin	100 mg	❌	Blue (#45B7D1)
Propranolol	10 mg	✅	Green (#96CEB4)
Quetiapine	25 mg	❌	Yellow (#FFEAA7)

Usage:

1. Through UI: Go to Tools → Manage Medicines...
2. Manual Configuration: Edit medicines.json directly
3. Programmatically: Use the MedicineManager API

💊 Advanced Dose Tracking

Comprehensive dose tracking system that records exact timestamps and dosages throughout the day.

Core Capabilities:

• Timestamp Recording: Exact time when medicine is taken
• Dose Amount Tracking: Record specific doses (150mg, 10mg, etc.)
• Multiple Doses Per Day: Take the same medicine multiple times
• Real-time Display: See today's doses immediately
• Data Persistence: All doses saved to CSV with full history

Dose Management Interface:

Located in the edit window (double-click any entry):

• Individual Dose Entry Fields: For each medicine
• "Take [Medicine]" Buttons: Immediate dose recording with timestamps
• Editable Dose Display Areas: View and modify existing doses
• Quick Dose Buttons: Pre-configured common dose amounts
• Format Consistency: All doses displayed in HH:MM: dose format

Data Format:

• Timestamp Format: YYYY-MM-DD HH:MM:SS
• Dose Separator: | (pipe) for multiple doses
• Dose Format: timestamp:dose
• CSV Storage: Additional columns in existing CSV file

Example CSV Format:

date,depression,anxiety,sleep,appetite,bupropion,bupropion_doses,hydroxyzine,hydroxyzine_doses,propranolol,propranolol_doses,note
07/28/2025,4,5,3,3,1,"2025-07-28 14:30:00:150mg|2025-07-28 18:30:00:150mg",0,"",1,"2025-07-28 12:30:00:10mg","Multiple doses today"

📊 Enhanced Graph Visualization

Advanced graphing system with comprehensive data visualization and interactive controls.

Medicine Dose Visualization:

• Colored Bar Charts: Each medicine has distinct colors
• Daily Dose Totals: Automatically calculated from individual doses
• Scaled Display: Doses scaled by 1/10 for better visibility (labeled as "mg/10")
• Dynamic Positioning: Bars positioned below main chart area
• Semi-transparent Bars: Alpha=0.6 to avoid overwhelming symptom data

Interactive Controls:

• Toggle Buttons: Independent show/hide for each medicine and symptom
• Organized Sections: "Symptoms" and "Medicines" sections
• Real-time Updates: Changes take effect immediately

Enhanced Legend:

• Multi-column Layout: Efficient use of graph space (2 columns)
• Average Dosage Display: Shows average dose for each medicine
• Color Coding: Consistent color scheme matching graph elements
• Professional Styling: Frame, shadow, and transparency effects
• Tracking Status: Shows medicines being monitored but without current dose data

Dose Calculation Features:

• Multiple Format Support: Handles various dose string formats
• Robust Parsing: Handles timestamps, symbols (•), and mixed formats
• Edge Case Handling: Manages empty strings, NaN values, malformed data
• Daily Totals: Sums all individual doses for comprehensive daily tracking

🏥 Pathology Management

Comprehensive symptom tracking with configurable pathologies.

Features:

• Dynamic Pathology System: Similar to medicine management
• Configurable Symptoms: Add, edit, and remove symptom categories
• Scale-based Rating: 0-10 rating system for symptom severity
• Historical Tracking: Full symptom history with trend analysis

📝 Data Management

Robust data handling with comprehensive backup and migration support.

Data Features:

• CSV-based Storage: Human-readable and portable data format
• Automatic Backups: Created before major migrations
• Backward Compatibility: Existing data continues to work with updates
• Dynamic Column Management: Automatically adapts to new medicines/pathologies
• Data Validation: Ensures data integrity and handles edge cases

Migration Support:

• Automatic Migration: Data structure updates handled automatically
• Backup Creation: thechart_data.csv.backup_YYYYMMDD_HHMMSS format
• No Data Loss: All existing functionality and data preserved
• Version Compatibility: Seamless updates across application versions

🧪 Comprehensive Testing Framework

Professional testing infrastructure with high code coverage.

Testing Statistics:

• 93% Overall Code Coverage (482 total statements, 33 missed)
• 112 Total Tests across 6 test modules
• 80 Tests Passing (71.4% pass rate)
• Pre-commit Testing: Core functionality tests run before each commit

Test Coverage by Module:

• 100% Coverage: constants.py, logger.py
• 97% Coverage: graph_manager.py
• 95% Coverage: init.py
• 93% Coverage: ui_manager.py
• 91% Coverage: main.py
• 87% Coverage: data_manager.py

Testing Tools:

• pytest: Modern Python testing framework
• pytest-cov: Coverage reporting with HTML, XML, and terminal output
• pytest-mock: Mocking support for isolated testing
• pre-commit hooks: Automated testing before commits

User Interface Features

🖥️ Intuitive Design

• Clean Main Interface: Simplified new entry form focused on essential inputs
• Organized Edit Windows: Comprehensive dose management in dedicated edit interface
• Scrollable Interface: Vertical scrollbar for expanded UI components
• Responsive Design: Interface adapts to window size and content
• Visual Feedback: Success messages and clear status indicators

🎯 User Experience Improvements

• Centralized Dose Management: All dose operations consolidated in edit windows
• Quick Entry Options: Pre-configured dose buttons for common amounts
• Format Guidance: Clear instructions and format examples
• Real-time Updates: Immediate feedback and data updates
• Error Handling: Comprehensive error messages and recovery options

⌨️ Keyboard Shortcuts

Comprehensive keyboard shortcuts for efficient navigation and data entry.

File Operations:

• Ctrl+S: Save/Add new entry - Quickly save current entry data
• Ctrl+Q: Quit application - Exit with confirmation dialog
• Ctrl+E: Export data - Open export dialog window

Data Management:

• Ctrl+N: Clear entries - Clear all input fields for new entry
• Ctrl+R / F5: Refresh data - Reload data from CSV and update displays

Window Management:

• Ctrl+M: Manage medicines - Open medicine management window
• Ctrl+P: Manage pathologies - Open pathology management window

Table Operations:

• Delete: Delete selected entry - Remove selected table entry with confirmation
• Escape: Clear selection - Clear current table selection
• Double-click: Edit entry - Open edit dialog for selected entry

Help System:

• F1: Show keyboard shortcuts - Display help dialog with all shortcuts

Integration Features:

• Menu Display: All shortcuts shown in menu bar next to items
• Button Labels: Primary buttons show their keyboard shortcuts
• Case Insensitive: Both Ctrl+S and Ctrl+Shift+S work
• Focus Management: Shortcuts work when main window has focus
• Status Feedback: All operations provide status bar feedback

Technical Architecture

🏗️ Modular Design

• MedicineManager: Core medicine CRUD operations
• PathologyManager: Symptom and pathology management
• GraphManager: All graph-related operations and visualizations
• UIManager: User interface creation and management
• DataManager: CSV operations and data persistence

🔧 Configuration Management

• JSON-based Configuration: medicines.json and pathologies.json
• Dynamic Loading: Runtime configuration updates
• Validation: Input validation and error handling
• Backward Compatibility: Seamless updates and migrations

📈 Data Processing

• Pandas Integration: Efficient data manipulation and analysis
• Matplotlib Visualization: Professional graph rendering
• Robust Parsing: Handles various data formats and edge cases
• Real-time Calculations: Dynamic dose totals and averages

Deployment and Distribution

📦 Standalone Executable

• PyInstaller Integration: Creates self-contained executables
• Cross-platform Support: Linux deployment with desktop integration
• Automatic Installation: Installs to ~/Applications/ with desktop entry
• Data Migration: Copies data files to appropriate user directories

🐳 Docker Support

• Multi-platform Images: Docker container support
• Docker Compose: Easy container management
• Development Environment: Consistent development setup across platforms

🔄 Package Management

• UV Integration: Fast Python package management with Rust performance
• Virtual Environment: Isolated dependency management
• Lock Files: Reproducible builds with uv.lock
• Development Dependencies: Separate dev dependencies for clean production builds

Integration Features

🔄 Import/Export

• CSV Import: Import existing medication data
• Data Export: Export data for backup or analysis
• Format Compatibility: Standard CSV format for portability

🔌 API Integration

• Extensible Architecture: Plugin system for future enhancements
• Medicine API: Programmatic medicine management
• Data API: Direct data access and manipulation

Future Enhancements

🚀 Planned Features

• Mobile Companion App: Mobile dose tracking and reminders
• Cloud Synchronization: Multi-device data synchronization
• Advanced Analytics: Machine learning-based trend analysis
• Reminder System: Intelligent dose reminders and scheduling
• Doctor Integration: Export reports for healthcare providers

🎯 Development Roadmap

• macOS/Windows Support: Extended platform support
• Plugin Architecture: Third-party extension support
• API Development: RESTful API for external integrations
• Advanced Visualizations: Additional chart types and analysis tools

---

For detailed usage instructions, see the main README.md. For development information, see DEVELOPMENT.md.