Move to FastAPI with accounts, SQLite books, export and tax returns

Storage and export
- Keep books and transactions in SQLite (data/cashbook.db) instead of
  .ods files; existing .ods books are migrated once at startup
- Export a book as the cashbook spreadsheet (.xlsx/.ods, built from the
  template via LibreOffice) or as CSV
- GST rounded per transaction to match the spreadsheet

Tax
- GST return page with IRD GST101A boxes 5-15 per six-monthly,
  two-monthly or monthly period, due dates, and a Zero-rated GST type
- Income tax page with IR10 (financial statements summary) and IR4
  (company return) boxes, from the cashbook plus year-end amounts typed
  in and saved per book

FastAPI and accounts (following led-editor)
- Replace the stdlib server with a FastAPI app (src/cashbook_app) run by
  uvicorn; dependencies in Pipfile
- Cookie sessions with bcrypt passwords, first-run admin setup or
  BOOTSTRAP_ADMIN_*, invites (link or email), sign-in throttling,
  password change that signs out other sessions
- Users page for administrators: rename, reset password, promote or
  demote, delete, list and revoke invites; last admin is protected
- Replaces the shared CASHBOOK_PASSWORD basic auth; AUTH_* settings in
  .env (see .env.example)
- Docker image uses a venv with system site packages for python3-uno
- pytest suite for auth, user management, imports, GST and tax figures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-10-24 22:43:18 +13:00
1 parent 17b48f25e8
commit 4b3e5f0932
47 files changed
+4189 -862

No files matched your search

