counterpoise-ledger: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

This file is the index. It holds the commands, the rules that apply everywhere, and the warnings you must read before you act. Everything else is in guides/, one file per subject. Read the guide for the subject you are about to touch. The guides carry the reasons, and a rule without its reason is the rule that gets undone.

This checkout is for development only. Development needs no Docker and no Cloudflare account: the Rust server keeps its SQLite file in data/.

Production has two targets. COUNTERPOISE_DEPLOY_TARGET selects the target that a release deploys to. Set it in the environment or in the gitignored .env.deploy.local. See guides/architecture.md.

• worker: the Cloudflare Worker in rust-api/worker/. One Durable Object holds the database. The owner's production runs on this target. When a release PR merges into main, GitHub Actions publishes the tag and deploys it. No local checkout or container takes part.
• docker (the default): one image, one container and one process, from docker-compose.yml in a separate checkout on main. The default path is ~/counterpoise-production. COUNTERPOISE_BUILD_DIR (in the environment or in .env.deploy.local) can name another directory. That checkout has its own .env.production.local and backups/. An install on its own machine uses this target. docker-compose.yml is for this target only.

Project Overview

Counterpoise is a multi-book personal finance accounting application with true double-entry bookkeeping and investment tracking. The UI is a React and React Router client that Vite builds into static files (client/, pages in app/). A Rust server (axum and rusqlite, in rust-api/) serves every /api route, the MCP server and, on the Docker target, the client build; the browser runs its shared domain code as WASM. One SQLite database holds all data: a file (DATABASE_PATH) on the Docker target, the Durable Object's own storage on the Worker. The server applies the numbered SQL migrations in rust-api/db/migrations/ at startup, and runs the scheduled jobs and the backups itself. The Docker target is one image, one container and one process. The Worker runs the same router inside its Durable Object, and the object's alarm runs the jobs. The app supports user authentication, shared books, and a Moneydance import tool (ledger-cli import-moneydance).