# Spendlight

A private, self-hosted household budgeting app: import bank and card
statements, categorize in a tap, budget by month, and keep an eye on
subscriptions. Runs as a single container on arm64 or amd64.

Status: milestones 0 to 2 are built (foundation, money in, the full picture).
Milestone 3, launch hardening, is next.

## What it does

- **Import** CSV statements from Bank of America, Discover, Chase, Capital One,
  Citi and Apple Card, plus any other bank through a one-time column mapper.
  Duplicates are skipped, card payments and transfers are paired, and any
  import can be undone.
- **Review** new transactions with one-tap category suggestions that learn
  from every choice. Splits, tags, notes and cash entries are built in.
- **Budget** one amount per category for every month, with any month set on
  its own. Fill a year from recent spending in one step; copy it into the next.
- **Home** shows what's left to spend, how the year is pacing, insights, balances
  and the charges coming up.
- **Insights**: year pacing, money in and out, budget against actual,
  categories by month, merchants, balances over time and tags.
- **Subscriptions and bills** are found automatically across every account,
  confirmed with one tap, and watched for price changes, missed charges, charges
  after cancelling, double billing, renewals and trials ending.
- **Export** everything to Excel or CSV.
- **AI** features are designed in and switched off; no provider ships with the
  app and it makes no outside calls.

## Running it

```bash
cp .env.example .env      # adjust the port, time zone and paths
scripts/deploy.sh         # builds a versioned image and starts it
```

HTTPS comes from your own reverse proxy (see `deploy/nginx.conf.example`).
The API is documented at `/api/docs` on a running instance.

## Developing

The host only needs Docker; Node 24 runs in a container.

```bash
scripts/dev.sh npm install
scripts/dev.sh npm test
scripts/dev.sh npm run typecheck
```

Statement files never belong in this repository: `samples/` is ignored and a
pre-commit hook blocks statement and database files. Tests use made-up data in
`server/test/fixtures/synthetic` and `server/test/synthetic.ts`.