+200 -49
View File
@@ -1,9 +1,10 @@
# 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.
A small web app (FastAPI) for keeping a New Zealand business cashbook from ANZ bank
statements. Books are kept in a SQLite database, and can be exported to the standard
cashbook spreadsheet layout (one sheet per month, April–March) as Excel or
LibreOffice files, or as CSV. People sign in with their own accounts, and
administrators manage who has access.
- Import ANZ statements: **CSV exports** from internet banking or **PDF statements**
(including a PDF holding several monthly statements).
@@ -11,10 +12,17 @@ and edited directly.
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.
- Review each month and set the GST type (Incl GST, Zero-rated, Excl GST) and the
income or expense category per transaction.
- See the year at a glance, and get the **GST return** figures (IRD GST101A boxes
5–15) for each filing period, with due dates.
- **Income tax:** company return (IR4) and financial statements summary (IR10)
figures for the year, from the cashbook plus year-end amounts you type in.
- **Export** a book as an Excel (.xlsx) or LibreOffice (.ods) cashbook spreadsheet,
with formulas, GST and category columns and the summary sheet, or as a CSV of all
transactions.
- **Accounts:** sign-in with personal accounts. Administrators invite people, reset
passwords and manage who's an administrator (see [Accounts](#accounts)).
Everything runs on your machine; nothing is sent anywhere.
@@ -22,15 +30,15 @@ Everything runs on your machine; nothing is sent anywhere.
### Docker Compose (recommended)
One-time setup, as the user who should own the books (uid 1000 by default).
Create the data folder, then put a login password in `.env` (optional, see below):
One-time setup: create the data folder as the user who should own the books (uid
1000 by default), and copy the example settings.
```bash
mkdir -p data
```
```bash
(umask 077; echo "CASHBOOK_PASSWORD=$(openssl rand -base64 18)" >> .env)
cp .env.example .env
```
Then start it:
@@ -39,17 +47,14 @@ Then start it:
docker compose up -d --build
```
Open <http://127.0.0.1:8765> and log in as `cashbook` with the password from
`.env`. With no `CASHBOOK_PASSWORD` set, there's no login: anyone who can reach the
port can see and change your books, so only do that on a network you trust. Stop it with `docker compose down`, and check it with
Open <http://127.0.0.1:8765>. The first time, it asks you to create the
administrator account. Stop it with `docker compose down`, and check it with
`docker compose ps` (it reports `healthy`) or `docker compose logs`.
**What the compose file sets up**
- **Data:** `./data` is mounted at `/data` and holds the cashbooks and `statements/`
(uploads go there). Back up this folder.
- **Login:** HTTP Basic auth, with the password from the `CASHBOOK_PASSWORD`
environment variable. Leave it unset to turn the login off.
- **Data:** `./data` is mounted at `/data`. It holds the database (`cashbook.db`:
books and accounts) and `statements/`, where uploads go. Back up this folder.
- **Network:** published on `127.0.0.1:8765` only.
- **Lockdown:**
- read-only container filesystem, with scratch space only in `/tmp` (tmpfs);
@@ -58,23 +63,30 @@ port can see and change your books, so only do that on a network you trust. Stop
- **Operations:** a health check on `/healthz`, rotated logs (3 × 10 MB) and
`restart: unless-stopped`.
**Settings** go in a `.env` file next to `compose.yaml`. Keep it private
(`chmod 600 .env`); it's git-ignored.
**Settings** go in `.env` next to `compose.yaml` (see `.env.example`). Keep it
private (`chmod 600 .env`); it's git-ignored.
| Variable | Default | Purpose |
|---|---|---|
| `CASHBOOK_PASSWORD` | *(none)* | login password; unset means no login |
| `AUTH_ENABLED` | `true` | require sign-in; `false` lets anyone who can reach the port in |
| `AUTH_REGISTER_OPEN` | `true` | allow creating accounts at `/register` |
| `AUTH_INVITE_ONLY` | `true` | …but only with an invite link |
| `AUTH_SESSION_DAYS` | `14` | how long a sign-in lasts |
| `BOOTSTRAP_ADMIN_USERNAME` / `_PASSWORD` | | create this administrator on first start, instead of in the browser |
| `PUBLIC_BASE_URL`, `SMTP_*` | | email invites (see `.env.example`) |
| `CASHBOOK_USER` | `1000:1000` | uid:gid to run as; it should own `data/`. Use `0:0` with rootless Docker, which maps container root to you. |
| `CASHBOOK_USERNAME` | `cashbook` | login name |
| `CASHBOOK_BIND` | `127.0.0.1` | host address to publish on |
| `CASHBOOK_PORT` | `8765` | host port |
| `CASHBOOK_ALLOWED_HOSTS` | | extra host names you open the app by, comma-separated; see below |
| `FORWARDED_ALLOW_IPS` | `127.0.0.1` | proxies trusted to say the request came over HTTPS |
**Reaching it from other machines:** keep it on `127.0.0.1` and put a reverse proxy
with HTTPS in front (Caddy, nginx, Traefik). Basic auth sends the password with every
request, so don't expose it over plain HTTP.
with HTTPS in front (Caddy, nginx, Traefik). Set `FORWARDED_ALLOW_IPS` to the proxy's
address, so sign-in cookies are marked secure. On a trusted network you can instead
set `CASHBOOK_BIND=0.0.0.0` and open `http://server-ip:8765`. Passwords then cross the
network unencrypted.
To block other websites from making changes through your login, the app refuses
To block other websites from making changes through your sign-in, the app refuses
changes whose page address doesn't match the server's host name. It checks the
`Host` and `X-Forwarded-Host` headers. Caddy passes the original host through. With
nginx, add `proxy_set_header Host $host;`. Otherwise, list the name you use in
@@ -99,35 +111,156 @@ services:
### Without Docker
Needs Python 3 with LibreOffice's UNO bridge and `pdftotext`. On Debian/Ubuntu:
Needs Python 3, `pdftotext` for PDF statements, and LibreOffice's UNO bridge for
spreadsheet export and migration. On Debian/Ubuntu:
```bash
sudo apt install libreoffice-calc python3-uno poppler-utils
sudo apt install libreoffice-calc python3-uno poppler-utils pipenv
```
The virtualenv needs the system site packages, so it can see LibreOffice's `uno`:
```bash
pipenv --site-packages --python /usr/bin/python3 install --dev
```
```bash
python3 src/webapp.py
pipenv run dev
```
Options: `--port 8765`, `--host 127.0.0.1`, `--data DIR` (default `./data`), and
`--statements DIR` (repeatable) for extra folders to list statements from.
Set `CASHBOOK_PASSWORD` (or `CASHBOOK_PASSWORD_FILE`) to require a login; without
one, anyone who can reach the port can see your books.
That serves <http://127.0.0.1:8765> and reloads on code changes. Settings come from
`.env` in the same way. `CASHBOOK_DATA` sets the data folder (default `./data`), and
`CASHBOOK_STATEMENTS` adds statement folders, separated by `:`.
Run the tests with:
```bash
pipenv run test
```
## Accounts
With `AUTH_ENABLED=true` (the default), everyone signs in with their own username
and password. Everyone signed in can see and change the books. Administrators can
also manage people from **Users** in the menu at the top right.
- **First run:** with no accounts yet, the sign-in page offers to create the
administrator account. Alternatively, set `BOOTSTRAP_ADMIN_USERNAME` and
`BOOTSTRAP_ADMIN_PASSWORD` and it's created on first start.
- **Inviting people:** on the Users page, create an invite link and send it. Each
link works once and expires after 1, 7 or 30 days. It can make the new person an
administrator. With `SMTP_*` set and an email address given, the link is emailed.
Pending invites can be revoked. Set `AUTH_INVITE_ONLY=false` to let anyone create
an account, or `AUTH_REGISTER_OPEN=false` to stop new accounts entirely.
- **Managing people:** rename, reset a password, make or remove an administrator,
or delete an account. You can't delete or demote yourself, and there's always at
least one administrator.
- **Passwords:** at least 8 characters, stored as bcrypt hashes. Use **Change
password** in the menu. Changing or resetting a password signs that account out
on every other device.
- **Sessions:** a sign-in lasts `AUTH_SESSION_DAYS` days, in an `httponly`,
`SameSite=Lax` cookie that's marked secure over HTTPS. **Sign out** ends it.
- **Brute force:** after 5 wrong passwords for a username or from an address within
15 minutes, sign-in is refused for a while.
## 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.
1. **New book…** creates a book for a financial year (April to March). 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.
year (these are skipped). Then import. The database is backed up to
`data/cashbook.db.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.
5. Open **GST return**, pick your filing frequency, and enter the boxes into myIR
(see below).
6. **Export** gives you the book as a spreadsheet for your accountant or IRD records.
Close a book in LibreOffice before changing it in the app; the app refuses to save
while LibreOffice has it open.
GST on the Year and month pages is 3/23 of each GST-inclusive amount, rounded to the
cent per transaction, the same as the spreadsheet. Exported spreadsheets show
zero-rated rows as Excl GST, since the template only has those two types.
### GST return
The **GST return** tab shows, for each filing period, the figures for boxes 5–15 of
the GST return (GST101A). These use the payments basis, with periods lined up to a
31 March balance date: six-monthly (Apr–Sep, Oct–Mar), two-monthly (Apr–May …
Feb–Mar) or monthly. It also shows each period's due date: the 28th of the following
month, except 7 May for periods ending in March and 15 January for November. Click a
figure to copy it.
What goes where depends on each transaction's GST type:
| GST type | Use for | On the return |
|---|---|---|
| Incl GST | sales and purchases at 15% GST | money in → Box 5; money out → Box 11 |
| Zero-rated | 0% GST supplies, such as services exported to overseas clients | money in → Box 5 and Box 6 |
| Excl GST | no GST: transfers, drawings, wages, interest, overseas purchases | left out |
Boxes 8 and 12 are 3/23 of the totals, as myIR calculates them, so they can differ by
a cent from the per-transaction GST on the Year page. Adjustments (boxes 9 and 13)
aren't tracked, so add any from your calculation sheet. The page lists anything to
check before filing: transactions not yet allocated, and money in or out left off the
return. Refunds from suppliers come in as Excl GST money in. If you claimed GST on
the original purchase, that GST needs a debit adjustment in Box 9.
These figures are worked out from your records and aren't tax advice. Check them
before you file.
### Income tax (IR4 and IR10)
The **Income tax** tab works out the company income tax return (IR4) and the
financial statements summary (IR10) for the book's year, box by box. Box numbers
follow IRD's IR10 (March 2026) and IR4 (2026) forms. Check them against the form
for the year you're filing.
**IR10.** The cashbook fills these boxes from allocated transactions, excluding GST:
| Cashbook category | IR10 box |
|---|---|
| Sales | 2 Sales and/or services |
| Interest | 7 Interest received |
| Grants, Sundry (income) | 10 Other income |
| Purchases | 4 Purchases |
| ACC & Insurance | 14 Insurance (move ACC levies to box 24) |
| Rent | 18 Rental, lease and licence payments |
| Wages | 22 Salaries and wages |
| Motor vehicle, Bank fees, Telephone & Power, Postage & Stationery, Sundry | 24 Other expenses |
| Drawings | 57 Drawings |
| Funds Intr., Loan repmt | not income or expenses |
| Closing bank balance | 31 Cash and deposits |
Anything the cashbook can't know you type in: stock, depreciation, debtors and
creditors, fixed assets, loans, tax adjustments and the other information boxes. For
boxes the cashbook fills, what you type is added to its figure, so you can move or
correct amounts. Totals (gross profit, net profit, total assets, owners' equity …)
are calculated. Unallocated transactions are left out, and the page says how much
there is.
The cashbook is on a cash basis, and bank interest arrives after RWT, so add the RWT
to box 7 to make it the gross interest.
**IR4.** Business profit (box 20B) comes from IR10 box 29, less the income reported
separately (interest, dividends, schedular and overseas income). You enter RWT and
other tax credits, donations, losses brought forward and provisional tax paid. Tax is
28% of taxable income in whole dollars, and the page shows the refund or tax to pay.
It assumes a New Zealand resident company with no residential property, Māori
authority, partnership or trust income, and no taxable property sales.
Entered amounts are saved per book in the database. These figures are worked out
from your records and aren't tax advice.
### Books kept in spreadsheets
Earlier versions kept each book as an `.ods` file in `data/`. At startup the app copies
any such spreadsheet into the database as a book named after the file, once, and
leaves the file alone. Rows split across several categories come in as unallocated,
and the log says which ones. To migrate files by hand:
```bash
python3 src/migrate.py data/cashbook-2026-27.ods
```
### How transactions are classified
@@ -146,28 +279,46 @@ 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
python3 src/new_book.py cashbook-2026-27 --year 2026 --opening-balance 74.70
```
```bash
python3 src/anz_import.py data/cashbook-2026-27.ods data/statements/statement.pdf
python3 src/anz_import.py cashbook-2026-27 data/statements/statement.pdf
```
`anz_import.py` refuses transactions outside the book's year unless you pass `--force`.
```bash
python3 src/export.py cashbook-2026-27 cashbook-2026-27.xlsx
```
The export format comes from the file extension: `.xlsx`, `.ods` or `.csv`.
Transactions outside a book's year are skipped on import. All of these take
`--data DIR` (default `./data`).
## Layout
```
src/
webapp.py web server and JSON API (stdlib only)
static/ the web page
app.py entry point (uvicorn app:app --app-dir src)
cashbook_app/ the FastAPI app
main.py app setup, security middleware, startup
config.py settings from the environment / .env
deps.py current user, admin check, database connections
routers/ auth, users, books, statements and page routes
services/ accounts, statement files, LibreOffice
db/, schemas/ account tables (SQLAlchemy) and request/response models
static/ the web pages (cashbook, sign-in, register, users)
ledger.py SQLite storage: books, transactions, GST and summaries
tax.py IR10 and IR4 figures
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)
export.py exports a book to .xlsx/.ods/.csv (also a CLI)
cashbook.py writes and reads the spreadsheet layout
migrate.py copies .ods cashbooks into the database (also a CLI)
office.py runs a private headless LibreOffice (for spreadsheets)
new_book.py creates a book (CLI)
anz_import.py imports statements (CLI)
template.ods blank cashbook template
data/ your books and statements (git-ignored)
template.ods blank cashbook template, used for exports
tests/ pytest suite (pipenv run test)
data/ cashbook.db and statements (git-ignored)
```
`data/` is in `.gitignore`: books, backups and bank statements are never committed.