> ## Documentation Index
> Fetch the complete documentation index at: https://whiskypeak.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Guide

> Technical guide for WhiskyPay platform development

# WhiskyPay Development Guide

This guide provides comprehensive information for developers working on the WhiskyPay platform. It covers environment setup, development workflows, and system architecture.

## System Architecture

WhiskyPay consists of three main components that work together:

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    React App    │     │  Payment Gateway │     │     Workers     │
│                 │────▶│  (Next.js API)   │────▶│   (BullMQ)      │
│  SDK            │     │                 │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Solana Wallet  │     │    Supabase     │     │      Redis      │
│                 │     │    Database     │     │     Queue       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

1. **SDK**: React components and utility functions for merchants to integrate
2. **Payment Gateway**: Backend API and database for processing payments
3. **Workers**: Background processing for webhooks and emails

## Development Environment Setup

### Prerequisites

* Node.js v16+
* npm or yarn
* Git
* Redis (for local development)
* Supabase account (or local Supabase setup)
* Solana CLI tools (optional but recommended)

### Clone Repositories

```bash theme={null}
# Clone all three repositories
https://github.com/weknowyourgame/WhiskyPay sdk workers & payment-gateway
```

### SDK Setup

```bash theme={null}
cd sdk
npm install
npm run build
```

To develop the SDK with local linking:

```bash theme={null}
# In the SDK directory
npm link

# In your test application
npm link @whisky-peak/whisky-pay-sdk
```

### Payment Gateway Setup

```bash theme={null}
cd payment-gateway
npm install

# Create .env file with Supabase credentials
cp .env.example .env
# Edit .env with your actual credentials

# Start development server
npm run dev
```

### Workers Setup

```bash theme={null}
cd workers
npm install

# Create .env file with Redis credentials
cp .env.example .env
# Edit .env with your actual credentials

# Start workers in development mode
npm run dev
```

## Local Development Workflow

For a complete local development environment, run all three components:

1. Start the Payment Gateway: `cd payment-gateway && npm run dev`
2. Start the Workers: `cd workers && npm run dev`
3. Start your test application that uses the SDK

### Testing the End-to-End Flow

1. Create a test merchant in your local database
2. Use the SDK in a test app to create a payment session
3. Complete a payment using a Solana wallet (Phantom in dev mode)
4. Verify webhook callbacks and email notifications

## Project Structure

### SDK Structure

```
sdk/
├── src/
│   ├── index.ts             # Main exports
│   ├── PaymentModal.tsx     # Payment UI component
│   ├── createSession.ts     # Create payment session
│   ├── fetchSession.ts      # Fetch session details
│   ├── verifyPayment.tsx    # Verify payment transactions
│   └── Tokens.ts            # Token definitions
├── dist/                    # Compiled code
├── package.json
└── tsconfig.json
```

### Payment Gateway Structure

```
payment-gateway/
├── app/                     # Next.js app directory
│   ├── api/                 # API routes
│   │   ├── session/         # Session API
│   │   ├── verify/          # Verification API
│   │   └── webhook/         # Webhook API
│   ├── components/          # React components
│   ├── lib/                 # Utility functions
│   ├── models/              # Database models
│   └── page.tsx             # Main landing page
├── .env                     # Environment variables
├── middleware.ts            # Next.js middleware
└── package.json
```

### Workers Structure

```
workers/
├── index.ts                 # Main worker file
├── .env                     # Environment variables
└── package.json
```

## Data Flow

### Payment Process Flow

1. **Session Creation**:
   * Merchant creates a session via SDK
   * Gateway generates a session ID and stores details in Supabase
   * Session details returned to frontend

2. **Payment Execution**:
   * Customer connects their wallet via the PaymentModal component
   * SDK fetches session details from the Gateway
   * Customer selects token and makes payment
   * Transaction is submitted to Solana blockchain

3. **Payment Verification**:
   * SDK sends transaction signature to Gateway for verification
   * Gateway verifies the transaction on Solana
   * On success, Gateway updates the database and queues jobs

4. **Notifications**:
   * Workers process webhook notification to merchant
   * Workers send confirmation emails

## Deployment Guidelines

### SDK Deployment

```bash theme={null}
# Build the package
npm run build

# Update version in package.json
npm version patch

# Publish to npm
npm publish
```

### Payment Gateway Deployment

The Payment Gateway is a Next.js application that can be deployed to Vercel, Netlify, or any Node.js hosting:

```bash theme={null}
# Build for production
npm run build

# For Vercel
vercel deploy

# For custom hosting
npm start
```

### Workers Deployment

Workers should be deployed as a separate service:

```bash theme={null}
# Build for production
npm run build

# Start in production mode
npm start
```

For production, use PM2 or Docker as described in the [Workers Setup](/workers/setup) guide.

## Debugging Tips

### SDK Debugging

* Set `localStorage.debug = 'whiskypay:*'` in the browser console to enable debug logging
* Use the browser developer tools to inspect network requests and responses
* Check the console for detailed error messages

### Payment Gateway Debugging

* Check the Next.js server logs for API errors
* Verify Supabase connection and queries
* Use the `/api/debug` endpoint (in development) to check system status

### Workers Debugging

* Check Redis connection status
* Verify job queues are being populated
* Examine worker logs for processing errors
* Use BullMQ's API to inspect job status

## Contributing Guidelines

1. **Branch Management**:
   * `main`: Production-ready code
   * `develop`: Integration branch for features
   * `feature/[name]`: Individual features

2. **Pull Request Process**:
   * Create feature branches from `develop`
   * Submit PRs back to `develop`
   * Ensure tests pass
   * Follow code style guidelines

3. **Versioning**:
   * Follow semantic versioning (MAJOR.MINOR.PATCH)
   * Document breaking changes in CHANGELOG.md

## Resources

* [Solana Documentation](https://docs.solana.com/)
* [Next.js Documentation](https://nextjs.org/docs)
* [Supabase Documentation](https://supabase.io/docs)
* [BullMQ Documentation](https://docs.bullmq.io/)
* [React Documentation](https://reactjs.org/docs)