thechart/README.md

# Thechart
App to manage medication and see the evolution of its effects.

## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Running the Application](#running-the-application)
- [Development](#development)
- [Deployment](#deployment)
- [Docker Usage](#docker-usage)
- [Troubleshooting](#troubleshooting)
- [Make Commands Reference](#make-commands-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
- Create necessary configuration files

## Development

### Code Quality Tools
The project includes several code quality tools that are automatically set up:

#### Formatting and Linting
```shell
make format  # Format code with ruff
make lint    # Run linter checks
```

**With uv directly:**
```shell
uv run ruff format .  # Format code
uv run ruff check .   # Check for issues
```

#### Running Tests
```shell
make test    # Run unit tests
```

**With uv directly:**
```shell
uv run pytest  # Run tests with pytest
```

### Package Management with uv

#### Adding Dependencies
```shell
# Add a runtime dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Add specific version
uv add "package-name>=1.0.0"
```

#### Removing Dependencies
```shell
uv remove package-name
```

#### Updating Dependencies
```shell
# Update all dependencies
uv sync --upgrade

# Update specific package
uv add "package-name>=new-version"
```

#### Pre-commit Hooks
Pre-commit hooks are automatically installed and will run on every commit to ensure code quality. They include:
- Code formatting with ruff
- Linting checks
- Import sorting
- Basic file checks

### Development Dependencies
The following development tools are included:
- **ruff** - Fast Python linter and formatter
- **pre-commit** - Git hook management
- **pyinstaller** - For creating standalone executables

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

## Docker Usage

### Building the Container Image
Build a multi-platform Docker image:
```shell
make build
```

### Running with Docker Compose
The project includes Docker Compose configuration for easy container management:

1. **Start the application:**
```shell
make start
```

2. **Stop the application:**
```shell
make stop
```

3. **Access container shell:**
```shell
make attach
```

### Manual Docker Commands
If you prefer using Docker directly:

```shell
# Build image
docker build -t thechart .

# Run container
docker run -it --rm thechart
```

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

## Make Commands Reference

The project uses a Makefile to simplify common development and deployment tasks.

### Show Help Menu
```shell
make help
```

### Available Commands
| Command | Description |
|---------|-------------|
| `install` | Set up the development environment |
| `run` | Run the application |
| `shell` | Open a shell in the local environment |
| `format` | Format the code with ruff |
| `lint` | Run the linter |
| `test` | Run the tests |
| `requirements` | Export the requirements to a file |
| `build` | Build the Docker image |
| `start` | Start the app (Docker) |
| `stop` | Stop the app (Docker) |
| `attach` | Open a shell in the container |
| `deploy` | Deploy standalone app executable |
| `help` | Show this help |

### Quick Reference
```shell
# 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
```

---

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

**Project Structure:**
- `src/` - Main application source code
- `logs/` - Application log files
- `deploy/` - Deployment configuration files
- `build/` - Build artifacts (created during deployment)
- `.venv/` - Virtual environment (created by uv)
- `uv.lock` - Lock file with exact dependency versions
- `pyproject.toml` - Project configuration and dependencies
- `thechart_data.csv` - Application data file