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>
155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# 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.
|