# Emberleaf

Emberleaf is a lightweight roast-profile manager for small-batch tea production. It helps tea roasters record batches, follow repeatable temperature curves, track sensory notes, and export production logs without requiring specialized cloud software.

Designed for countertop and workshop roasters, Emberleaf works well for experimental batches, seasonal lots, and day-to-day production.

## Features

- Create reusable roast profiles with timed temperature stages
- Record origin, cultivar, harvest date, oxidation level, and batch weight
- Run guided roast sessions with stage timers and temperature targets
- Add live observations and post-roast tasting notes
- Track weight loss and calculate roast yield
- Search previous batches by lot, profile, date, or result
- Export batch records as CSV or JSON
- Store all data locally using SQLite
- Optional serial temperature-probe input

## Requirements

- Node.js 20 or later
- npm 10 or later
- SQLite 3
- A modern web browser

A serial temperature probe is optional. Emberleaf can also be used with manual temperature entry.

## Install

Clone the repository and install the dependencies:

```sh
git clone https://github.com/example/emberleaf.git
cd emberleaf
npm install
```

Create a local configuration file:

```sh
cp .env.example .env
```

Initialize the database:

```sh
npm run db:migrate
```

Start the application:

```sh
npm run dev
```

Open `http://localhost:4173` in your browser.

For a production build:

```sh
npm run build
npm start
```

## Usage

### Create a roast profile

1. Open **Profiles** and select **New Profile**.
2. Enter a descriptive name, such as `Spring Baozhong — Light Finish`.
3. Add one or more roast stages with a target temperature and duration.
4. Set an optional cooling duration and notes.
5. Save the profile.

Example profile:

| Stage | Target | Duration | Purpose |
|---|---:|---:|---|
| Warm | 80°C | 4 min | Evenly warm the leaf |
| Dry | 105°C | 8 min | Reduce residual moisture |
| Develop | 125°C | 6 min | Build aroma and sweetness |
| Finish | 140°C | 2 min | Set the final roast character |
| Cool | Ambient | 10 min | Stop development |

### Run a batch

1. Select **New Batch**.
2. Choose a profile and enter the tea lot and starting weight.
3. Start the roast session.
4. Advance through each stage while following the displayed targets.
5. Record temperature readings and observations as needed.
6. Enter the cooled weight when the roast is complete.

Emberleaf calculates weight loss automatically:

```text
weight loss = (green weight - roasted weight) / green weight × 100
```

### Record tasting notes

After the tea has rested, open the batch record and add:

- Resting time
- Brewing parameters
- Aroma
- Flavor
- Mouthfeel
- Finish
- Defects
- Overall score

Notes can be updated later as the roast settles.

### Export records

Export all batch records:

```sh
npm run export -- --format csv --output ./exports/batches.csv
```

Export a single lot as JSON:

```sh
npm run export -- --format json --lot TW-2026-041
```

## Configuration

Emberleaf reads configuration from environment variables in `.env`.

```dotenv
PORT=4173
DATABASE_PATH=./data/emberleaf.sqlite
TEMPERATURE_UNIT=C
DEFAULT_BATCH_UNIT=g
ROAST_TIMEZONE=America/Toronto
SERIAL_ENABLED=false
SERIAL_PORT=/dev/ttyUSB0
SERIAL_BAUD_RATE=9600
BACKUP_DIRECTORY=./backups
BACKUP_RETENTION_DAYS=30
```

| Variable | Default | Description |
|---|---|---|
| `PORT` | `4173` | HTTP port used by the application |
| `DATABASE_PATH` | `./data/emberleaf.sqlite` | Path to the SQLite database |
| `TEMPERATURE_UNIT` | `C` | Display unit: `C` or `F` |
| `DEFAULT_BATCH_UNIT` | `g` | Batch-weight unit: `g`, `kg`, or `oz` |
| `ROAST_TIMEZONE` | System timezone | Timezone used for batch timestamps |
| `SERIAL_ENABLED` | `false` | Enables temperature-probe input |
| `SERIAL_PORT` | Empty | Serial device path |
| `SERIAL_BAUD_RATE` | `9600` | Probe serial baud rate |
| `BACKUP_DIRECTORY` | `./backups` | Directory for database backups |
| `BACKUP_RETENTION_DAYS` | `30` | Number of days to retain backups |

Restart Emberleaf after changing configuration values.

## Data and Backups

All production data is stored in the configured SQLite database. Create a backup with:

```sh
npm run backup
```

Restore a backup with:

```sh
npm run restore -- ./backups/emberleaf-2026-07-15.sqlite
```

Stop the application before restoring a database.

## License

MIT License. See `LICENSE` for details.