# Project pack: ezBookkeeping @ 3dcc316

Facts about **ezBookkeeping** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; 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.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Download the prebuilt program for your system and run it. No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://raw.githubusercontent.com/mayswind/ezbookkeeping/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/mayswind/ezbookkeeping
- Pinned commit: `3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/mayswind/ezbookkeeping/archive/3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- 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.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/mayswind/ezbookkeeping bespoke-ezbookkeeping
  cd bespoke-ezbookkeeping
  git checkout --detach 3dcc316e1fb6a190d6a0dd13fbe4052d17b9315c
  # Prepare development requirements and local configuration first.
  # Setup notes: frontend dev server; backend: go run ezbookkeeping.go server run (port 8080)
  npm install && npm run serve
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```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
  ```
- Tools these commands use: 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.
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. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/ezbookkeeping/3dcc316/r3/SKILL.md)