formulation/docs/local-application.md

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:

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:

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:

# 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:

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:

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.