# Getting started

This is the entry document for the accounting app — read this first, whether
you're setting it up for the first time, using it day to day, or handing it
off to someone else. If you're recovering from a lost machine or restoring a
backup onto a new one, jump straight to [RESTORE.md](RESTORE.md) instead —
this document assumes you're starting from nothing but the application code.

Who this is for: someone comfortable installing software and typing commands
into PowerShell, but not a professional developer. Every command below is
meant to be copy-pasted exactly as written.

---

## 1. What this is

A local accounting system that runs entirely on your own Windows machine. It
is **not** a website — nothing you enter here is sent anywhere over the
internet. Your books (every account, transaction, and report) live in a
database on this computer only, and the only way another person sees any of
it is if you hand them a backup file yourself.

You'll run one command (`npm run app`) to start it, and a browser tab opens
to your dashboard. Press **Ctrl+C** in that window (or close it) to stop —
the database shuts down along with it, so nothing at all keeps running in the
background when you're not using it.

**One thing does come off the internet, exactly once.** The first time you
run `npm run app`, it downloads the database it keeps your books in
(PostgreSQL — about 25 MB, from balancedsum.com), checks that what arrived is
byte-for-byte what it expected, and sets it up for you. You do not install it
yourself and it does not go anywhere else on your computer. After that first
run, nothing about using this app needs an internet connection — apart from
the optional once-a-day check for a newer version, which you can switch off.

---

## 2. One-time setup

You only need to do this section once per machine.

### 2.1 Install Node.js

1. Go to https://nodejs.org/ and download the **LTS** installer (as of this
   writing that's Node 24 — the app requires Node 24 or newer). Do not pick
   the "Current" version if LTS is older; use whichever is the newer of the
   two if in doubt.
