nicholasandnicholas
2a1e16ed30
Reviewed-on: #14 Co-authored-by: Nicholas Ward <nicholaspward@outlook.com>
81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
# 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.
|