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
2. User Guide
3. Developer Guide
4. Features & Capabilities
5. Technical Architecture
6. Recent Improvements
7. API Reference
8. Troubleshooting
9. Contributing

---

🚀 Quick Start

Installation

# 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

# 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

# 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

# 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

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

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

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

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

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

# 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:

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 and README.md files.