# Market Basket

Market Basket is a local farmers-market marketplace that connects shoppers with nearby growers, bakers, makers, and food producers. Customers can browse seasonal products, place orders ahead of market day, and choose pickup or local delivery where available. Vendors can manage inventory, publish pickup schedules, and track orders from a simple dashboard.

## Features

### For shoppers

- Browse products by market, vendor, category, and availability
- Search for seasonal produce and locally made goods
- View vendor profiles, growing practices, and allergen information
- Add products from multiple vendors to one cart
- Select an available pickup window or local delivery option
- Pay securely online and receive order-status notifications
- Review previous orders and quickly reorder regular items

### For vendors

- Create a storefront with contact and production details
- Manage products, prices, photos, and limited inventory
- Configure market locations and fulfillment windows
- Receive and update customer orders
- Export packing lists and sales reports
- Mark products as seasonal, organic, vegan, or gluten-free

### For market operators

- Approve and manage participating vendors
- Configure market dates, locations, fees, and service areas
- Review marketplace activity and order totals
- Publish announcements and schedule changes

## Requirements

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

## Installation

Clone the repository and install dependencies:

```bash
git clone https://github.com/example/market-basket.git
cd market-basket
npm install
```

Create a local environment file:

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

Update `.env` with your database, Redis, payment provider, and email credentials.

Create the database schema and seed development data:

```bash
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`.

The seed script creates sample shopper, vendor, and market-operator accounts. Their credentials are printed to the terminal after seeding.

## Usage

### Run locally

```bash
npm run dev
```

### Run tests

```bash
npm test
```

Run end-to-end tests:

```bash
npm run test:e2e
```

### Check code quality

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

### Create a production build

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

### Database commands

Create a migration after changing the schema:

```bash
npm run db:migration:create
```

Apply pending migrations:

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

Open the database administration interface:

```bash
npm run db:studio
```

## Configuration

Market Basket is configured through environment variables.

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `APP_URL` | Yes | `http://localhost:3000` | Public application URL |
| `NODE_ENV` | No | `development` | Runtime environment |
| `PORT` | No | `3000` | HTTP server port |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `REDIS_URL` | Yes | — | Redis connection string |
| `SESSION_SECRET` | Yes | — | Secret used to sign sessions |
| `STRIPE_SECRET_KEY` | Yes | — | Stripe server-side API key |
| `STRIPE_WEBHOOK_SECRET` | Yes | — | Stripe webhook signing secret |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Yes | — | Stripe browser publishable key |
| `EMAIL_FROM` | Yes | — | Sender address for transactional email |
| `SMTP_HOST` | Yes | — | SMTP server hostname |
| `SMTP_PORT` | No | `587` | SMTP server port |
| `SMTP_USER` | Yes | — | SMTP username |
| `SMTP_PASSWORD` | Yes | — | SMTP password |
| `S3_BUCKET` | No | — | Object-storage bucket for product images |
| `S3_REGION` | No | — | Object-storage region |
| `S3_ACCESS_KEY_ID` | No | — | Object-storage access key |
| `S3_SECRET_ACCESS_KEY` | No | — | Object-storage secret key |
| `DELIVERY_RADIUS_KM` | No | `15` | Maximum default delivery radius |
| `ORDER_CUTOFF_HOURS` | No | `12` | Hours before fulfillment when ordering closes |

Use long, randomly generated values for secrets in production. Never commit `.env` files or production credentials.

## Webhooks

Payment events are received at:

```text
POST /api/webhooks/stripe
```

For local development, forward Stripe events to the application:

```bash
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```

Copy the generated webhook signing secret into `STRIPE_WEBHOOK_SECRET`.

## Project Structure

```text
src/
├── app/          Application routes and pages
├── components/   Shared interface components
├── lib/          Database, payments, email, and utilities
├── modules/      Marketplace domain modules
└── workers/      Background jobs and notifications

prisma/           Database schema, migrations, and seed data
public/           Static assets
tests/            Integration and end-to-end tests
```

## License

This project is licensed under the MIT License.