# dj-papercheck

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![Django](https://img.shields.io/badge/django-5.2%2B-green.svg)](https://djangoproject.com)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A comprehensive Django app for managing and printing paper checks at home. This application allows you to create, manage, and generate PDF checks with proper MICR encoding for home printing.

## Features

- 📝 **Check Management**: Create and manage checks with automatic numbering
- 🏦 **Bank Account Support**: Store multiple bank account configurations
- 👥 **Payee Management**: Maintain a database of payees with addresses
- 🏷️ **Categorization**: Organize checks with categories and tags
- 📄 **PDF Generation**: Automatically generate printable PDF checks with MICR encoding
- 📊 **Export Functionality**: Export check data to MonarchMoney-compatible CSV format
- 🔢 **Auto Check Numbering**: Automatic sequential check number assignment
- 💰 **Amount Conversion**: Automatic conversion of amounts to written words
- 📱 **Admin Interface**: Full Django admin interface for easy management

## Models

### BankAccount

Stores bank account information including:

- Institution details (name, address, phone)
- Account and routing numbers
- Payor information (account holder details)

### Payee

Manages payee information:

- Name and address
- Payor account numbers for reference

### Check

The main check model with:

- Bank account and payee relationships
- Amount, memo, and invoice fields
- Auto-generated check numbers
- PDF file storage
- Category and tag support
- Creation and update timestamps

### Category

Simple categorization system for organizing checks

## Installation

### Requirements

- Python 3.10+
- Django 5.2+
- Additional dependencies listed in `pyproject.toml`

### Install from PyPI (when published)

```bash
pip install dj-papercheck
```

### Install from Source

1. Clone the repository:

```bash
git clone https://github.com/kerryhatcher/dj-papercheck.git
cd dj-papercheck
```

2. Install using uv (recommended):

```bash
uv sync
```

Or using pip:

```bash
pip install -e .
```

## Setup

### 1. Add to Django Settings

Add `papercheck` to your `INSTALLED_APPS` in your Django settings:

```python
INSTALLED_APPS = [
    # ... your other apps
    'taggit',  # Required for tag support
    'papercheck',
]
```

### 2. Configure Media Files

Ensure your Django project is configured to handle media files for PDF storage:

```python
# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
```

### 3. Run Migrations

```bash
python manage.py makemigrations papercheck
python manage.py migrate
```

### 4. Create Superuser (if needed)

```bash
python manage.py createsuperuser
```

## Usage

### Admin Interface

1. Start your Django development server:

```bash
python manage.py runserver
```

2. Access the admin interface at `http://localhost:8000/admin/`

3. Create your bank accounts, payees, and categories

4. Start creating checks - PDFs will be automatically generated

### Programmatic Usage

```python
from papercheck.models import BankAccount, Payee, Check, Category

# Create a bank account
bank = BankAccount.objects.create(
    institution_name="My Bank",
    routing_number="123456789",
    account_number="987654321",
    payor_name="John Doe",
    payor_street_1="123 Main St",
    payor_city="Anytown, ST 12345"
)

# Create a payee
payee = Payee.objects.create(
    name="Electric Company",
    street_1="456 Power St",
    city="Utility Town, ST 54321"
)

# Create a category
category = Category.objects.create(name="Utilities")

# Create a check (PDF will be auto-generated)
check = Check.objects.create(
    bank_account=bank,
    payee=payee,
    category=category,
    amount=125.50,
    memo="Monthly electric bill"
)

print(f"Check #{check.check_number} created with PDF: {check.pdf.url}")
```

### Exporting Data

Export checks to MonarchMoney format:

```python
from papercheck.models import Check

# Get checks from last month
checks = Check.objects.filter(check_date__month=11, check_date__year=2023)

# Export to CSV
filename, csv_content = Check.export_to_monarchmoney_csv(checks)

# Save to file
with open(filename, 'w') as f:
    f.write(csv_content)
```

## MICR Font

The app includes MICR (Magnetic Ink Character Recognition) font support for proper check printing. The MICR font file is included in the `micr-encoding/` directory.

**Note**: The included MICR font is for personal use. Check the license file in the `micr-encoding/` directory for usage restrictions.

## Development

### Setting up Development Environment

1. Clone the repository

2. Install development dependencies:

```bash
uv sync --group dev --group lint
```

3. Set up pre-commit hooks:

```bash
pre-commit install
```

4. Run tests:

```bash
python manage.py test papercheck
```

### Running the Sample Project

A sample Django project is included for testing:

```bash
cd sample_project
uv sync
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
```

### Code Quality

The project uses:

- **Ruff** for linting and formatting
- **Black** for code formatting
- **Pre-commit** hooks for automated checks

Run linting:

```bash
ruff check .
ruff format .
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

This project is licensed under the GNU Affero General Public License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- MICR font provided by Digital Graphic Labs (see license in `micr-encoding/` directory)
- Built with Django and ReportLab for PDF generation
- Uses django-taggit for tagging functionality

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/kerryhatcher/dj-papercheck).

---

**⚠️ Important Security Note**: This application handles sensitive financial information. Always use HTTPS in production and follow Django security best practices. Never commit real bank account information to version control.
