nicholas
816b28e179
Consolidate the application, culinary data model, read-only runtime, and registry-backed deployment.
145 lines
4.0 KiB
Markdown
145 lines
4.0 KiB
Markdown
# Formulation
|
|
|
|
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.
|
|
|
|
The Astro application can run as either the full editor or a server-enforced
|
|
read-only viewer. Both modes provide recipes, ingredients, purchasing data,
|
|
nutrition, live costs, scaling, conversions, and recipe books. Read-only mode
|
|
removes persistent editing while retaining browser-side calculations.
|
|
|
|
## Capabilities
|
|
|
|
- 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
|
|
|
|
The [culinary data model](docs/culinary-data-model.md) documents entity
|
|
boundaries, measurement semantics, provenance, and portability conventions.
|
|
|
|
## Requirements
|
|
|
|
- Node.js 22.12 or newer
|
|
- npm 9.6.5 or newer
|
|
- Python 3 for schema and content validation utilities
|
|
|
|
Install dependencies:
|
|
|
|
```bash
|
|
npm ci
|
|
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. The single
|
|
baseline in `migrations/001_initial.sql` defines its complete schema.
|
|
|
|
Create a new local database from the portable culinary dataset:
|
|
|
|
```bash
|
|
npm run db:reset
|
|
```
|
|
|
|
This command replaces an existing local database. There is intentionally no
|
|
legacy upgrade chain. 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 editor:
|
|
|
|
```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 same application in read-only mode:
|
|
|
|
```bash
|
|
npm run dev:readonly
|
|
```
|
|
|
|
Open <http://localhost:4399/app/>. The database is opened read-only, modifying
|
|
HTTP requests are rejected, and editing controls and routes are unavailable.
|
|
|
|
## Validation and builds
|
|
|
|
Run type checks, unit tests, and the production build:
|
|
|
|
```bash
|
|
npm run check
|
|
npm test
|
|
npm run build
|
|
```
|
|
|
|
The standalone Node server is written to `dist/app/`. Start a production
|
|
read-only instance on port 4399 with `npm run start:readonly`.
|
|
|
|
## Culinary data tools
|
|
|
|
Validate portable culinary entities, schemas, and cross-references:
|
|
|
|
```bash
|
|
scripts/validate-content
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
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.
|