# Roastery

Roastery is a coffee subscription platform for small-batch roasters. Customers can build a taste profile, choose a delivery schedule, and receive freshly roasted coffee selected to match their preferences.

## Features

- Personalized coffee recommendations based on roast, origin, and tasting notes
- Flexible weekly, biweekly, or monthly subscriptions
- Whole-bean and ground coffee options
- Subscription pausing, skipping, and cancellation
- Shipment and order history
- Inventory-aware product selection
- Stripe-powered checkout and recurring billing
- Transactional email notifications
- Customer and subscription management dashboard

## Requirements

- Node.js 20 or later
- PostgreSQL 15 or later
- npm 10 or later
- Stripe account and API keys

## Installation

Clone the repository and install the dependencies:

```bash
git clone https://github.com/example/roastery.git
cd roastery
npm install
```

Create a local environment file:

```bash
cp .env.example .env
```

Create the database and apply migrations:

```bash
npm run db:migrate
npm run db:seed
```

Start the development server:

```bash
npm run dev
```

The application will be available at `http://localhost:3000`.

## Usage

Create a customer account, complete the taste-profile questionnaire, and select a subscription plan. The recommendation engine will choose an available coffee for each upcoming shipment.

Common development commands:

```bash
npm run dev          # Start the development server
npm run build        # Create a production build
npm start            # Run the production server
npm test             # Run the test suite
npm run lint         # Check code style
npm run db:migrate   # Apply database migrations
npm run db:seed      # Load sample coffees and plans
```

To test Stripe webhooks locally:

```bash
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

Copy the webhook signing secret printed by the Stripe CLI into `STRIPE_WEBHOOK_SECRET`.

## Configuration

Roastery is configured through environment variables in `.env`.

| Variable | Required | Description |
| --- | --- | --- |
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `APP_URL` | Yes | Public application URL |
| `SESSION_SECRET` | Yes | Secret used to sign sessions |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret |
| `STRIPE_PRICE_WEEKLY` | Yes | Stripe price ID for weekly deliveries |
| `STRIPE_PRICE_BIWEEKLY` | Yes | Stripe price ID for biweekly deliveries |
| `STRIPE_PRICE_MONTHLY` | Yes | Stripe price ID for monthly deliveries |
| `SMTP_HOST` | Yes | Outgoing mail server hostname |
| `SMTP_PORT` | No | Outgoing mail server port; defaults to `587` |
| `SMTP_USER` | Yes | SMTP username |
| `SMTP_PASSWORD` | Yes | SMTP password |
| `EMAIL_FROM` | Yes | Sender address for transactional email |
| `LOG_LEVEL` | No | Logging level; defaults to `info` |

Example development configuration:

```dotenv
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/roastery
APP_URL=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-value

STRIPE_SECRET_KEY=sk_test_example
STRIPE_WEBHOOK_SECRET=whsec_example
STRIPE_PRICE_WEEKLY=price_example_weekly
STRIPE_PRICE_BIWEEKLY=price_example_biweekly
STRIPE_PRICE_MONTHLY=price_example_monthly

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASSWORD=
EMAIL_FROM=Roastery <hello@roastery.test>

LOG_LEVEL=debug
```

Never commit `.env` files or production credentials to version control.