# RoastCycle

RoastCycle is a coffee subscription platform for independent roasters and subscription-first coffee brands. It helps customers discover fresh beans, customize delivery schedules, manage preferences, and pause or update subscriptions without contacting support.

## Overview

RoastCycle provides the core application layer for a direct-to-consumer coffee subscription startup. The project includes customer onboarding, subscription management, product catalog support, checkout integration, and operational workflows for fulfillment teams.

The application is designed for small teams that need a practical foundation for selling recurring coffee subscriptions online.

## Features

- Customer signup and account management
- Coffee preference quiz for roast level, grind type, brew method, and flavor profile
- Flexible subscription plans: weekly, biweekly, monthly
- Product catalog for single-origin, blends, decaf, and seasonal releases
- Subscription pause, skip, cancel, and address update flows
- Stripe-ready checkout and billing integration
- Admin-friendly order and fulfillment status tracking
- Email notification hooks for renewals, shipments, and failed payments
- Environment-based configuration for local, staging, and production deployments

## Install

Clone the repository:

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

Install dependencies:

```bash
npm install
```

Create a local 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

Run the app locally:

```bash
npm run dev
```

Run tests:

```bash
npm test
```

Build for production:

```bash
npm run build
```

Start the production server:

```bash
npm start
```

Example customer flow:

1. Create an account.
2. Complete the coffee preference quiz.
3. Choose a subscription frequency.
4. Add shipping and billing details.
5. Manage upcoming deliveries from the customer dashboard.

Example admin flow:

1. Sign in with an admin account.
2. Review active subscriptions.
3. Export upcoming fulfillment orders.
4. Update shipment status after roasting and packing.
5. Monitor failed payments or paused subscriptions.

## Configuration

RoastCycle is configured with environment variables. Copy `.env.example` to `.env` and update the values for your environment.

```env
APP_URL=http://localhost:3000
NODE_ENV=development

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/roastcycle

STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_key

EMAIL_FROM=orders@roastcycle.example
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your_smtp_user
SMTP_PASSWORD=your_smtp_password

FULFILLMENT_EXPORT_TIMEZONE=America/New_York
DEFAULT_SUBSCRIPTION_INTERVAL=monthly
```

Common configuration options:

| Variable | Description |
| --- | --- |
| `APP_URL` | Public URL used for redirects, emails, and webhook callbacks. |
| `DATABASE_URL` | PostgreSQL connection string. |
| `STRIPE_SECRET_KEY` | Secret key used for Stripe payments and subscription billing. |
| `STRIPE_WEBHOOK_SECRET` | Secret used to verify incoming Stripe webhook events. |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Public Stripe key used by the checkout UI. |
| `EMAIL_FROM` | Sender address for transactional emails. |
| `SMTP_HOST` | SMTP server hostname. |
| `SMTP_PORT` | SMTP server port. |
| `SMTP_USER` | SMTP username. |
| `SMTP_PASSWORD` | SMTP password. |
| `FULFILLMENT_EXPORT_TIMEZONE` | Timezone used when generating roasting and shipping schedules. |
| `DEFAULT_SUBSCRIPTION_INTERVAL` | Default delivery cadence shown during onboarding. |