feat: Remove outdated testing documentation and add comprehensive development and feature guides
- Deleted `TESTING_SETUP.md` and `TEST_UPDATES_SUMMARY.md` as they were outdated. - Introduced `CHANGELOG.md` to document notable changes and version history. - Added `DEVELOPMENT.md` for detailed development setup, testing framework, and debugging guidance. - Created `FEATURES.md` to outline core features and functionalities of TheChart. - Established `README.md` as a centralized documentation index for users and developers.
This commit is contained in:
William Valentin
232
docs/FEATURES.md
Normal file
232
docs/FEATURES.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 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:
|
||||
```csv
|
||||
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
|
||||
|
||||
## 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](../README.md).
|
||||
For development information, see [DEVELOPMENT.md](DEVELOPMENT.md).
|
||||
Reference in New Issue
Block a user