A desktop application that eliminates repetitive office workflows — from invoice generation and bulk email dispatch to automated printing and financial reconciliation — so teams can focus on the work that actually matters.
-41CD52?logo=qt&logoColor=white){kind=icon}
In many office and finance environments, staff spend a significant portion of their day on tasks that follow the same pattern every time: pulling data from a spreadsheet, populating a letter template, converting it to PDF, signing it, emailing it to the right people, printing copies for filing, and then doing it all again for the next row. Multiply that by hundreds of documents a month and the inefficiency becomes substantial.
QOL was built to solve exactly that problem. It started as an internal tool to automate the most time-consuming parts of a departmental workflow — invoice generation, letter dispatch, batch printing, and basic reconciliation — and grew into a full-featured desktop application with a clean UI, a modular architecture, and the flexibility to adapt to new processes as they arise.
Note: Active development continues in a private repository where additional modules (advanced reconciliation workflows, expanded reporting, and deeper ERP integration) are being built. This public release represents the foundational platform and core automation features.
- Populate Word templates from Excel/spreadsheet data — one row, one document, fully automated
- Auto-convert generated documents to PDF with optional digital signature embedding
- Intelligent invoice renaming to match organisational naming conventions
- Support for number-to-words conversion (e.g. amounts rendered in words on invoices and financial letters)
- Template-driven approach: update the template once, regenerate thousands of documents without touching code
- Send emails with PDF attachments to recipients defined in Excel — no manual copy-pasting
- Compose HTML-formatted emails with configurable subject lines and body content
- Secure SMTP integration with credential management via system keyring
- Recipient filtering and selection before dispatch — review before you send
- Batch-print PDFs to any system printer with configurable copy counts and filtering
- Folder-watch mode: drop files into a directory and they print automatically — ideal for high-volume environments
- Printer selection and configuration from within the application
- Track aggregate metrics across all workflows — documents generated, emails sent, pages printed
- At-a-glance dashboard for understanding throughput and workload distribution
- Designed to provide visibility into how much manual effort the tool is saving
- Theme support — switch between light and dark modes at runtime
- Configure default directories, SMTP server details, and printer preferences in one place
- All settings persisted to a local configuration file for portability
- Cross-reference data across spreadsheets to identify discrepancies and mismatches
- Designed for financial environments where accuracy across documents and records is non-negotiable
QOL is built on a strict three-layer architecture that enforces a clean separation of concerns. This makes the codebase maintainable, testable, and straightforward to extend with new features.
┌──────────────────────────────────────────────────────────┐
│ GUI Layer (gui/) │
│ PySide6 widgets, sidebar navigation, QSS theming │
│ → Handles user interaction only — no business logic │
├──────────────────────────────────────────────────────────┤
│ Controller Layer (controllers/) │
│ Orchestration, threading, config management │
│ → Bridges UI events to core engines via worker threads │
├──────────────────────────────────────────────────────────┤
│ Core / Engine Layer (core/) │
│ Pure Python — zero Qt dependencies │
│ → Fully testable in isolation, reusable outside the UI │
└──────────────────────────────────────────────────────────┘
| Concept | Detail |
|---|---|
| Tab Auto-Discovery | Any class inheriting from BaseTab with the required attributes (TAB_NAME, TAB_ICON, TAB_ORDER) is automatically registered at startup — no manual wiring needed |
| Thread-Safe Operations | Long-running tasks (document generation, email sending) execute on background threads with Qt signal-based progress reporting back to the UI |
| Token-Driven Theming | All colours, spacing, and typography are defined in a centralised tokens.json file and applied via QSS stylesheets — no inline styling anywhere in the codebase |
| Subprocess Isolation | Heavy workloads run in separate processes to keep the GUI responsive, even during large batch operations |
| Config Persistence | User preferences are serialised to JSON and restored automatically on launch |
| Layer | Technologies |
|---|---|
| UI Framework | PySide6 (Qt 6) with QSS styling and Feather SVG icons |
| Data Processing | pandas, openpyxl |
| Document Engine | python-docx, docx2pdf, PyMuPDF, Pillow |
| smtplib (SMTP) with system keyring for credential security | |
| Utilities | num2words (amount-to-words conversion) |
| Platform | pywin32 (Windows printer APIs), winotify (native notifications) |
| Build & Package | Nuitka (compiled standalone executables), setuptools-scm |
| Testing & Quality | pytest, pytest-cov, ruff |
├── gui/ # UI layer — tabs, sidebar, theming, feedback widgets
│ ├── tabs/ # Feature tabs (letters, email, printing, impact, settings, help)
│ ├── sidebar.py # Collapsible icon-driven sidebar navigation
│ └── theme.py # Token-based theme engine
├── controllers/ # Controller layer — one controller per feature module
├── core/ # Engine layer — generators, senders, sorters, reconciliation
├── resources/
│ └── styles/ # QSS stylesheets, tokens.json, Feather SVG icon set
├── tests/ # pytest unit and integration tests
├── build.py # Nuitka build script (debug & release modes)
├── main.py # Application entry point
├── version.py # Single-source version string
├── pyproject.toml # Project metadata and tool configuration
└── requirements.txt # Production dependencies
- Python 3.10 or newer
- Windows (required for printer integration and native notifications; core modules are cross-platform)
# Clone the repository
git clone https://github.com/QOLGEN/QOL.git
cd QOL
# Create a virtual environment (recommended)
python -m venv .venv
.venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtpython main.pyQOL can be compiled into a single distributable executable using Nuitka:
python build.py # Debug build
python build.py --release # Optimised release build# Install development dependencies
pip install -r requirements-dev.txt
# Run the test suite
pytest tests/
# Run tests with coverage reporting
pytest --cov=core tests/
# Lint the codebase
ruff check .See CONTRIBUTING.md for coding standards, architecture rules, and the step-by-step guide for adding new feature tabs.
QOL is under active development. The following capabilities are being built in a private repository for subsequent versions:
- Advanced Reconciliation Engine — multi-source financial reconciliation with configurable matching rules
- Expanded Reporting — exportable PDF and Excel reports with trend analysis
- Audit Trail — full logging of document generation, dispatch, and print events for compliance
- Template Designer — visual editor for creating and modifying document templates within the app
- Role-Based Access — multi-user support with permission levels for sensitive operations
This software is provided under a proprietary license. See LICENSE for details.
QOL v2.0.0 · Built with Python, PySide6, and a commitment to eliminating busywork.