thechart/README.md

# TheChart
Advanced medication tracking application for monitoring treatment progress and symptom evolution.

## Quick Start
```bash
# Install dependencies
make install

# Run the application
make run

# Run tests
make test
```

## 📚 Documentation
- **[Features Guide](docs/FEATURES.md)** - Complete feature documentation
- **[Keyboard Shortcuts](docs/KEYBOARD_SHORTCUTS.md)** - Keyboard shortcuts for efficient navigation
- **[Export System](docs/EXPORT_SYSTEM.md)** - Data export functionality and formats
- **[Development Guide](docs/DEVELOPMENT.md)** - Testing, development, and architecture
- **[Changelog](docs/CHANGELOG.md)** - Version history and feature evolution
- **[Quick Reference](#quick-reference)** - Common commands and shortcuts

## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Application](#running-the-application)
- [Key Features](#key-features)
- [Development](#development)
- [Deployment](#deployment)
- [Docker Usage](#docker-usage)
- [Troubleshooting](#troubleshooting)
- [Quick Reference](#quick-reference)

## Prerequisites

Before installing Thechart, ensure you have the following installed on your system:

### Required Software
- **Python 3.13 or higher** - The application requires Python 3.13+
- **uv** - For fast dependency management and virtual environment handling
- **Git** - For version control (if cloning from repository)

### Installing Prerequisites

#### Install Python 3.13
**Ubuntu/Debian:**
```shell
sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev
```

**macOS (using Homebrew):**
```shell
brew install python@3.13
```

**Windows:**
Download and install from [python.org](https://www.python.org/downloads/)

#### Install uv
**All Platforms:**
```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**macOS (using Homebrew):**
```shell
brew install uv
```

**Windows (using PowerShell):**
```shell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Alternative (using pip):**
```shell
pip install uv
```

Add uv to your PATH (usually done automatically by the installer):
```shell
export PATH="$HOME/.local/bin:$PATH"
```

#### Verify Installation
```shell
python3.13 --version
uv --version
```

## Installation

### Quick Setup (Recommended)
The Makefile is configured to use the fish shell by default. For other shells, see the [shell-specific instructions](#shell-specific-activation) below.

**Note:** The current Makefile still uses Poetry commands. If you've switched to uv, you may need to update the Makefile or use the manual installation method below.

```shell
make install
```

This command will:
- Set up the Python virtual environment using uv
- Install all required dependencies
- Install development dependencies
- Set up pre-commit hooks for code quality
- Run initial code formatting and linting

### Manual Installation
If you prefer to set up the environment manually:

1. **Clone the repository** (if not already done):
```shell
git clone <repository-url>
cd thechart
```

2. **Create and activate virtual environment:**
```shell
uv venv --python 3.13
uv sync
```

3. **Install pre-commit hooks** (for development):
```shell
uv run pre-commit install --install-hooks --overwrite
uv run pre-commit autoupdate
```

### Migrating from Poetry to uv

If you have an existing Poetry setup and want to migrate to uv:

1. **Remove Poetry environment** (optional):
```shell
poetry env remove python
```

2. **Create new uv environment:**
```shell
uv venv --python 3.13
uv sync
```

3. **Update your workflow:** Replace `poetry run` with `uv run` in your commands.

The `pyproject.toml` file remains compatible between Poetry and uv, so no changes are needed there.

### Shell-Specific Activation

If the automatic environment activation doesn't work or you're using a different shell, manually activate the environment:

#### fish shell (default)
```shell
source .venv/bin/activate.fish
```
or use the convenience command:
```shell
make shell
```

#### bash/zsh
```shell
source .venv/bin/activate
```

#### PowerShell (Windows)
```shell
.venv\Scripts\Activate.ps1
```

#### Using uv run (recommended)
For any command, you can use `uv run` to automatically use the virtual environment:
```shell
uv run python src/main.py
uv run pre-commit run --all-files
```

## Running the Application

### Quick Start
After installation, run the application with:
```shell
make run
```

### Manual Run
Alternatively, you can run the application directly:
```shell
uv run python src/main.py
```
or if you have activated the virtual environment:
```shell
python src/main.py
```

### First-Time Setup
On first run, the application will:
- Create a default CSV data file (`thechart_data.csv`) if it doesn't exist
- Set up logging in the `logs/` directory
- Initialize medicine and pathology configuration files (`medicines.json`, `pathologies.json`)
- Create necessary directory structure
## Key Features

### 🏥 Modular Medicine System
- **Dynamic Medicine Management**: Add, edit, and remove medicines through the UI
- **Configurable Properties**: Customize names, dosages, colors, and quick-dose options
- **JSON Configuration**: Easy management through `medicines.json`
- **Automatic UI Updates**: All components update when medicines change

### 💊 Advanced Dose Tracking
- **Precise Timestamps**: Record exact time and dose amounts
- **Multiple Daily Doses**: Track multiple doses of the same medicine
- **Comprehensive Interface**: Dedicated dose management in edit windows
- **Historical Data**: Complete dose history with CSV persistence

### 📊 Enhanced Visualizations
- **Interactive Graphs**: Toggle visibility of symptoms and medicines
- **Dose Bar Charts**: Visual representation of daily medication intake
- **Enhanced Legends**: Multi-column layout with average dosage information
- **Professional Styling**: Clean, informative chart design

### 📈 Data Management
- **Robust CSV Storage**: Human-readable and portable data format
- **Automatic Backups**: Data protection during updates
- **Backward Compatibility**: Seamless upgrades without data loss
- **Dynamic Columns**: Adapts to new medicines and pathologies

### 📋 Data Export System
- **Multiple Formats**: Export to JSON, XML, and PDF formats
- **Comprehensive Reports**: PDF exports with optional graph visualization
- **Metadata Inclusion**: Export includes date ranges, pathologies, and medicines
- **User-Friendly Interface**: Easy access through File menu with format selection
- **Data Portability**: Structured exports for analysis or backup purposes

For complete feature documentation, see **[docs/FEATURES.md](docs/FEATURES.md)**.

## Development

### Testing Framework
TheChart includes a comprehensive testing suite with **93% code coverage**:

```bash
# Run all tests
make test

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

# Run specific test file
uv run pytest tests/test_graph_manager.py -v
```

**Testing Statistics:**
- **112 total tests** across 6 test modules
- **93% overall coverage** (482 statements, 33 missed)
- **Pre-commit testing** prevents broken commits

### Code Quality
```bash
# Format code
make format

# Check code quality
make lint

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

### Package Management with uv
```bash
# Add dependencies
uv add package-name

# Add development dependencies
uv add --dev package-name

# Update dependencies
uv sync --upgrade

# Remove dependencies
uv remove package-name
```

For detailed development information, see **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.

## Deployment

### Creating a Standalone Executable

#### Linux/Unix Deployment
Deploy the application as a standalone executable that can run without Python installed:

```shell
make deploy
```

This command will:
1. **Create a standalone executable** using PyInstaller
2. **Install the executable** to `~/Applications/`
3. **Copy data file** to `~/Documents/thechart_data.csv`
4. **Create desktop entry** for easy access from the applications menu
5. **Validate desktop file** to ensure proper integration

#### Manual Deployment Steps
If you prefer to deploy manually:

1. **Build the executable:**
```shell
pyinstaller --name thechart \
    --optimize 2 \
    --onefile \
    --windowed \
    --hidden-import='PIL._tkinter_finder' \
    --icon='chart-671.png' \
    --add-data="./.env:." \
    --add-data='./chart-671.png:.' \
    --add-data='./thechart_data.csv:.' \
    src/main.py
```

2. **Install files:**
```shell
# Copy executable
cp ./dist/thechart ~/Applications/

# Copy data file
cp ./thechart_data.csv ~/Documents/

# Install desktop entry (Linux)
cp ./deploy/thechart.desktop ~/.local/share/applications/
desktop-file-validate ~/.local/share/applications/thechart.desktop
```

#### macOS/Windows Deployment
**Note:** macOS and Windows deployment is planned for future releases. Currently, you can run the application using Python directly on these platforms.

For now, use:
```shell
python src/main.py
```

### Deployment Requirements
- **PyInstaller** (included in dev dependencies)
- **Icon file** (`chart-671.png`)
- **Desktop file** (`deploy/thechart.desktop` for Linux)

## Docker Usage

### Quick Start with Docker
```bash
# Build and start the application
make build
make start

# Stop the application
make stop

# Access container shell
make attach
```

### Manual Docker Commands
```bash
# Build image
docker build -t thechart .

# Run container with X11 forwarding (Linux)
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  thechart
```

**Note:** Docker support is primarily for development. For production use, consider the standalone executable deployment.

## Troubleshooting

### Common Issues

#### Python Version Conflicts
**Problem:** `uv sync` fails with Python version errors.
**Solution:** Ensure Python 3.13+ is installed and specify the correct version:
```shell
uv venv --python 3.13
uv sync
```

#### Permission Denied During Deployment
**Problem:** Cannot copy files to `~/Applications/` or `~/Documents/`.
**Solution:** Ensure directories exist and have proper permissions:
```shell
mkdir -p ~/Applications ~/Documents
chmod 755 ~/Applications ~/Documents
```

#### Missing System Dependencies
**Problem:** Application fails to start due to missing system libraries.
**Solution:** Install required system packages:

**Ubuntu/Debian:**
```shell
sudo apt install python3-tk python3-dev build-essential
```

**macOS:**
```shell
brew install tcl-tk
```

#### Virtual Environment Issues
**Problem:** Environment activation fails or commands not found.
**Solution:** Rebuild the virtual environment:
```shell
rm -rf .venv
uv venv --python 3.13
uv sync
```

### Logs and Debugging
Application logs are stored in the `logs/` directory:
- `app.log` - General application logs
- `app.error.log` - Error messages
- `app.warning.log` - Warning messages

To enable debug logging, modify the logging configuration in `src/logger.py`.

### Getting Help
If you encounter issues not covered here:
1. Check the application logs in the `logs/` directory
2. Ensure all prerequisites are properly installed
3. Try rebuilding the virtual environment
4. Verify file permissions for deployment directories

## Quick Reference

### Essential Commands
```bash
# Development workflow
make install    # One-time setup
make run        # Run application
make test       # Run tests
make format     # Format code
make lint       # Check code quality

# Deployment
make deploy     # Create standalone executable

# Docker
make build      # Build container image
make start      # Start containerized app
make stop       # Stop containerized app
```

### Project Structure
```
src/                 # Main application source code
├── main.py         # Application entry point
├── ui_manager.py   # User interface management
├── data_manager.py # CSV data operations
├── graph_manager.py # Visualization and plotting
├── medicine_manager.py # Medicine system
└── pathology_manager.py # Symptom tracking

docs/               # Documentation
├── FEATURES.md     # Complete feature guide
└── DEVELOPMENT.md  # Development guide

logs/               # Application logs
deploy/             # Deployment configuration
tests/              # Test suite
medicines.json      # Medicine configuration
pathologies.json    # Pathology configuration
thechart_data.csv   # User data (created on first run)
```

### Key Files
- **`medicines.json`**: Configure available medicines
- **`pathologies.json`**: Configure tracked symptoms
- **`thechart_data.csv`**: Your medication and symptom data
- **`pyproject.toml`**: Project configuration and dependencies
- **`uv.lock`**: Dependency lock file

### Keyboard Shortcuts
```bash
# 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

# 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 help
```

---

## Why uv?

**uv** is a fast Python package installer and resolver, written in Rust. It offers several advantages over Poetry:

- **Speed**: 10-100x faster than pip and Poetry
- **Compatibility**: Drop-in replacement for pip with Poetry-like project management
- **Simplicity**: Unified tool for package management and virtual environments
- **Standards**: Follows Python packaging standards (PEP 621, etc.)

### Key uv Commands vs Poetry

| Task | uv Command | Poetry Equivalent |
|------|------------|-------------------|
| Create virtual environment | `uv venv` | `poetry env use` |
| Install dependencies | `uv sync` | `poetry install` |
| Add package | `uv add package` | `poetry add package` |
| Run command | `uv run command` | `poetry run command` |
| Activate environment | `source .venv/bin/activate` | `poetry shell` |