Add cashbook web app for importing ANZ statements
Local web app and CLI that fill a NZ cashbook spreadsheet (one sheet per month, April-March) from ANZ CSV exports and PDF statements, via a headless LibreOffice. - Import with preview; duplicates matched on date and amount so CSV and PDF versions of the same period don't double up - Statement upload (drag and drop), view, download, rename and remove, with per-book import status - Month review with GST and category editing, year summary and six-monthly GST returns - Docker Compose setup; books and statements live in data/ (ignored) - Blank cashbook template (NZ Government, CC BY 4.0); code under AGPL-3.0 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
971de14356
15 files changed
+2520
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# Accounts
|
||||
|
||||
A small local web app for keeping a New Zealand business cashbook from ANZ bank
|
||||
statements. It fills in a LibreOffice/Excel cashbook spreadsheet (one sheet per
|
||||
month, April–March), so the spreadsheet stays the record and can still be opened
|
||||
and edited directly.
|
||||
|
||||
- Import ANZ statements: **CSV exports** from internet banking or **PDF statements**
|
||||
(including a PDF holding several monthly statements).
|
||||
- Upload statements by drag-and-drop, then view, download, rename or remove them.
|
||||
Each one shows how much of it is already in the selected book.
|
||||
- Preview an import before it happens. Transactions already in the book are skipped,
|
||||
matched on date and amount, so a CSV and a PDF of the same period don't double up.
|
||||
- Review each month and set GST (incl/excl) and the income or expense category per
|
||||
transaction.
|
||||
- See the year at a glance, with a six-monthly GST summary (Apr–Sep, Oct–Mar) and
|
||||
IRD due dates.
|
||||
|
||||
Everything runs on your machine; nothing is sent anywhere.
|
||||
|
||||
## Running it
|
||||
|
||||
### Docker Compose (recommended)
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Open <http://127.0.0.1:8765>. Stop it with `docker compose down`.
|
||||
|
||||
The compose file mounts:
|
||||
|
||||
| Host | Container | Purpose |
|
||||
|---|---|---|
|
||||
| `./data` | `/data` | cashbooks and `statements/` (uploads go here) |
|
||||
| `~/Downloads/anz` | `/statements` (read-only) | ANZ CSV exports to pick from |
|
||||
|
||||
The app is only published on `127.0.0.1`. With rootless Docker the container runs as
|
||||
root, which maps to your user, so saved files stay yours. With rootful Docker, set
|
||||
`CASHBOOK_USER=$(id -u):$(id -g)` before `docker compose up`.
|
||||
|
||||
### Without Docker
|
||||
|
||||
Needs Python 3 with LibreOffice's UNO bridge and `pdftotext`. On Debian/Ubuntu:
|
||||
|
||||
```bash
|
||||
sudo apt install libreoffice-calc python3-uno poppler-utils
|
||||
```
|
||||
|
||||
```bash
|
||||
python3 src/webapp.py
|
||||
```
|
||||
|
||||
Options: `--port 8765`, `--host 127.0.0.1`, `--data DIR` (default `./data`), and
|
||||
`--statements DIR` (repeatable) for extra folders to list statements from.
|
||||
|
||||
## Using it
|
||||
|
||||
1. **New book…** creates `data/cashbook-YYYY-YY.ods` from the template for a
|
||||
financial year. If you've ticked a PDF statement covering 31 March, the opening
|
||||
balance is filled in from it.
|
||||
2. Add statements (drop them on the page, or **Add…**), tick them, and **Preview import**.
|
||||
3. Check the preview: new rows, rows already in the book, and rows outside the book's
|
||||
year. Then import. The book is backed up to `<book>.ods.bak` first.
|
||||
4. Go through each month: fix GST settings and allocate categories. **Only unallocated**
|
||||
filters to what still needs doing.
|
||||
5. Check the GST table on the Year page before filing.
|
||||
|
||||
Close a book in LibreOffice before changing it in the app; the app refuses to save
|
||||
while LibreOffice has it open.
|
||||
|
||||
### How transactions are classified
|
||||
|
||||
These are starting guesses to review, not tax advice:
|
||||
|
||||
- NZ card purchases and payments out: **Incl GST**, unallocated.
|
||||
- Overseas purchases (with a foreign currency amount), bank fees, transfers and money
|
||||
in: **Excl GST**.
|
||||
- Bank fees go to *Bank fees*.
|
||||
- Transfers to and from your own accounts (`OWN_ACCOUNT_PREFIX` in
|
||||
`src/statements.py`) go to *Drawings* (out) or *Funds Intr.* (in).
|
||||
|
||||
Income that is a GST-able sale needs changing to **Incl GST** by hand, otherwise it
|
||||
won't count in the GST summary.
|
||||
|
||||
## Command line
|
||||
|
||||
```bash
|
||||
python3 src/new_book.py data/cashbook-2026-27.ods --year 2026 --opening-balance 74.70
|
||||
```
|
||||
|
||||
```bash
|
||||
python3 src/anz_import.py data/cashbook-2026-27.ods data/statements/statement.pdf
|
||||
```
|
||||
|
||||
`anz_import.py` refuses transactions outside the book's year unless you pass `--force`.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
src/
|
||||
webapp.py web server and JSON API (stdlib only)
|
||||
static/ the web page
|
||||
statements.py reads ANZ CSV and PDF statements, GST/category guesses
|
||||
cashbook.py reads and writes the spreadsheet
|
||||
office.py runs a private headless LibreOffice
|
||||
new_book.py creates a book from the template (also a CLI)
|
||||
anz_import.py imports statements (CLI)
|
||||
template.ods blank cashbook template
|
||||
data/ your books and statements (git-ignored)
|
||||
```
|
||||
|
||||
`data/` is in `.gitignore`: books, backups and bank statements are never committed.
|
||||
Removed statements go to `data/statements/.trash`.
|
||||
|
||||
## Licence
|
||||
|
||||
### Cashbook template
|
||||
|
||||
`src/template.ods` is adapted from a free cashbook spreadsheet published by the
|
||||
New Zealand Government. Its instructions refer to downloading it "from our website"
|
||||
and to newzealand.govt.nz, and it was created in 2008. It appears to be the Inland
|
||||
Revenue (IRD) cashbook template, but the original download page couldn't be confirmed.
|
||||
|
||||
Inland Revenue publishes its Crown copyright material under the
|
||||
[Creative Commons Attribution 4.0 International licence](https://creativecommons.org/licenses/by/4.0/)
|
||||
([IRD copyright statement](https://www.ird.govt.nz/about-this-site/conditions-of-use/copyright)).
|
||||
You may reuse and adapt it, including commercially, if you:
|
||||
|
||||
- acknowledge the source and its Crown copyright status,
|
||||
- reproduce it accurately and say what was changed,
|
||||
- don't use it in a misleading or derogatory way.
|
||||
|
||||
The licence excludes logos, emblems, trademarks, design elements and photography.
|
||||
The template contains none of these.
|
||||
|
||||
Attribution: *Cashbook template © Crown copyright, New Zealand Government (Inland
|
||||
Revenue), licensed under CC BY 4.0. Modified: all transaction data and the opening
|
||||
balance cleared.*
|
||||
|
||||
If you confirm the template came from a different agency, check that agency's terms.
|
||||
Some, such as business.govt.nz, use the non-commercial
|
||||
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) licence instead.
|
||||
|
||||
### Code
|
||||
|
||||
Copyright (C) 2026 jimmy
|
||||
|
||||
The code is licensed under the GNU Affero General Public License v3.0; see
|
||||
[LICENSE](LICENSE). It's free software: you can redistribute and modify it under
|
||||
the AGPL. If you run a modified version as a network service, you must offer its
|
||||
source code to the people who use it. It comes with no warranty.
|
||||
|
||||
The template is covered by its own CC BY 4.0 licence above, not the AGPL.
|
||||
Reference in new issue
Block a user