# Roam Coffee

Roam Coffee is a subscription platform for discovering freshly roasted coffee from independent roasters. Customers choose their preferred roast, grind, delivery frequency, and bag quantity, then receive a rotating selection matched to their taste.

## Features

- Flexible weekly, biweekly, or monthly subscriptions
- Whole-bean and grind-size options
- Personalized roast and flavor preferences
- Curated coffee rotation from independent roasters
- Subscription pause, skip, and cancellation controls
- Shipment and order history
- Stripe-powered checkout and recurring billing
- Email notifications for upcoming deliveries
- Customer and subscription management dashboard

## Requirements

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

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/example/roam-coffee.git
cd roam-coffee
npm install
```

Create a local environment file:

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

Create the database and run migrations:

```bash
createdb roam_coffee
npm run db:migrate
```

Optionally load sample coffees and subscription plans:

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

Start the development server:

```bash
npm run dev
```

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

## Usage

Run the application in development mode:

```bash
npm run dev
```

Create an optimized production build:

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

Run the test suite:

```bash
npm test
```

Run formatting and lint checks:

```bash
npm run format
npm run lint
```

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

```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

Roam Coffee is configured with environment variables in `.env`.

```dotenv
NODE_ENV=development
PORT=3000
APP_URL=http://localhost:3000

DATABASE_URL=postgresql://localhost:5432/roam_coffee
SESSION_SECRET=replace-with-a-long-random-value

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=mailer@example.com
SMTP_PASSWORD=replace-me
EMAIL_FROM="Roam Coffee <hello@example.com>"

DEFAULT_CURRENCY=USD
ORDER_CUTOFF_DAYS=3
```

| Variable | Required | Description |
| --- | --- | --- |
| `NODE_ENV` | Yes | Runtime environment: `development`, `test`, or `production`. |
| `PORT` | No | HTTP port. Defaults to `3000`. |
| `APP_URL` | Yes | Public application URL used for redirects and email links. |
| `DATABASE_URL` | Yes | PostgreSQL connection string. |
| `SESSION_SECRET` | Yes | Secret used to sign customer sessions. |
| `STRIPE_SECRET_KEY` | Yes | Stripe server-side API key. |
| `STRIPE_PUBLISHABLE_KEY` | Yes | Stripe browser-side API key. |
| `STRIPE_WEBHOOK_SECRET` | Yes | Signing secret used to verify Stripe webhook events. |
| `SMTP_HOST` | Yes | Outgoing mail server hostname. |
| `SMTP_PORT` | Yes | Outgoing mail server port. |
| `SMTP_USER` | Yes | SMTP account username. |
| `SMTP_PASSWORD` | Yes | SMTP account password. |
| `EMAIL_FROM` | Yes | Sender shown on transactional emails. |
| `DEFAULT_CURRENCY` | No | ISO currency code. Defaults to `USD`. |
| `ORDER_CUTOFF_DAYS` | No | Days before fulfillment when subscription changes are locked. |

Never commit `.env` files or production credentials to version control. Use your deployment provider’s secret manager in production.