Build and run the app

Paths in this guide are relative to the folder you get by unpacking the download.

# Continuity application

Optional. Everything it shows lives in plain files that open without it
(charter §4.4). Architecture: [ADR-003](../decisions/ADR-003-application-architecture.md);
sign-in, writing and history: [ADR-004](../decisions/ADR-004-sign-in-writing-history.md).

| Folder | What |
|---|---|
| `backend/` | Spring Boot 4 / Java 25. Modules: `vault`, `records`, `index`, `query`, `audit`, `editing`, `auth` |
| `frontend/` | React + TypeScript + MUI (Vite). Built into the backend jar. Fonts bundled; no CDN |
| `dev-vault/` | A **fictional** vault for development and tests. Never put real data here |

## Build

You need JDK 25, Node 20.19 or newer, and Docker or Podman.

```
cd app/frontend && npm ci && npm run build      # → app/frontend/dist
cd ../backend && ./mvnw package                 # the jar includes dist/ as its web page
```

## Run (development, fictional vault)

```
docker compose -f deploy/compose.yaml up -d      # PostgreSQL, data on tmpfs, 127.0.0.1:5437
cd app/backend
java -jar target/continuity-backend-*.jar --spring.profiles.active=dev
```

Open http://localhost:8437.

**The first time**, the app prints a one-time code in its own window. Type
it in the browser, and the app makes your **sign-in code** and shows it
once. Save it in your password manager, then sign in with it (ADR-007 §3).
Only its hash is kept, in the vault at `c1/app/sign-in.json`. To make a
new one (lost or leaked), delete that file from the unlocked vault and
start the app again.

For frontend work, run `npm run dev` in `app/frontend`
(http://localhost:5173). It forwards the API to the backend.

The dev profile writes into `app/dev-vault`. To keep the fixtures
unchanged, point it at a copy with
`--continuity.vault.root=/path/to/copy`.

## Run against the real vault

Unlock first (`tools/unlock`), then start without the `dev` profile. The
app refuses to start unless every compartment in `$CONTINUITY_DATA/mnt` is
a mounted, unlocked compartment. It listens on 127.0.0.1 only; server
mode (TLS, reverse proxy) is step 9.

## Tests

| Command | What |
|---|---|
| `cd app/backend && ./mvnw test` | 66 tests: rules, parser, steps, vault, sign-in, editing, delete, pictures, procedure runs, timeline, level, photos, API (Testcontainers; needs Docker) |
| `cd app/frontend && npm run typecheck` | TypeScript |
| Browser test (below) | The whole app in Chromium, from first use (setup code, sign-in code) on |

### Browser test

1. Start the app against a **copy** of `dev-vault`. It must have no
   `c1/app/sign-in.json`, so the app prints a setup code.
2. Run, with the code from the app's window:

```
cd app/frontend
npx playwright install chromium      # once
SETUP_CODE=XXXX-XXXX-XXXX npx playwright test
```

It makes the sign-in code, refuses a wrong one, signs in, and uses Attention, Search, Record, mark as
checked, Editor, "View as it was", a refused save, Supersede, the phone
layout, the Procedure runner (including a careful step and "Welcome
back"), Timeline, About me, adding pictures and taking one off, deleting a record (refused, then done),
switching to Guided and back (its memory home,
My people, Papers and accounts, and the pause
before saving), and Lock now. Screenshots go to `test-results/screens/`.