nicholas/formulation
1
0
Fork 0
Code Pull Requests Actions Activity

docs: update project README

Browse Source
This commit is contained in:
nicholas
2026-08-13 15:44:35 -05:00
parent 3e81d54262
commit e89d003d71
1 changed files with 128 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+128 -65
View File
@@ -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.