thechart/CONSOLIDATED_DOCS.md

# TheChart - Comprehensive Documentation

> **Modern medication tracking application with advanced UI/UX for monitoring treatment progress and symptom evolution.**

## 📋 Table of Contents

1. [Quick Start](#-quick-start)
2. [User Guide](#-user-guide)
3. [Developer Guide](#-developer-guide)
4. [Features & Capabilities](#-features--capabilities)
5. [Technical Architecture](#-technical-architecture)
6. [Recent Improvements](#-recent-improvements)
7. [API Reference](#-api-reference)
8. [Troubleshooting](#-troubleshooting)
9. [Contributing](#-contributing)

---

## 🚀 Quick Start

### Installation
```bash
# Clone the repository
git clone <repository-url>
cd thechart

# Install dependencies
make install

# Run the application
make run
```

### First Steps
1. **Launch TheChart** using `make run` or `python src/main.py`
2. **Add your first entry** using Ctrl+S
3. **Explore features** with the keyboard shortcuts (F1 for help)
4. **Customize settings** with F2 or through the Theme menu

---

## 👤 User Guide

### Core Features

#### 📊 Data Tracking
- **Daily Entries**: Track medications and symptoms with date-based entries
- **Medicine Management**: Configure medications with dosage information and colors
- **Pathology Tracking**: Monitor symptoms using customizable 0-10 scales
- **Notes System**: Add detailed notes to each entry

#### 🎨 Modern UI/UX (v1.9.5+)
- **Professional Themes**: Multiple built-in themes (Dark, Light, Arc, etc.)
- **Smart Tooltips**: Context-sensitive help throughout the interface
- **Responsive Design**: Optimized layouts for different screen sizes
- **Smooth Interactions**: Debounced updates and flicker-free scrolling

#### ⌨️ Keyboard Shortcuts

##### File Operations
- **Ctrl+S**: Save/Add new entry
- **Ctrl+Q**: Quit application
- **Ctrl+E**: Export data

##### Data Management
- **Ctrl+N**: Clear entries
- **Ctrl+R / F5**: Refresh data
- **Ctrl+F**: Toggle search/filter

##### Window Management
- **Ctrl+M**: Manage medicines
- **Ctrl+P**: Manage pathologies

##### Table Operations
- **Delete**: Delete selected entry
- **Escape**: Clear selection
- **Double-click**: Edit entry

##### Help
- **F1**: Show keyboard shortcuts
- **F2**: Open settings window

#### 🔍 Search & Filter System
- **Text Search**: Search across all entry data
- **Date Range Filtering**: Filter by specific date ranges
- **Medicine Filters**: Show entries where medicines were taken/not taken
- **Pathology Range Filters**: Filter by symptom severity ranges
- **Quick Filters**: Pre-configured filters (last week, high symptoms, etc.)

#### 📈 Visualization
- **Interactive Graphs**: Line charts showing symptom trends over time
- **Medicine Dose Charts**: Bar charts displaying daily medication intake
- **Toggle Controls**: Show/hide specific symptoms or medicines
- **Professional Styling**: Clean, medical-grade visualization

#### 💾 Data Management
- **Auto-save**: Automatic data saving every 5 minutes
- **Backup System**: Automatic backups on startup/shutdown
- **Export Options**: JSON, PDF, XML export formats
- **Data Validation**: Comprehensive input validation and error handling

### Settings & Customization

#### Theme Management
- **Built-in Themes**: Dark, Light, Arc, Clam, Default, Alt
- **Dynamic Switching**: Change themes without restart
- **Persistent Settings**: Theme preferences saved automatically
- **Accessibility**: High contrast options available

#### Medicine Configuration
- **Add/Edit/Delete**: Full CRUD operations for medicines
- **Dosage Information**: Track dosage details and instructions
- **Color Coding**: Visual identification with custom colors
- **Quick Doses**: Pre-configured common dose amounts

#### Pathology Configuration
- **Symptom Scales**: Customizable 0-10 symptom tracking scales
- **Display Names**: User-friendly symptom names
- **Scale Descriptions**: Helpful descriptions for each scale level
- **Color Themes**: Visual feedback with color coding

---

## 🛠️ Developer Guide

### Development Environment Setup

#### Prerequisites
- **Python 3.13+**
- **uv** package manager
- **Virtual environment support**

#### Setup Commands
```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv/bin/activate.fish

# Install dependencies
uv sync

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html
```

### Project Structure

```
thechart/
├── src/                    # Source code
│   ├── main.py            # Application entry point
│   ├── ui_manager.py      # UI component management
│   ├── data_manager.py    # Data persistence
│   ├── theme_manager.py   # Theme and styling
│   ├── medicine_manager.py # Medicine CRUD operations
│   ├── pathology_manager.py # Pathology management
│   ├── graph_manager.py   # Visualization
│   ├── export_manager.py  # Data export
│   ├── search_filter*.py  # Search and filtering
│   └── auto_save.py       # Auto-save functionality
├── tests/                 # Test suite
├── docs/                  # Documentation
├── scripts/               # Utility scripts
└── logs/                  # Application logs
```

### Architecture Overview

#### Core Components
- **MedTrackerApp**: Main application class coordinating all components
- **UIManager**: Creates and manages all UI elements
- **DataManager**: Handles CSV data operations with pandas
- **ThemeManager**: Manages application themes and styling
- **GraphManager**: Creates interactive matplotlib visualizations

#### Design Patterns
- **Manager Pattern**: Separate managers for different concerns
- **Observer Pattern**: UI updates based on data changes
- **Strategy Pattern**: Different export formats and themes
- **Factory Pattern**: Dynamic UI component creation

### Testing Strategy

#### Test Organization
- **Unit Tests**: Individual component testing
- **Integration Tests**: Cross-component functionality
- **UI Tests**: User interface behavior testing
- **Performance Tests**: Load and stress testing

#### Running Tests
```bash
# All tests
make test

# Specific test categories
uv run pytest tests/unit/
uv run pytest tests/integration/
uv run pytest tests/ui/

# With coverage
uv run pytest --cov=src --cov-report=html --cov-report=term-missing
```

### Code Quality

#### Linting and Formatting
- **ruff**: Primary linter and formatter
- **Type Hints**: Full type annotation coverage
- **PEP8 Compliance**: Enforced code style
- **Docstrings**: Comprehensive documentation

#### Pre-commit Hooks
```bash
# Install pre-commit hooks
pre-commit install

# Run all hooks
pre-commit run --all-files
```

---

## 🌟 Features & Capabilities

### Data Management Features
- **Dynamic Medicine System**: Add/remove medicines without code changes
- **Flexible Pathology Tracking**: Customizable symptom scales
- **Robust Data Validation**: Comprehensive input validation
- **Data Export**: Multiple export formats (JSON, PDF, XML)
- **Backup & Recovery**: Automatic backup system

### User Interface Features
- **Modern Theme Engine**: Professional styling system
- **Smart Tooltip System**: Context-sensitive help
- **Responsive Layouts**: Adaptive UI components
- **Keyboard Navigation**: Full keyboard accessibility
- **Visual Feedback**: Status updates and progress indicators

### Technical Features
- **Performance Optimization**: Efficient data handling and UI updates
- **Error Handling**: Comprehensive error recovery
- **Logging System**: Detailed application logging
- **Cross-platform**: Works on Windows, macOS, and Linux
- **Modular Architecture**: Easy to extend and maintain

---

## 🏗️ Technical Architecture

### Data Layer
- **CSV Storage**: Primary data persistence using pandas
- **JSON Configuration**: Medicine and pathology configurations
- **Backup System**: Automatic backup creation and management
- **Data Validation**: Input validation and error handling

### Business Logic Layer
- **Manager Classes**: Encapsulated business logic
- **Event Handling**: User interaction processing
- **Auto-save**: Background data persistence
- **Export Processing**: Data transformation for export

### Presentation Layer
- **Tkinter UI**: Native desktop interface
- **Theme System**: Dynamic styling and theming
- **Interactive Components**: Responsive UI elements
- **Visualization**: Matplotlib integration for charts

### Recent Technical Improvements

#### UI Flickering Fix (Latest)
- **Auto-save Optimization**: Removed unnecessary UI refreshes during auto-save
- **Debounced Filter Updates**: 300ms debouncing for search/filter changes
- **Efficient Tree Updates**: Scroll position preservation and batch operations
- **Optimized Scroll Handling**: Reduced scrollbar update frequency
- **Performance Improvements**: Eliminated redundant data loading

#### Key Optimizations
1. **Memory Efficiency**: Single data load with copies instead of multiple loads
2. **Scroll Performance**: Threshold-based scroll updates to reduce CPU usage
3. **UI Responsiveness**: Batch UI operations using `update_idletasks()`
4. **User Experience**: Preserved scroll position during data updates

---

## 📈 Recent Improvements

### Version 1.9.5 - UI/UX Overhaul
- **Professional Theme Engine**: Complete theming system with 6+ themes
- **Smart Tooltip System**: Context-sensitive help throughout the interface
- **Enhanced Settings Window**: Comprehensive configuration interface
- **Modern UI Components**: Improved styling and layout
- **Performance Optimizations**: Faster loading and smoother interactions

### Latest Fixes - UI Flickering Resolution
- **Smooth Scrolling**: Eliminated flickering during table scrolling
- **Debounced Updates**: Reduced filter update frequency
- **Preserved Context**: Maintain scroll position during updates
- **Auto-save Optimization**: Non-intrusive background saving
- **Performance Gains**: Reduced CPU usage during UI operations

### Previous Improvements
- **Search & Filter System**: Advanced filtering capabilities
- **Export Enhancements**: Multiple export formats with customization
- **Keyboard Shortcuts**: Comprehensive keyboard navigation
- **Data Validation**: Robust input validation and error handling
- **Auto-save & Backup**: Automatic data protection

---

## 📖 API Reference

### Core Classes

#### MedTrackerApp
```python
class MedTrackerApp:
    """Main application class."""

    def __init__(self, root: tk.Tk) -> None:
        """Initialize the application."""

    def add_new_entry(self) -> None:
        """Add a new data entry."""

    def refresh_data_display(self, apply_filters: bool = False) -> None:
        """Refresh the data display."""
```

#### UIManager
```python
class UIManager:
    """Manages UI components and creation."""

    def create_input_frame(self, parent_frame: ttk.Frame) -> dict[str, Any]:
        """Create the input form."""

    def create_table_frame(self, parent_frame: ttk.Frame) -> dict[str, Any]:
        """Create the data table."""

    def update_status(self, message: str, message_type: str = "info") -> None:
        """Update the status bar."""
```

#### DataManager
```python
class DataManager:
    """Handles data persistence and operations."""

    def load_data(self) -> pd.DataFrame:
        """Load data from CSV file."""

    def add_entry(self, entry: list) -> bool:
        """Add a new entry to the data."""

    def update_entry(self, date: str, values: list) -> bool:
        """Update an existing entry."""
```

### Configuration APIs

#### Medicine Management
```python
class MedicineManager:
    """Manages medicine configurations."""

    def add_medicine(self, medicine: Medicine) -> bool:
        """Add a new medicine."""

    def get_medicine(self, key: str) -> Medicine | None:
        """Get medicine by key."""

    def get_medicine_keys(self) -> list[str]:
        """Get all medicine keys."""
```

#### Pathology Management
```python
class PathologyManager:
    """Manages pathology configurations."""

    def add_pathology(self, pathology: Pathology) -> bool:
        """Add a new pathology."""

    def get_pathology(self, key: str) -> Pathology | None:
        """Get pathology by key."""

    def get_pathology_keys(self) -> list[str]:
        """Get all pathology keys."""
```

---

## 🚨 Troubleshooting

### Common Issues

#### Application Won't Start
```bash
# Check Python version
python --version  # Should be 3.13+

# Verify virtual environment
source .venv/bin/activate
which python

# Reinstall dependencies
uv sync --reinstall
```

#### UI Flickering (Resolved)
The UI flickering issue during scrolling has been resolved in the latest version through:
- Auto-save optimization
- Debounced filter updates
- Efficient tree updates
- Scroll position preservation

#### Data Not Saving
1. Check file permissions in the project directory
2. Verify CSV file is not locked by another application
3. Check logs in `logs/app.log` for error messages
4. Ensure sufficient disk space

#### Theme Issues
1. Restart the application after theme changes
2. Check theme configuration in settings
3. Reset to default theme if issues persist
4. Verify tkinter supports the selected theme

#### Export Problems
1. Check output directory permissions
2. Verify required libraries are installed
3. Check for large dataset memory issues
4. Review export logs for specific errors

### Debug Mode
Enable debug logging by setting the log level in `src/constants.py`:
```python
LOG_LEVEL = "DEBUG"
```

### Log Files
- **`logs/app.log`**: General application logs
- **`logs/app.error.log`**: Error messages only
- **`logs/app.warning.log`**: Warning messages only

---

## 🤝 Contributing

### Development Workflow
1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature-name`
3. **Make** your changes following the coding guidelines
4. **Test** your changes: `make test`
5. **Lint** your code: `ruff check src/`
6. **Submit** a pull request

### Coding Standards
- **Follow PEP8** for Python code style
- **Use type hints** for all functions and variables
- **Write docstrings** for all public methods and classes
- **Add tests** for new functionality
- **Update documentation** for user-facing changes

### Testing Requirements
- **Unit tests** for all new functions
- **Integration tests** for cross-component features
- **UI tests** for user interface changes
- **Performance tests** for optimization changes

### Documentation Updates
- **Update user guide** for new features
- **Add API documentation** for new classes/methods
- **Update changelog** with version information
- **Include troubleshooting** for known issues

---

## 📄 License & Credits

### License
This project is licensed under [LICENSE] - see the LICENSE file for details.

### Credits
- **UI Framework**: Tkinter (Python standard library)
- **Data Processing**: pandas
- **Visualization**: matplotlib
- **Themes**: ttkthemes integration
- **Package Management**: uv

### Version Information
- **Current Version**: 1.13.7
- **Latest UI Update**: v1.9.5 (UI/UX Overhaul)
- **Latest Fix**: UI Flickering Resolution

---

*For the most up-to-date information, check the [CHANGELOG.md](CHANGELOG.md) and [README.md](README.md) files.*