# BeanBox

BeanBox is a coffee subscription platform for managing recurring coffee deliveries, customer preferences, roaster inventory, and billing workflows. It is built for specialty coffee startups that need flexible subscription plans, grind preference tracking, and shipment scheduling.

## Overview

BeanBox helps customers subscribe to curated coffee deliveries while giving operators tools to manage products, subscriptions, orders, and fulfillment. The app supports weekly, biweekly, and monthly plans, personalized roast preferences, and configurable shipping rules.

## Features

- Customer subscription signup and account management
- Roast, origin, grind, and bag-size preferences
- Recurring billing integration
- Subscription pause, skip, resume, and cancel flows
- Product catalog for blends and single-origin coffees
- Fulfillment dashboard for upcoming shipments
- Inventory-aware order generation
- Email notifications for billing, shipment, and subscription changes
- Admin configuration for shipping regions, taxes, and plan rules

## Install

Clone the repository:

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

Install dependencies:

```bash
npm install
```

Copy the environment file:

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

Run database migrations:

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

Seed sample products and plans:

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

Start the development server:

```bash
npm run dev
```

## Usage

Open the app locally:

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

Create an admin user:

```bash
npm run create-admin
```

Common commands:

```bash
npm run dev        # Start the local development server
npm run build      # Build the production bundle
npm run start      # Start the production server
npm run test       # Run the test suite
npm run lint       # Run lint checks
npm run db:migrate # Apply database migrations
```

Example subscription flow:

1. Customer selects a subscription plan.
2. Customer chooses roast level, grind type, and delivery frequency.
3. Payment method is saved through the billing provider.
4. The system generates upcoming orders based on the subscription schedule.
5. Admin users review and fulfill shipments from the dashboard.

## Configuration

Configuration is managed through environment variables.

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

DATABASE_URL=postgres://beanbox:beanbox@localhost:5432/beanbox

SESSION_SECRET=replace-with-a-secure-secret

STRIPE_SECRET_KEY=sk_test_replace_me
STRIPE_WEBHOOK_SECRET=whsec_replace_me

MAIL_PROVIDER=smtp
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM="BeanBox <hello@beanbox.local>"

DEFAULT_CURRENCY=USD
DEFAULT_SHIPPING_COUNTRY=US
ORDER_CUTOFF_DAY=Wednesday
FULFILLMENT_LEAD_DAYS=2
```

Important settings:

- `DATABASE_URL`: PostgreSQL connection string.
- `SESSION_SECRET`: Secret used to sign user sessions.
- `STRIPE_SECRET_KEY`: Billing provider API key.
- `STRIPE_WEBHOOK_SECRET`: Secret used to verify billing webhook events.
- `SMTP_FROM`: Sender address for transactional emails.
- `ORDER_CUTOFF_DAY`: Last day subscriptions can change before fulfillment.
- `FULFILLMENT_LEAD_DAYS`: Number of days needed to prepare shipments.

## License

MIT