A Flask-based desktop application for tracking daily transactions and expenses — built as a digital replacement for paper-based financial record-keeping. Generates printable PDF receipts and runs as a standalone Windows desktop app.
A local-first point-of-sale / expense tracking system: no internet dependency, no external database server — everything runs and persists on the user's own machine.
Status: Feature-complete. Core functionality, PDF receipts, and desktop packaging are all working end to end.
- Flask (Application Factory pattern + Blueprints)
- Flask-SQLAlchemy — ORM
- SQLite — database, managed via Flask-Migrate
- pdfkit + wkhtmltopdf — PDF receipt generation
- pywebview — desktop window shell
- Vanilla JS, Jinja2, plain CSS (no frontend framework)
- Add / edit / delete transactions (name, phone, items/services, price, discount, amount paid)
- Server-computed pricing and outstanding/overpaid balance (
remain_amount = paid_amount - (price - discount)) - Dashboard showing today's transactions
- Full data page with:
- Server-side filters (date range, name, item/category, outstanding/overpaid)
- Instant client-side quick-search by name (filters visible rows as you type)
- Customer records: live search when adding a transaction, per-customer profile page with full history and totals, editable customer details that sync across all linked records
- Automatic payment matching (FIFO) — outstanding balances are settled against payments and new charges in order, oldest first
- Combined account statement PDF per customer, regenerated automatically after each payment
- Settings page to manage the list of available items/services and their prices
- CSV export respecting all active filters
- Printable PDF receipts per transaction (RTL Arabic support), auto-filed under
instance/reports/<year>/<month>/ - Runs as a native Windows desktop app (no browser required)
- Separate module for tracking incoming bills/invoices from suppliers (company name, category, amount, paid/remaining balance), with its own filtered list view and printable PDF receipts
- Automatic local database backup on each app launch
- Accessible from other devices (e.g. phones) on the same local network, with the access URL displayed directly in the app
- Simple role-based access (admin / worker) with password-protected login and restricted views per role
Simple-POS-System/
├── app.py # Application factory (create_app)
├── config.py # Centralized path config (dev vs. packaged/frozen mode)
├── extensions.py # Shared SQLAlchemy instance
├── launcher.py # Desktop entry point (Flask thread + pywebview window)
├── bin/ # Bundled wkhtmltopdf.exe + dependencies
├── migrations/ # Flask-Migrate schema history
├── models/ # Expense, Test, Bils, Customer
├── routes/ # index, add, edit, delete, data, settings, export, receipt, bils, customer, login
├── services/ # item lookup, date parsing, receipt generation, payment matching, port selection, backup, auth
├── templates/ # base, index, data, settings, receipt, bils
└── static/
├── css/ # theme.css (variables) + style.css (layout/components)
└── js/
git clone https://github.com/MahmoudAlQataa/Simple-POS-System
cd Simple-POS-System
python -m venv venv
source venv/bin/activate # on Windows: venv\Scripts\activate
pip install -r requirements.txt
flask db upgrade # apply database migrations
python app.pyThis runs the app as a regular Flask server, accessible from a browser at http://127.0.0.1:5000.
To run the app inside a native desktop window instead of a browser tab, use:
python launcher.pyThis requires pywebview to be installed on your machine (included in requirements.txt). The app listens on a fixed port and binds to all network interfaces, so it's also reachable from other devices on the same local network at http://<your-local-ip>:5000.
PDF receipt generation requires wkhtmltopdf — a copy is bundled in bin/, or set the path in config.py.
No license has been chosen yet.