docs: update project README
This commit is contained in:
@@ -1,91 +1,154 @@
|
||||
# advanced-food-making
|
||||
# Formulation
|
||||
|
||||
A recipe collection
|
||||
Formulation is a culinary recipe-management application for building, scaling,
|
||||
costing, and analyzing professional recipes. It models ingredients and
|
||||
sub-recipes as reusable entities instead of embedding duplicated ingredient
|
||||
data in every recipe.
|
||||
|
||||
Canonical version 2 culinary data lives in `culinary/` and is defined by the
|
||||
vendor-neutral schemas in `container/schemas/v2/`. Two independent Astro applications
|
||||
consume the shared data and libraries;
|
||||
see [the culinary data model](docs/culinary-data-model.md) for entity boundaries,
|
||||
density and unit semantics, and USDA provenance.
|
||||
The project includes two independent Astro applications:
|
||||
|
||||
## Knowledge Sync
|
||||
- A SQLite-backed management application for recipes, ingredients, purchasing,
|
||||
nutrition, costs, preparation actions, conversions, and recipe books.
|
||||
- A read-only static cooking site generated from the same culinary data.
|
||||
|
||||
The Gitea Actions workflow at
|
||||
`.gitea/workflows/sync-knowledge.yml` exports the recipes as clean
|
||||
Markdown and synchronizes them to the Gourmand Open WebUI knowledge base. It
|
||||
runs when recipe content, ingredient data, or the corpus exporter changes on
|
||||
`master`, and it can also be started manually.
|
||||
## Capabilities
|
||||
|
||||
Configure these Actions variables in this repository:
|
||||
- Structured recipes with components, sub-recipes, ordered preparation steps,
|
||||
yields, tags, and shelf life
|
||||
- Recipe scaling using amounts, standard percentages, or baker's percentages
|
||||
- Weight, volume, count, density, and ingredient-specific unit conversions
|
||||
- Preparation yields and loss or gain factors
|
||||
- Recursive nutrition and recipe costing
|
||||
- USDA FoodData Central mappings with source provenance
|
||||
- Ingredient aliases, purchasing packages, suppliers, and price history
|
||||
- Nutrition labels and missing-data indicators
|
||||
|
||||
```text
|
||||
OPEN_WEBUI_URL
|
||||
GOURMAND_KB_ID
|
||||
```
|
||||
The [culinary data model](docs/culinary-data-model.md) documents entity
|
||||
boundaries, measurement semantics, provenance, and portability conventions.
|
||||
|
||||
Configure this Actions secret:
|
||||
## Requirements
|
||||
|
||||
```text
|
||||
KNOWLEDGE_SYNC_OPEN_WEBUI_API_KEY
|
||||
```
|
||||
- Node.js 22.12 or newer
|
||||
- npm 9.6.5 or newer
|
||||
- Python 3 for schema and content validation utilities
|
||||
|
||||
The existing knowledge-sync account and API key may be reused if the account
|
||||
has permission to manage files in the Gourmand knowledge base.
|
||||
|
||||
To inspect the generated corpus locally, run:
|
||||
|
||||
```bash
|
||||
scripts/corpus-export
|
||||
```
|
||||
|
||||
Validate canonical entities, schema conformance, and cross-references before
|
||||
building or committing changes:
|
||||
|
||||
```bash
|
||||
python3 -m pip install --user -r requirements-dev.txt
|
||||
scripts/validate-content
|
||||
```
|
||||
|
||||
To review purchasing products extracted from the sibling `ledger` receipt
|
||||
archive, run `scripts/receipt-products propose` and open
|
||||
`/tools/purchasing-review/`. Export the decisions and apply them with:
|
||||
|
||||
```bash
|
||||
scripts/receipt-products apply ~/Downloads/purchasing-decisions.json
|
||||
scripts/validate-content
|
||||
```
|
||||
|
||||
Build both applications:
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run db:reset # initial setup only; do not use over an edited database
|
||||
python3 -m pip install --user -r requirements-dev.txt
|
||||
```
|
||||
|
||||
## Database
|
||||
|
||||
SQLite is the canonical writable store. The database is located at
|
||||
`var/recipe-book.sqlite` and is intentionally excluded from Git. Numbered SQL
|
||||
migrations in `migrations/` define its schema.
|
||||
|
||||
Create a new local database from the portable culinary dataset:
|
||||
|
||||
```bash
|
||||
npm run db:reset
|
||||
```
|
||||
|
||||
This command replaces an existing local database. For an existing database,
|
||||
apply pending migrations without replacing data:
|
||||
|
||||
```bash
|
||||
npm run db:migrate
|
||||
```
|
||||
|
||||
`npm run db:sync` is an alias for the safe migration command. YAML under
|
||||
`culinary/` is retained as portable seed and interchange data; normal edits in
|
||||
the management application write to SQLite.
|
||||
|
||||
See [Local application](docs/local-application.md) for more detail.
|
||||
|
||||
## Development
|
||||
|
||||
Run the management application:
|
||||
|
||||
```bash
|
||||
npm run dev:app
|
||||
```
|
||||
|
||||
Open <http://localhost:4322/app/>.
|
||||
|
||||
To stop any process listening on the application port and start a fresh Astro
|
||||
development server:
|
||||
|
||||
```bash
|
||||
npm run restart:app
|
||||
```
|
||||
|
||||
Run the static cooking site separately:
|
||||
|
||||
```bash
|
||||
npm run dev:site
|
||||
```
|
||||
|
||||
Open <http://localhost:4321/>. The site command creates a read-only projection
|
||||
at `generated/site-projection.json` before Astro starts.
|
||||
|
||||
## Validation and builds
|
||||
|
||||
Run application and site type checks, unit tests, and both production builds:
|
||||
|
||||
```bash
|
||||
npm run check
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
The frontend requires Node.js 22.12 or newer. The public cooking site is a fully
|
||||
static build in `dist/site`; the SQLite-backed management application is a Node
|
||||
server build in `dist/app`. They share components and culinary calculation code,
|
||||
but neither artifact contains the other application's routes. The site build
|
||||
generates a read-only projection from SQLite before Astro renders its pages.
|
||||
Build output is separated by application:
|
||||
|
||||
Run them independently during development:
|
||||
- `dist/app/` — standalone Node server for the management application
|
||||
- `dist/site/` — static public cooking site
|
||||
|
||||
## Culinary data tools
|
||||
|
||||
Validate portable culinary entities, schemas, and cross-references:
|
||||
|
||||
```bash
|
||||
npm run dev:site # http://localhost:4321
|
||||
npm run dev:app # http://localhost:4322/app/
|
||||
scripts/validate-content
|
||||
```
|
||||
|
||||
The generated files are written to `generated/open-webui/recipes/` and are not
|
||||
committed.
|
||||
|
||||
Search USDA FoodData Central and import a candidate mapping with:
|
||||
Search USDA FoodData Central and import a nutrition mapping:
|
||||
|
||||
```bash
|
||||
USDA_FDC_API_KEY=... scripts/usda-fdc search "all-purpose flour"
|
||||
USDA_FDC_API_KEY=... scripts/usda-fdc import flour_all_purpose 790018
|
||||
```
|
||||
|
||||
Add `--reviewed` only after confirming that the USDA description matches the
|
||||
canonical ingredient. An official USDA JSON download can be supplied with
|
||||
`--dataset` instead. Never commit the API key.
|
||||
Use `--reviewed` only after confirming that the selected record describes the
|
||||
canonical ingredient. Never commit the USDA API key.
|
||||
|
||||
Purchasing candidates can be proposed from the sibling `ledger` receipt
|
||||
archive and reviewed in the application:
|
||||
|
||||
```bash
|
||||
scripts/receipt-products propose
|
||||
scripts/receipt-products apply ~/Downloads/purchasing-decisions.json
|
||||
```
|
||||
|
||||
The review interface is available at `/tools/purchasing-review/`.
|
||||
|
||||
## Knowledge export
|
||||
|
||||
Generate the recipe corpus used by external knowledge systems:
|
||||
|
||||
```bash
|
||||
scripts/corpus-export
|
||||
```
|
||||
|
||||
The Gitea Actions workflow in `.gitea/workflows/sync-knowledge.yml` can publish
|
||||
that corpus to an Open WebUI knowledge base. Configure these repository Actions
|
||||
variables:
|
||||
|
||||
```text
|
||||
OPEN_WEBUI_URL
|
||||
GOURMAND_KB_ID
|
||||
```
|
||||
|
||||
Configure the API key as the `KNOWLEDGE_SYNC_OPEN_WEBUI_API_KEY` Actions secret.
|
||||
Generated exports are not committed.
|
||||
|
||||
Reference in New Issue
Block a user