2. Run the installer, accepting the defaults.
3. Open a **new** PowerShell window (important — a window that was already
   open before you installed Node won't see it) and confirm:

   ```powershell
   node --version
   ```

   You should see `v24.x.x` or newer. If PowerShell says `node` is not
   recognized, close all PowerShell windows and open a fresh one — Node's
   installer updates your PATH, but only windows opened afterward pick it up.

### 2.2 Get the application code

Clone or unzip this repository somewhere on your machine, then open
PowerShell **in that folder** and install its dependencies:

```powershell
npm install
```

This downloads the pieces the app is built from, and only needs to be run
again if the application code changes.

**That's the whole of the setup.** There is nothing else to install — no
database to download, install, configure, or start, and no reboots. The app
takes care of the database itself the first time you run it, which is the
next section.

---

## 3. Daily use

From the application folder, in PowerShell:

```powershell
npm run app
```

Every launch does the same four things, and tells you which one it's on:

1. Start the database (installing it first, if this is the first run).
2. Apply any pending database updates.
3. Build the web app, if needed.
4. Start the server and open your browser to **http://localhost:3000**.

### The first run is different, and it explains itself

Before it does anything slow, it stops and tells you what's about to happen:

```
  Setting up Balanced Sum on this computer. This happens once.

  Your books are kept in PostgreSQL, a database Balanced Sum installs for
  you rather than asking you to install yourself.

    * Downloading it — about 25 MB, from balancedsum.com. You'll see the
      progress below.

    * Creating an empty set of books for it to hold. A few seconds.

  Nothing is installed system-wide, and nothing else on this computer is
  changed. It all goes in one folder:
    C:\Users\you\AppData\Local\BalancedSum
  That folder is also where your books will live, so deleting it is both the
  whole uninstall and the end of your accounting records.
```

Then it downloads, showing you how far along it is, checks that what arrived
is exactly what it expected before unpacking a byte of it, and sets the
database up. Expect a couple of minutes in total on a normal connection —
most of it the download. You'll see lines like
`[database] Downloaded 24.7 MB and verified its checksum.` and
`[database] Your database is set up (PostgreSQL 16.10, port 54329).`

Every launch after that skips all of it and takes a few seconds.

### Once it's running

Leave the PowerShell window open while you work — it prints this once it's
ready:

```
  Balanced Sum is running at http://localhost:3000
  Press Ctrl+C in this window to close it and shut the database down.
```

**To stop the app**, click into that window and press **Ctrl+C**. Closing the
window also stops it. Either way the database is shut down cleanly with the
app, so nothing is left running afterward. Your data is safe either way — it
lives in the database on disk, not in the running program.

If you ever need to get back to the app without restarting it, just open
http://localhost:3000 in your browser again.

---

## 4. Where your data lives

- **The books themselves** live in the database, in this folder:

  ```
  %LOCALAPPDATA%\BalancedSum\
  ```

  which on a normal Windows account means
  `C:\Users\<your name>\AppData\Local\BalancedSum\`. Inside it:

  | | |
  |---|---|
  | `data\pg16\` | **Your books.** The database itself. This is the folder that matters. |
  | `runtime\` | The copy of PostgreSQL the app downloaded. About 120 MB. Replaceable — it's just software. |
  | `logs\` | What the database said while it was running. Useful when something goes wrong, and nothing else. |
  | `instance.json` | Which version and port your database uses. |
  | `secret` | The database's password, generated for your machine alone. Readable only by your Windows account. |

  It is deliberately **outside the application folder**, so re-cloning,
  updating, or deleting the application code cannot touch your books. The
  flip side is the sentence the app itself prints on first run: deleting that
  folder is both the whole uninstall and the end of your accounting records.
- **Backups**: the app takes an automatic daily backup and you can also
  trigger one from Settings in the app. These are plain files, written to
  `Documents\Accounting Backups` by default (override with the `BACKUP_DIR`
  environment variable if you want them somewhere else, e.g. a synced cloud
  folder). Keep the last 30.
- **Restoring** a backup — onto this machine or a brand-new one — is a
  deliberate, manual procedure, documented in full in
  [RESTORE.md](RESTORE.md). Read it before you need it; the single most
  important rule in it is **never restore over a live database**.

---

## 5. Getting the software to another person

Each install is independent — there is no shared or hosted version in v1.
If you want to give someone else their own copy of this app (their own
company's books, starting empty), hand them the **application code only**,
not your data:

1. Clone or zip the repository **excluding**:
   - `imports/` — your uploaded QuickBooks files
   - `reports/` — any generated report output
   - your backups folder, if you keep it inside this folder instead of the
     `Documents\Accounting Backups` default (most people won't have this
     problem — it's outside the repo by default)
   - `node_modules/` (they'll run `npm install` themselves — no need to
     include it, and it's large)

   If you're using `git`, a plain `git clone` (or `git archive`) already
   excludes all of these automatically — they're listed in `.gitignore`
   precisely so a handoff is a clean `git clone` away. If you're zipping the
   folder by hand instead, delete those folders from the zip before sending
   it.
2. They follow **sections 2, 3, and 4** of this document from scratch, on
   their own machine.
3. The first time they run `npm run app`, the app has no companies yet, so
   it takes them straight to the setup wizard. They choose **Start fresh**
   and get a real, working chart of accounts for a small business — never an
   empty, blank slate — ready for them to start recording transactions.
   (The other wizard path, restoring QuickBooks history, is for you moving
   your own historical books forward — it's not what a brand-new recipient
   with no prior books would use.)

---

## 6. Troubleshooting

**The first run can't download PostgreSQL**
The download comes from balancedsum.com over an ordinary HTTPS connection.
If it fails, the message says why. The usual causes, in order: you're
offline, a company firewall or content filter is blocking the address, or the
site is briefly down. A failed attempt leaves nothing half-installed behind
it, so reconnecting and running `npm run app` again is always safe — and is
the whole fix.

If the app says what arrived **didn't match its checksum**, do not work
around it. That means the file it received is not the file we published, and
it refuses to unpack it on purpose. Try again on a different network, and
tell us at support@balancedsum.com if it keeps happening.

**The database wouldn't start**
The app prints an English explanation and, where it helps, the last few lines
of the database's own log. The full log is at:

```
%LOCALAPPDATA%\BalancedSum\logs\postgresql.log
```

Each launch writes a dated banner line into it, so the run you care about is
the one after the last `===== Balanced Sum starting PostgreSQL =====`. If the
app tells you the database was already running and you don't think it was,
you may have a second PowerShell window still running `npm run app` — check
before doing anything else.

**Port 3000 is already in use**
Something else on this machine (possibly a previous, not-fully-stopped run
of this same app) is using port 3000. Find and stop it:

```powershell
Get-NetTCPConnection -LocalPort 3000 -State Listen | Select-Object OwningProcess
Stop-Process -Id <the process id from above> -Force
```

Then run `npm run app` again. If this keeps happening, make sure you're
stopping the app with Ctrl+C in its own window rather than closing the
window a different way.

**Backup failed**
Backups are taken with `pg_dump`, which came with the PostgreSQL the app
installed for you, so there is nothing for you to install. If the app says it
can't find it, close Balanced Sum and open it again — it checks its own
PostgreSQL on every launch and reinstalls anything missing. If a backup
reports the output was "empty or suspiciously small," something interrupted
it partway through; nothing was saved (it never leaves a half-written backup
under a real filename), so simply try **Settings → Back up now** again.

**Something else looks wrong**
The dashboard has a health panel that flags common issues (books not
balancing, unlocked prior years, wrong-sign balances, and — if you keep stock
— your stock records disagreeing with what your books say inventory is worth)
with an explanation of each. For anything not covered there or above, the terminal window running
`npm run app` prints what actually failed — that message is written in
plain English on purpose; it's meant to be read, not just reported.
