# RoastRoute

RoastRoute is a coffee subscription platform for independent roasters and specialty coffee customers. It handles recurring subscriptions, roast preferences, shipment scheduling, payment setup, and customer account management.

## Overview

RoastRoute helps small coffee businesses launch and manage flexible subscription programs without building the operational tooling from scratch. Customers can choose their grind size, roast profile, delivery cadence, and bag quantity, while administrators can manage products, inventory, billing status, and upcoming fulfillment batches.

The project is designed as a full-stack web application with a customer storefront, account dashboard, and admin workflow for subscription operations.

## Features

- Customer signup and account management
- Coffee subscription plans with configurable delivery cadence
- Roast, origin, grind, and bag-size preferences
- One-time coffee purchases alongside subscriptions
- Subscription pause, resume, skip, and cancellation flows
- Upcoming shipment preview and order history
- Admin product and inventory management
- Fulfillment batch view for upcoming roast and ship dates
- Payment integration support
- Email notifications for confirmations, renewals, and shipping updates

## Install

Clone the repository:

```bash
git clone https://github.com/example/roastroute.git
cd roastroute
```

Install dependencies:

```bash
npm install
```

Create an environment file:

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

Run database migrations:

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

Seed local development data:

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

Start the development server:

```bash
npm run dev
```

The app will be available at:

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

## Usage

Create a customer account and choose a subscription plan from the storefront. Select coffee preferences such as roast level, grind type, delivery frequency, and quantity.

Customers can manage their subscription from the account dashboard:

- Update delivery address
- Change billing details
- Skip the next shipment
- Pause or resume a subscription
- Change coffee preferences
- View previous orders

Administrators can access the admin dashboard to:

- Add or edit coffee products
- Manage available inventory
- Review active subscriptions
- Generate fulfillment batches
- Track upcoming shipments
- Review failed payments and inactive subscriptions

Useful development commands:

```bash
npm run dev
npm run test
npm run lint
npm run build
npm run start
```

## Configuration

RoastRoute is configured through environment variables.

```env
APP_URL=http://localhost:3000
DATABASE_URL=postgres://user:password@localhost:5432/roastroute
SESSION_SECRET=change-me

PAYMENT_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_example
STRIPE_WEBHOOK_SECRET=whsec_example

EMAIL_PROVIDER=postmark
POSTMARK_SERVER_TOKEN=example-token
EMAIL_FROM=hello@roastroute.test

DEFAULT_CURRENCY=USD
DEFAULT_SHIPPING_COUNTRY=US
FULFILLMENT_CUTOFF_DAY=3
```

### Required Variables

| Variable | Description |
| --- | --- |
| `APP_URL` | Public URL used for redirects and email links |
| `DATABASE_URL` | PostgreSQL connection string |
| `SESSION_SECRET` | Secret used to sign user sessions |
| `STRIPE_SECRET_KEY` | Secret key for payment processing |
| `STRIPE_WEBHOOK_SECRET` | Webhook signing secret for payment events |
| `EMAIL_FROM` | Sender address for transactional emails |

### Optional Variables

| Variable | Default | Description |
| --- | --- | --- |
| `DEFAULT_CURRENCY` | `USD` | Currency used for product pricing |
| `DEFAULT_SHIPPING_COUNTRY` | `US` | Default country for shipping forms |
| `FULFILLMENT_CUTOFF_DAY` | `3` | Day of the week used to group upcoming subscription shipments |
| `ENABLE_GIFT_SUBSCRIPTIONS` | `false` | Enables gift subscription checkout |
| `ENABLE_LOW_STOCK_ALERTS` | `true` | Sends admin alerts when inventory is low |