thechart/docs/FEATURES.md

TheChart - Features Documentation

Overview

TheChart is a comprehensive medication tracking application with a modern, professional UI that allows users to monitor medication intake, track symptoms, and visualize treatment progress over time.

🎨 Modern UI/UX System (New in v1.9.5)

Professional Theme Engine

TheChart features a sophisticated theme system powered by ttkthemes, offering 8 carefully curated professional themes.

Available Themes:

• Arc: Modern flat design with subtle shadows
• Equilux: Dark theme with excellent contrast
• Adapta: Clean, minimalist design
• Yaru: Ubuntu-inspired modern interface
• Ubuntu: Official Ubuntu styling
• Plastik: Classic professional appearance
• Breeze: KDE-inspired clean design
• Elegance: Sophisticated dark theme

UI Enhancements:

• Modern Styling: Card-style frames, enhanced buttons, professional form controls
• Smart Tooltips: Context-sensitive help for all interactive elements
• Improved Tables: Better selection highlighting and alternating row colors
• Settings System: Comprehensive preferences with theme persistence
• Responsive Design: Automatic layout adjustments and scaling

⌨️ Comprehensive Keyboard Shortcuts

Professional keyboard shortcut system for efficient navigation and operation.

File Operations:

• Ctrl+S: Save/Add new entry
• Ctrl+Q: Quit application (with confirmation)
• Ctrl+E: Export data

Data Management:

• Ctrl+N: Clear entries
• Ctrl+R / F5: Refresh data
• Delete: Delete selected entry
• Escape: Clear selection

Window Management:

• Ctrl+M: Manage medicines
• Ctrl+P: Manage pathologies
• F1: Show keyboard shortcuts help
• F2: Open settings window

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

⚙️ Settings and Theme Management

Advanced configuration system allowing users to customize their experience.

Settings Window (F2):

• Theme Selection: Choose from 8 professional themes with live preview
• UI Preferences: Font scaling, window behavior options
• About Information: Detailed application and version information
• Tabbed Interface: Organized settings categories for easy navigation

Theme Features:

• Real-time Switching: No restart required for theme changes
• Persistence: Selected theme remembered between sessions
• Quick Access: Theme menu for instant switching
• Fallback Handling: Graceful handling if themes fail to load

💡 Smart Tooltip System

Context-sensitive help system providing guidance throughout the application.

Tooltip Types:

• Pathology Scales: Usage guidance for symptom tracking
• Medicine Checkboxes: Medication information and dosage details
• Action Buttons: Functionality description with keyboard shortcuts
• Form Controls: Input guidance and format requirements

Features:

• Delayed Display: Non-intrusive timing (500-800ms delay)
• Theme-aware Styling: Tooltips match selected theme
• Smart Positioning: Automatic placement to avoid screen edges
• Rich Content: Multi-line descriptions with formatting

💊 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

<EFBFBD> Modern UI Architecture

• ThemeManager: Centralized theme management with dynamic switching
• TooltipManager: Smart tooltip system with context-sensitive help
• UIManager: Enhanced UI component creation with theme integration
• SettingsWindow: Advanced configuration interface with persistence

🏗️ Core Application Design

• MedicineManager: Core medicine CRUD operations with JSON persistence
• PathologyManager: Symptom and pathology management system
• GraphManager: Professional graph rendering with matplotlib integration
• DataManager: Robust CSV operations and data persistence with validation

🔧 Configuration and Data Management

• JSON-based Configuration: medicines.json and pathologies.json for easy management
• Dynamic Loading: Runtime configuration updates without restarts
• Data Validation: Comprehensive input validation and error handling
• Backward Compatibility: Seamless updates and migrations across versions

📈 Advanced Data Processing

• Pandas Integration: Efficient data manipulation and analysis
• Real-time Calculations: Dynamic dose totals, averages, and statistics
• Robust Parsing: Handles various data formats and edge cases gracefully
• Performance Optimization: Efficient batch operations and caching

UI/UX Technical Implementation

🎭 Theme System Architecture

• Multiple Theme Support: 8 curated professional themes
• Dynamic Style Application: Real-time theme switching without restart
• Color Extraction: Automatic color scheme detection and application
• Fallback Mechanisms: Graceful handling when themes fail to load

💡 Enhanced User Experience

• Smart Tooltips: Context-sensitive help with delayed, non-intrusive display
• Modern Styling: Card-style frames, enhanced buttons, professional form controls
• Improved Tables: Better selection highlighting and alternating row colors
• Responsive Design: Automatic layout adjustments and proper scaling

⚙️ Settings and Persistence

• Configuration Management: Theme and preference persistence across sessions
• Tabbed Settings Interface: Organized categories for easy navigation
• Live Preview: Real-time theme preview in settings
• Error Recovery: Robust handling of corrupted settings with defaults

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.