nicholas
21651e1ce8
- Resolve ingredient table overflow and 2-column layout on laptop screens (1280px-1440px) - Align recipe, ingredient, and directory pages with meez visual design specifications - Implement segmented icon navigation tabs across recipe and ingredient detail views - Standardize top utility bar and entity detail header alignment across all viewports - Fix mobile home page filter popup z-index and viewport overflow clipping - Clean up legacy prototype media queries and consolidate responsive CSS system
2.9 KiB
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
Create the initial database from the current portable dataset with Node 22 or newer, then run either application mode:
npm run db:reset
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. migrations/001_initial.sql defines the complete relational schema.
The application does not support upgrading databases from older schemas: rebuild
from portable data with npm run db:reset. Recipe edits are transactional and a
private save token prevents stale browser tabs from overwriting newer changes.
There is no recipe revision history.
npm run db:import:yaml and npm run db:reset both delete and replace the
database from portable YAML. They are intended only for initial setup or an
explicit restore. Running either command after application edits can discard
newer SQLite-only data.
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.