TheChart

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

Quick Start

# Install dependencies
make install

# Run the application
make run

# Run tests
make test

📚 Documentation

• Features Guide - Complete feature documentation
• Keyboard Shortcuts - Keyboard shortcuts for efficient navigation
• Export System - Data export functionality and formats
• Development Guide - Testing, development, and architecture
• Changelog - Version history and feature evolution
• Quick Reference - Common commands and shortcuts

Table of Contents

• Prerequisites
• Installation
• Running the Application
• Key Features
• Development
• Deployment
• Docker Usage
• Troubleshooting
• 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:

sudo apt update
sudo apt install python3.13 python3.13-venv python3.13-dev

macOS (using Homebrew):

brew install python@3.13

Windows: Download and install from python.org

Install uv

All Platforms:

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS (using Homebrew):

brew install uv

Windows (using PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative (using pip):

pip install uv

Add uv to your PATH (usually done automatically by the installer):

export PATH="$HOME/.local/bin:$PATH"

Verify Installation

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 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.

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

git clone <repository-url>
cd thechart

2. Create and activate virtual environment:

uv venv --python 3.13
uv sync

3. Install pre-commit hooks (for development):

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

poetry env remove python

2. Create new uv environment:

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)

source .venv/bin/activate.fish

or use the convenience command:

make shell

bash/zsh

source .venv/bin/activate

PowerShell (Windows)

.venv\Scripts\Activate.ps1

Using uv run (recommended)

For any command, you can use uv run to automatically use the virtual environment:

uv run python src/main.py
uv run pre-commit run --all-files

Running the Application

Quick Start

After installation, run the application with:

make run

Manual Run

Alternatively, you can run the application directly:

uv run python src/main.py

or if you have activated the virtual environment:

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.

Development

Testing Framework

TheChart includes a comprehensive testing suite with 93% code coverage:

# 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

# Format code
make format

# Check code quality
make lint

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

Package Management with uv

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

Deployment

Creating a Standalone Executable

Linux/Unix Deployment

Deploy the application as a standalone executable that can run without Python installed:

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:

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:

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

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

# Build and start the application
make build
make start

# Stop the application
make stop

# Access container shell
make attach

Manual Docker Commands

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

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:

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:

sudo apt install python3-tk python3-dev build-essential

macOS:

brew install tcl-tk

Virtual Environment Issues

Problem: Environment activation fails or commands not found. Solution: Rebuild the virtual environment:

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

# 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

# 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