# 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.