# Project pack: ezBookkeeping @ 3dcc316

Facts about **ezBookkeeping** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> ezBookkeeping is a personal money diary. Record what you spend and earn in a few taps, sort it into accounts, categories and tags, and see clear charts of where your money goes. It imports bank statements (CSV, Excel, OFX, QIF and more), handles several currencies, and works on your phone like an app. It is light enough for a Raspberry Pi, and optional AI can turn a receipt photo or a typed sentence into a transaction.

## Version and source
- Repository: https://github.com/mayswind/ezbookkeeping
- Pinned commit: `3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c`. Use exactly this version.
- Get it: `git clone https://github.com/mayswind/ezbookkeeping ezbookkeeping && cd ezbookkeeping && git checkout 3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c`
- Or download a zip: https://github.com/mayswind/ezbookkeeping/archive/3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c.zip
- Official docs: https://ezbookkeeping.mayswind.net
- Live demo: https://ezbookkeeping-demo.mayswind.net. Official public demo linked from the README. Don't enter real financial details.
- Licence: **MIT**. Very permissive. You can use, change and share it, even commercially, as long as you keep the copyright notice. No obligation to publish your changes.

## Running it
- Easiest:

  ```sh
  docker volume create ezbookkeeping-data && docker volume create ezbookkeeping-storage && docker run -d -p 8080:8080 --name ezbookkeeping -e EBK_SECURITY_SECRET_KEY="$(openssl rand -base64 32)" -v ezbookkeeping-data:/ezbookkeeping/data -v ezbookkeeping-storage:/ezbookkeeping/storage mayswind/ezbookkeeping # then open http://localhost:8080 and create your account
  ```

- Needs: Docker, or the single binary for Windows, macOS or Linux, Runs on small hardware such as a NAS or Raspberry Pi, For development, Go, GCC, Node.js and npm
- Develop: `npm install && npm run serve   # frontend dev server; backend: go run ezbookkeeping.go server run (port 8080)`
- Test: `go test ./... && npm run test`
- Check/lint: `go vet ./... && npm run lint`
- Build: `./build.sh package -o ezbookkeeping.tar.gz`
- Stack: go, typescript, vue (Gin, XORM, Vue 3, Vuetify (desktop), Framework7 (mobile), Vite). Difficulty for a non-developer with an AI: **moderate**. A Go backend and a Vue 3 frontend with two separate interfaces (desktop and mobile), so screen changes are usually made twice. Sign-up, currencies, exchange rates, AI and MCP are settings in one .ini file or EBK_ environment variables. Building needs Go, GCC and Node.

## Customisation points (settings → extend → code)
- **config-file** [settings]: Sign-up, database, login options, exchange-rate source, map provider, scheduled transactions and more. → `conf/ezbookkeeping.ini, or EBK_{SECTION}_{OPTION} environment variables (e.g. EBK_USER_ENABLE_REGISTER)`
- **user-preferences** [settings]: Make it look and read the way your household expects, e.g. pounds, Monday-first weeks, UK dates. → `In the app → User Settings (language, default currency, first day of week, date and number formats, colours for income and expense)`
- **accounts-categories-tags** [settings]: Your own two-level accounts and categories, quick templates and scheduled transactions for regular bills. → `In the app → Accounts, Transaction Categories, Tags and Templates (src/views/desktop/accounts, categories, tags, templates)`
- **ai-recognition** [settings]: Add transactions from receipt photos or text, using a cloud model or a local one through Ollama. → `conf/ezbookkeeping.ini → [ai], [llm_text_recognition], [llm_image_recognition], [llm_coding_assistant] (code in pkg/llm/)`
- **import-rules** [extend]: Bring in your bank's statements regularly without retyping. → `Import dialog with custom column mapping and rules for CSV/Excel (converters in pkg/converters/)`
- **mcp-api-skill** [extend]: Let Claude, ChatGPT or a script record and query transactions for you. → `[mcp] enable_mcp in conf/ezbookkeeping.ini (pkg/mcp/); HTTP API with tokens ([security] enable_api_token); agent skill in skills/ezbookkeeping/SKILL.md`
- **insights-explorer** [extend]: Build and save your own charts and queries without code. → `Statistics → Insights Explorer (src/views/desktop/insights/)`
- **desktop-and-mobile-screens** [code]: Change or add screens. Most changes need doing in both the desktop and the mobile views. → `src/views/desktop/** and src/views/mobile/**, components in src/components/desktop|mobile/**`
- **wording-and-styles** [code]: Wording and look beyond the built-in options. → `src/locales/en.json (and other languages), src/styles/desktop/** and src/styles/mobile/**`
- **backend** [code]: New data or behaviour, such as a new import format for your bank. → `pkg/api/ (handlers) → pkg/services/ (logic) → pkg/models/ (data); new bank formats in pkg/converters/`

