A lightweight desktop payroll management system built with Python and Tkinter.
PyRoll Engine is a cross-platform desktop application for calculating and managing employee payroll. Enter hours worked, hourly rate, deductions, tax rate, and bonus to instantly compute gross and net pay. Records can be saved to Redis for persistence, with a seamless in-memory fallback when Redis is unavailable.
The UI is inspired by Claude's design language - dark backgrounds, a coral accent color - built entirely with Python's built-in tkinter library (no external UI dependencies).
| Feature | Description |
|---|---|
| Payroll Calculator | Computes gross pay, tax, deductions, bonus, and net pay in real time |
| Employee Records | Save and view all employee payroll records in a sortable table |
| Redis Storage | Persists records across sessions when a Redis server is available |
| In-Memory Fallback | Runs fully offline with no Redis required - data lives in memory for the session |
| Demo Data | Pre-seeded with two sample employees so the app is useful immediately |
| Connection Status | Status bar shows Redis vs. in-memory mode at a glance |
Calculate tab - enter employee details and compute net pay instantly.
Employees tab - full payroll table with all computed values.
- Python 3.10 or later
pip- (Optional) A running Redis server on
localhost:6379
# 1. Clone the repository
git clone https://github.com/sha-wrks/PyRoll-Engine.git
cd PyRoll-Engine
# 2. Create and activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txtpython main.pyThe app opens immediately. If Redis is not running, it silently falls back to in-memory storage and two demo employees are available right away.
Redis is only needed if you want payroll records to persist between sessions.
Windows - install Memurai Community Edition or run Redis via WSL/Ubuntu:
# WSL / Ubuntu
sudo apt update && sudo apt install redis-server
sudo service redis-server startmacOS
brew install redis
brew services start redisLinux (Ubuntu / Debian)
sudo apt update && sudo apt install redis-server
sudo systemctl enable --now redis-serverRedis connection settings are controlled via environment variables. The app uses these defaults when variables are not set:
| Variable | Default | Description |
|---|---|---|
REDIS_HOST |
localhost |
Redis server hostname |
REDIS_PORT |
6379 |
Redis server port |
REDIS_DB |
0 |
Redis database index |
Example - connect to a remote Redis instance:
REDIS_HOST=192.168.1.100 REDIS_PORT=6380 python main.pyPyRoll-Engine/
├── main.py # Entry point
├── requirements.txt # Runtime dependencies
├── pyproject.toml # Build metadata (PEP 517/518)
└── src/
├── ui/
│ ├── gui.py # Main window, widgets, user actions
│ └── theme.py # Design tokens (colors, fonts, spacing)
├── engine/
│ └── payroll.py # Pure payroll calculation logic
└── database/
└── database.py # Redis + in-memory storage abstraction
User Input -> PayrollCalculator.calculate_salary() -> Display result
|
(on save)
v
Database.save_employee() -> Redis or In-Memory list
PayrollCalculatoris a pure, stateless utility -gross = hours * rate,tax = gross * (rate/100),net = gross - deductions - tax + bonus.Databaseattempts a Redis connection on startup. If it fails, it falls back transparently and sets ausing_redisflag that the status bar reads.- Demo records are seeded only when storage is empty, so restarting the app never creates duplicates.
Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.
# Create a feature branch
git checkout -b feature/your-feature-name
# Make your changes, then push
git push origin feature/your-feature-name
# Open a pull request on GitHubPlease follow the existing code style (type hints, no unnecessary comments) and open an issue first for significant changes.
To report a vulnerability, see SECURITY.md. Do not open a public issue for security concerns.
Distributed under the terms of the LICENSE file in this repository.