dj-papercheck

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)

pip install dj-papercheck

Install from Source

1. Clone the repository:

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

2. Install using uv (recommended):

uv sync

Or using pip:

pip install -e .

Setup

1. Add to Django Settings

Add papercheck to your INSTALLED_APPS in your Django settings:

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:

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

3. Run Migrations

python manage.py makemigrations papercheck
python manage.py migrate

4. Create Superuser (if needed)

python manage.py createsuperuser

Usage

Admin Interface

1. Start your Django development server:

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

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:

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:

uv sync --group dev --group lint

3. Set up pre-commit hooks:

pre-commit install

4. Run tests:

python manage.py test papercheck

Running the Sample Project

A sample Django project is included for testing:

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:

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

---

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