# Local recipe application

The local application uses SQLite as its canonical data store. YAML remains a
portable import/export format, but normal application saves do not modify it.
Derived nutrition and cost are still calculated rather than stored.

## Source-of-truth rule

- SQLite is the only writable source of truth for a running installation.
- Humans should edit through the management application.
- Automation and AI agents should call validated application commands or domain
  save functions such as `saveRecipeStructure()`.
- Agents should not edit YAML to change live data and should not issue
  unrestricted SQL when a domain operation exists.
- Generated site projections and exports are downstream products of SQLite.

A safe automated recipe change follows this flow:

```text
agent request
  -> validate recipe structure and references
  -> domain save function
  -> SQLite transaction
  -> refresh derived projection
  -> optional explicit export for backup or review
```

Run either application mode with Node 22 or newer:

```sh
npm run dev:readonly
npm run dev:app
```

Read-only mode serves the same application with SQLite opened read-only, removes
editing controls, and rejects modifying HTTP requests. Browser-side scaling,
unit conversion, nutrition, and costing calculations remain available.

The database is written to `var/recipe-book.sqlite` and is intentionally ignored
by Git. Recipe edits are transactional and a private save token prevents stale
browser tabs from overwriting newer changes.

### Backup and Restore

To export or restore database snapshots across all 25 SQLite tables:

```sh
# Export a JSON backup
npm run db:backup -- [path/to/backup.json]

# Restore database from backup
npm run db:restore -- path/to/backup.json
```

Users can also export and restore backups interactively from the web UI at `/app/settings/`.

## Windows dev-server notes

Node is installed at `C:\Program Files\nodejs` but is not on the default
agent shell PATH. Prefix every npm/npx command:

```bat
cmd /c "set PATH=C:\Program Files\nodejs;%PATH%&& npm run dev:app"
```

`astro dev` runs as a detached daemon (Astro 7). To stop it, find the PID
from the port and kill it directly — `scripts/restart-app.mjs` reads `/proc`
and does not work on Windows:

```bat
netstat -ano | findstr :4322
taskkill /PID <pid> /F /T
```

A long-running dev server inherited from another session can degrade
silently: pages render but Preact islands never hydrate (empty
`astro-island`, no console error). Before debugging component code, check
whether the recipe table hydrates and, if not, restart the dev server. The
URL pattern `?astro&type=script` returns 500 even when hydration works — it
is not a valid diagnostic.