# RoastRoute

RoastRoute is a coffee subscription platform for small-batch roasters. Customers can build recurring coffee plans based on taste preferences, grind type, delivery frequency, and bag size, while operators manage products, subscriptions, orders, shipping, and billing from one dashboard.

## Features

- Personalized subscription onboarding with roast, flavor, brew method, and caffeine preferences
- One-time purchases and recurring coffee subscriptions
- Stripe checkout, billing portal, and webhook handling
- Customer account management for pausing, skipping, or changing deliveries
- Admin catalog tools for coffees, origins, inventory, and roast schedules
- Order generation based on subscription cadence
- Shipping label workflow integration
- Email notifications for checkout, renewals, shipment updates, and failed payments
- Local seed data for demo coffees, plans, and test customers

## Install

### Prerequisites

- Node.js 20+
- PostgreSQL 15+
- npm 10+
- Stripe CLI for local webhook testing

### Setup

```bash
git clone https://github.com/example/roastroute.git
cd roastroute
npm install
cp .env.example .env
```

Update `.env` with your local database URL and service credentials, then run:

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

The app will be available at:

```text
http://localhost:3000
```

## Usage

Start the development server:

```bash
npm run dev
```

Run database migrations:

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

Seed demo data:

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

Run tests:

```bash
npm test
```

Listen for Stripe webhooks locally:

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

Create a test checkout flow by visiting `/subscribe`, choosing a plan, and using Stripe test card `4242 4242 4242 4242`.

## Configuration

RoastRoute is configured through environment variables.

```env
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/roastroute"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."

EMAIL_FROM="RoastRoute <orders@roastroute.test>"
SENDGRID_API_KEY="SG..."

SHIPPO_API_KEY="shippo_test_..."
ADMIN_EMAIL="admin@roastroute.test"
```

| Variable | Required | Description |
| --- | --- | --- |
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `NEXT_PUBLIC_APP_URL` | Yes | Public base URL used for redirects and emails |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Yes | Stripe browser publishable key |
| `EMAIL_FROM` | Yes | Sender address for transactional emails |
| `SENDGRID_API_KEY` | No | Enables transactional email delivery |
| `SHIPPO_API_KEY` | No | Enables shipping label creation |
| `ADMIN_EMAIL` | Yes | Default administrator account email |

For production, use managed PostgreSQL, live Stripe keys, verified email sending domains, and HTTPS for webhook delivery.