# FreshStall

FreshStall is a farmers-market marketplace for connecting local growers, bakers, makers, and shoppers. Vendors can list seasonal products, manage inventory, and accept preorders, while shoppers can browse nearby markets, reserve items, and choose pickup windows.

## Overview

FreshStall is designed for community markets that need a lightweight online ordering layer without replacing the in-person market experience. It supports vendor storefronts, product availability by market day, shopper carts, pickup scheduling, and basic market administration.

## Features

- Vendor profiles with farm descriptions, photos, and contact details
- Product listings with categories, prices, units, allergens, and seasonal availability
- Inventory tracking by market date and pickup location
- Shopper search and filtering by vendor, category, dietary tags, and availability
- Cart and checkout flow for market pickup orders
- Order status management for vendors and market staff
- Market schedule and pickup-window configuration
- Admin tools for approving vendors and managing featured listings
- Email notifications for order confirmations and vendor updates

## Install

### Requirements

- Node.js 20+
- npm 10+
- PostgreSQL 15+
- Stripe account, optional for payments
- SMTP provider, optional for email notifications

### Setup

```bash
git clone https://github.com/example/freshstall.git
cd freshstall
npm install
```

Create an environment file:

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

Update `.env` with your local database and service credentials.

Run database migrations and seed sample data:

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

Start the development server:

```bash
npm run dev
```

The app will be available at:

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

## Usage

### Shopper Flow

1. Choose a market location and date.
2. Browse available products from local vendors.
3. Add items to the cart.
4. Select a pickup window.
5. Place the order and receive a confirmation email.

### Vendor Flow

1. Sign in to the vendor dashboard.
2. Create or update product listings.
3. Set available inventory for upcoming market dates.
4. Review incoming orders.
5. Mark orders as packed, ready, or completed.

### Admin Flow

1. Approve new vendor applications.
2. Configure market locations, dates, and pickup windows.
3. Feature seasonal products or vendors.
4. Review marketplace activity and order totals.

## Configuration

FreshStall is configured with environment variables.

```env
APP_URL=http://localhost:3000
DATABASE_URL=postgres://freshstall:freshstall@localhost:5432/freshstall

SESSION_SECRET=change-me

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
EMAIL_FROM=orders@freshstall.local

DEFAULT_MARKET_TIMEZONE=America/New_York
ORDER_CUTOFF_HOURS=12
MAX_PICKUP_WINDOW_CAPACITY=40
```

### Key Settings

| Variable | Description | Required |
| --- | --- | --- |
| `APP_URL` | Public URL for links in emails and redirects | Yes |
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `SESSION_SECRET` | Secret used to sign user sessions | Yes |
| `STRIPE_SECRET_KEY` | Enables payment collection through Stripe | No |
| `SMTP_HOST` | Enables transactional email delivery | No |
| `DEFAULT_MARKET_TIMEZONE` | Timezone used for market schedules | Yes |
| `ORDER_CUTOFF_HOURS` | Number of hours before pickup when ordering closes | Yes |
| `MAX_PICKUP_WINDOW_CAPACITY` | Default order limit per pickup window | Yes |

## Scripts

```bash
npm run dev          # Start local development server
npm run build        # Build production assets
npm run start        # Start production server
npm run lint         # Run lint checks
npm run test         # Run test suite
npm run db:migrate   # Apply database migrations
npm run db:seed      # Load sample market data
```

## License

MIT