# RoastLoop

RoastLoop is a coffee subscription platform for specialty roasters. It lets customers build recurring coffee plans, manage delivery frequency, pause shipments, and receive personalized roast recommendations based on taste preferences.

## Overview

RoastLoop provides the storefront, subscription logic, customer dashboard, and admin tools needed to run a recurring coffee business. The app is designed for small to mid-sized roasters that want flexible subscriptions without losing control over inventory, fulfillment windows, and customer experience.

## Features

- Customer coffee subscription plans
- Weekly, biweekly, and monthly delivery schedules
- Grind type, roast level, and flavor preference selection
- Subscription pause, skip, resume, and cancellation flows
- Admin product and inventory management
- Upcoming shipment preview
- Stripe billing integration
- Transactional email notifications
- Basic recommendation engine for coffee matching

## Install

Clone the repository:

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

Install dependencies:

```bash
npm install
```

Create an environment file:

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

Run database migrations:

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

Start the development server:

```bash
npm run dev
```

The app will be available at:

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

## Usage

Start the local app and create an admin account:

```bash
npm run dev
```

Seed sample coffees, customers, and subscriptions:

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

Run tests:

```bash
npm test
```

Build for production:

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

Typical customer flow:

1. Browse available coffees.
2. Choose a subscription size and delivery frequency.
3. Select grind type and taste preferences.
4. Enter shipping and billing details.
5. Manage upcoming shipments from the account dashboard.

Typical admin flow:

1. Add or update coffee products.
2. Set inventory and roast dates.
3. Review upcoming subscription orders.
4. Export fulfillment batches.
5. Monitor paused, failed, and canceled subscriptions.

## Configuration

RoastLoop uses environment variables for local and production configuration.

| Variable | Description | Example |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/roastloop` |
| `NEXT_PUBLIC_APP_URL` | Public app URL | `http://localhost:3000` |
| `STRIPE_SECRET_KEY` | Stripe server-side API key | `sk_test_...` |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | `whsec_...` |
| `EMAIL_FROM` | Sender address for transactional emails | `orders@roastloop.com` |
| `SMTP_HOST` | SMTP server hostname | `smtp.example.com` |
| `SMTP_PORT` | SMTP server port | `587` |
| `SMTP_USER` | SMTP username | `roastloop` |
| `SMTP_PASSWORD` | SMTP password | `password` |
| `FULFILLMENT_CUTOFF_DAY` | Last weekday for the next roast batch | `3` |

Example `.env` file:

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

STRIPE_SECRET_KEY=sk_test_replace_me
STRIPE_WEBHOOK_SECRET=whsec_replace_me

EMAIL_FROM=orders@roastloop.com
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=roastloop
SMTP_PASSWORD=replace_me

FULFILLMENT_CUTOFF_DAY=3
```

## License

MIT