# Roastery

Roastery is a coffee subscription platform that helps customers discover freshly roasted beans from independent roasters. Subscribers can customize their delivery schedule, roast preference, grind size, and quantity, then manage upcoming shipments from a self-service dashboard.

## Features

- Flexible weekly, biweekly, or monthly subscriptions
- Curated coffee recommendations based on taste preferences
- Whole-bean and ground coffee options
- Single-origin and rotating roaster selections
- Subscription pause, skip, resume, and cancellation flows
- Upcoming shipment and order history dashboard
- Secure checkout and recurring billing with Stripe
- Transactional email notifications
- Mobile-friendly customer experience

## Installation

### Prerequisites

- Node.js 20 or later
- PostgreSQL 15 or later
- npm 10 or later
- A Stripe account for billing

Clone the repository and install dependencies:

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

Create a local environment file:

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

Initialize the database:

```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 an account, complete the taste questionnaire, and choose a subscription plan. From the customer dashboard, subscribers can:

- Review their next coffee selection
- Change delivery frequency or quantity
- Update roast and grind preferences
- Skip or pause upcoming shipments
- Manage payment and shipping information
- View previous orders

To test recurring billing locally, forward Stripe webhook events to the application:

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

Run the test suite with:

```bash
npm test
```

Create a production build with:

```bash
npm run build
npm start
```

## Configuration

Configure the application with 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 user sessions |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | Secret used to verify Stripe webhook events |
| `STRIPE_PRICE_WEEKLY` | Yes | Stripe price ID for weekly subscriptions |
| `STRIPE_PRICE_BIWEEKLY` | Yes | Stripe price ID for biweekly subscriptions |
| `STRIPE_PRICE_MONTHLY` | Yes | Stripe price ID for monthly subscriptions |
| `EMAIL_FROM` | Yes | Sender address for transactional email |
| `SMTP_HOST` | Yes | SMTP server hostname |
| `SMTP_PORT` | Yes | SMTP server port |
| `SMTP_USER` | Yes | SMTP username |
| `SMTP_PASSWORD` | Yes | SMTP password |
| `LOG_LEVEL` | No | Logging verbosity; 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

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

LOG_LEVEL=debug
```

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