## Must keep working
- Existing transactions, balances and receipt pictures. Back up the data and storage folders before upgrades or code changes.
- EBK_SECURITY_SECRET_KEY must not change once set, or logins and protected data break.
- Both interfaces. Changes to a desktop screen usually need the matching mobile screen too.
- Amounts are stored as whole numbers of the smallest unit; keep currency maths exact (no floating point).

## Staying updatable
Settings, user preferences, import rules, MCP, the API and the agent skill cover most household needs without a fork. Upstream welcomes pull requests and translations; it is mainly maintained by one developer, so discuss larger changes in an issue first.

## Data, costs and safety
- Personal data: **yes**. Stored in: Accounts and transactions in SQLite at /ezbookkeeping/data/ezbookkeeping.db (or MySQL/PostgreSQL); receipt pictures and avatars in /ezbookkeeping/storage; settings in /ezbookkeeping/conf/ezbookkeeping.ini or EBK_ variables. Financial history is sensitive and hard to rebuild. Mount both the data and storage folders (without them, everything is lost when the container is replaced), back them up regularly, and use the app's export as a second copy.
- Service: AI model provider (OpenAI, Anthropic, Gemini, OpenRouter, Ollama, LM Studio or compatible) (optional, pay-per-use with your own key, or free with Ollama / LM Studio): Create transactions from a receipt photo or a sentence, and help write custom chart scripts.
- Service: Exchange-rate sources (European Central Bank by default, and others) (optional, free): Automatic currency conversion for multi-currency accounts.
- Service: Map tiles (OpenStreetMap by default, others configurable) (optional, free): Showing where a transaction happened.
- Service: Email (SMTP) (optional, free with most providers): Email verification and password resets.
- Service: OIDC login provider (optional, free (self-hosted) or varies): Log in with an existing account such as Authentik or Keycloak.
- Setting `EBK_SECURITY_SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Random secret for signing logins and protecting data. Set it before the first run (openssl rand -base64 32) and keep it.
- Setting `EBK_USER_ENABLE_REGISTER`: Set to false after creating your household's accounts so strangers can't sign up.
- Setting `EBK_DATABASE_TYPE`: sqlite3 (default), mysql or postgres. Upstream recommends MySQL or PostgreSQL for long-term use.
- Setting `EBK_SERVER_DOMAIN`: The domain you'll open it at, used to build links.
- Setting `EBK_MCP_ENABLE_MCP`: true turns on the MCP server so your own AI assistant can read and add transactions.
- Setting `EBK_LLM_TEXT_RECOGNITION_LLM_PROVIDER`: AI provider for turning typed text into transactions (e.g. ollama, openai, anthropic). Similar EBK_LLM_IMAGE_RECOGNITION_* settings exist for receipts.
- Setting `EBK_CONF_PATH`: Path to a custom ezbookkeeping.ini, if you mount your own.
- Set EBK_SECURITY_SECRET_KEY before the first run, turn off sign-up (EBK_USER_ENABLE_REGISTER=false) once your accounts exist, and turn on two-factor login.
- Use HTTPS through a reverse proxy before reaching it from outside your home. Financial data is sensitive.
- AI recognition sends the receipt photo or text to the provider you configure. Use Ollama or LM Studio to keep it local.
- The MCP server and API tokens give an AI or script full access to your books. Limit MCP to trusted IPs (mcp_allowed_remote_ips) and keep tokens secret.

---

# Customising ezBookkeeping

ezBookkeeping is a Go server with a Vue 3 web app that has **two interfaces**: a desktop one (Vuetify) and a mobile one (Framework7). **Most household needs are settings**, either in the app or in one config file. Exhaust levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Server settings:** `conf/ezbookkeeping.ini`, or the same options as environment variables named `EBK_{SECTION}_{OPTION}` (for example `EBK_USER_ENABLE_REGISTER=false`, `EBK_DATABASE_TYPE=postgres`). To read a secret from a file, use `EBKCFP_{SECTION}_{OPTION}`.
  - `[security] secret_key`: set it before the first run and never change it.
  - `[user]`: sign-up, email verification, avatars, scheduled transactions.
  - `[exchange_rates]`: which source to use (European Central Bank by default).
  - `[map]`: map provider for transaction locations.
  - `[ai]`, `[llm_text_recognition]`, `[llm_image_recognition]`, `[llm_coding_assistant]`: AI providers and models (OpenAI, Anthropic, Gemini, OpenRouter, Ollama, LM Studio or compatible).
- **In the app, per person:** language, default currency, first day of week, date, time and number formats, income and expense colours, and the overview layout.
- **Your structure:** two-level accounts (e.g. "Bank → Current account") and categories, tags, templates for common entries, and scheduled transactions for regular bills.
- **Security:** two-factor login and an app lock (PIN or WebAuthn) in user settings; OIDC login in `[auth]`.

## Level 2: Extend (no fork)
- **Imports:** CSV, Excel, OFX, QFX, QIF, IIF, Camt.052/053, MT940, GnuCash, Firefly III, Beancount and more, with custom column mapping and rules for CSV and Excel.
- **Insights Explorer:** build and save your own charts and queries; the optional AI coding assistant helps write chart scripts.
- **MCP server** (`[mcp] enable_mcp = true`, limit with `mcp_allowed_remote_ips`): lets Claude or another assistant read and add transactions.
- **HTTP API** (`[security] enable_api_token = true`): token-based API documented on the website (`/httpapi/`).
- **Agent skill:** `skills/ezbookkeeping/SKILL.md` and its `ebktools` scripts let an AI agent record and query transactions from the command line.

## Level 3: Code

| Change | Where |
|---|---|
| Desktop screens | `src/views/desktop/**` (overview, transactions, statistics, insights, accounts, settings…) |
| Mobile screens | `src/views/mobile/**` (most features need both) |
| Shared logic for screens | `src/views/base/**`, `src/lib/**`, `src/stores/**` |
| Wording | `src/locales/en.json` (and the other language files) |
| Styles | `src/styles/desktop/**`, `src/styles/mobile/**` |
| API handlers | `pkg/api/` → logic in `pkg/services/` → data in `pkg/models/` |
| New import format | `pkg/converters/<format>/` (see `transaction_data_converters.go`) |
| AI prompts and providers | `pkg/llm/` |

## Running locally
- **Just use it:** create the two volumes, then `docker run -d -p 8080:8080 -e EBK_SECURITY_SECRET_KEY=... -v ezbookkeeping-data:/ezbookkeeping/data -v ezbookkeeping-storage:/ezbookkeeping/storage mayswind/ezbookkeeping`, and open http://localhost:8080.
- **Develop:**
  1. Install Go, GCC, Node.js and npm.
  2. Start the backend with `go run ezbookkeeping.go server run` (port 8080).
  3. Run `npm install`, then `npm run serve` for the frontend dev server.
  4. Or build everything with `./build.sh package -o ezbookkeeping.tar.gz`.
- **Check:** `go vet ./...`, `go test ./...`, `npm run lint` and `npm run test`.

## Pitfalls
- Without mounted `data` and `storage` folders, everything is lost when the container is replaced. The container runs as UID/GID 1000, so host folders must be writable by that user.
- Upstream recommends MySQL or PostgreSQL rather than SQLite for long-term use.
- Amounts are whole numbers of the smallest unit (pence, cents). Never switch to floating point.
- A screen change in `views/desktop` usually needs the same change in `views/mobile`.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/SKILL.md)