# Roam Coffee

Roam Coffee is a subscription platform for independent roasters and curious coffee drinkers. Customers create a taste profile, choose a delivery schedule, and receive freshly roasted coffee matched to their preferences.

## Features

- Personalized recommendations based on roast, origin, process, and brew method
- Flexible weekly, biweekly, and monthly subscriptions
- Whole-bean or custom grind selections
- Subscription pause, skip, and cancellation controls
- Rotating catalog from independent roasters
- Shipment tracking and delivery notifications
- Customer ratings that improve future recommendations
- Admin tools for managing coffees, inventory, orders, and subscribers

## Requirements

- Node.js 20 or later
- PostgreSQL 15 or later
- npm 10 or later

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/roam-coffee/subscriptions.git
cd subscriptions
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
npm run db:seed
```

Start the development server:

```bash
npm run dev
```

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

## Usage

Run the development server with automatic reload:

```bash
npm run dev
```

Create a production build:

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

Run the test suite:

```bash
npm test
```

Run linting and type checks:

```bash
npm run lint
npm run typecheck
```

Seed data includes sample coffees, roasters, and a demo customer account:

```text
Email: demo@roamcoffee.test
Password: coffee123
```

The demo credentials are intended for local development only.

## Configuration

Configuration is provided through environment variables in `.env`.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `APP_URL` | Yes | `http://localhost:3000` | 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 webhooks |
| `SMTP_HOST` | No | — | SMTP server hostname |
| `SMTP_PORT` | No | `587` | SMTP server port |
| `SMTP_USER` | No | — | SMTP username |
| `SMTP_PASSWORD` | No | — | SMTP password |
| `EMAIL_FROM` | No | `Roam Coffee <hello@localhost>` | Sender address for transactional email |
| `DEFAULT_CURRENCY` | No | `CAD` | ISO 4217 currency code |
| `LOG_LEVEL` | No | `info` | Logging verbosity |

Example development configuration:

```dotenv
DATABASE_URL=postgresql://localhost:5432/roam_coffee
APP_URL=http://localhost:3000
SESSION_SECRET=replace-with-a-long-random-value
STRIPE_SECRET_KEY=sk_test_example
STRIPE_WEBHOOK_SECRET=whsec_example
DEFAULT_CURRENCY=CAD
LOG_LEVEL=debug
```

Never commit production credentials or customer data to the repository. Use your deployment provider's secret manager for hosted environments.