gridpilot.gg/apps/website/README.md

# GridPilot Landing Page

Pre-launch landing page for GridPilot with email signup functionality.

## Features

- **Mode Switching**: Toggle between pre-launch (landing page only) and alpha (full platform) modes
- **Email Capture**: Collect email signups with validation and rate limiting
- **Production Ready**: Configured for Vercel deployment with KV storage

## Local Development Setup

### Prerequisites

- Node.js 20+
- npm or pnpm

### Installation

1. Clone the repository and navigate to the website directory:
```bash
cd apps/website
```

2. Install dependencies:
```bash
npm install
```

3. Copy environment variables:
```bash
cp .env.example .env.local
```

4. Configure environment variables in `.env.local`:
```bash
# Application Mode (pre-launch or alpha)
NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch

# Vercel KV (required for email signups)
KV_REST_API_URL=your_kv_rest_api_url_here
KV_REST_API_TOKEN=your_kv_rest_api_token_here

# Site URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

5. Start the development server:
```bash
npm run dev
```

Visit `http://localhost:3000` to see the landing page.

## Environment Variables

### Required Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `NEXT_PUBLIC_GRIDPILOT_MODE` | Application mode (server & client) | `pre-launch` or `alpha` |
| `KV_REST_API_URL` | Vercel KV REST API endpoint | From Vercel Dashboard |
| `KV_REST_API_TOKEN` | Vercel KV authentication token | From Vercel Dashboard |
| `NEXT_PUBLIC_SITE_URL` | Public site URL | `https://gridpilot.com` |

### Getting Vercel KV Credentials

1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
2. Navigate to **Storage** → **Create Database** → **KV**
3. Create a new KV database (free tier available)
4. Copy the `KV_REST_API_URL` and `KV_REST_API_TOKEN` from the database settings
5. Add them to your environment variables

## Mode Switching

The application supports two modes:

### Pre-Launch Mode (Default)

- Shows landing page with email capture
- Only `/` and `/api/signup` routes are accessible
- All other routes return 404

To activate:
```bash
NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch
```

### Post-Launch Mode

- Full platform access
- All routes are accessible
- Landing page is still available at `/`

To activate:
```bash
NEXT_PUBLIC_GRIDPILOT_MODE=alpha
```

## Email Signup API

### Endpoint

`POST /api/signup`

### Request Body

```json
{
  "email": "user@example.com"
}
```

### Response

**Success (200):**
```json
{
  "success": true,
  "message": "Successfully added to waitlist"
}
```

**Error (400/409/429/500):**
```json
{
  "error": "Error message here"
}
```

### Features

- **Validation**: Email format validation using Zod
- **Rate Limiting**: Max 5 submissions per IP per hour
- **Duplicate Prevention**: Prevents duplicate email submissions
- **Disposable Email Detection**: Blocks common disposable email services
- **Storage**: Emails stored in Vercel KV with timestamp and IP

### Accessing Submitted Emails

Submitted emails are stored in Vercel KV under the key `signups:emails`.

**Option 1: Vercel KV Dashboard**
1. Go to [Vercel Dashboard](https://vercel.com/dashboard)
2. Navigate to **Storage** → Your KV Database
3. Browse the `signups:emails` hash

**Option 2: CLI (with Vercel KV SDK)**
```typescript
import { kv } from '@vercel/kv';

// Get all signups
const signups = await kv.hgetall('signups:emails');
console.log(signups);
```

## Deployment

### Vercel Deployment (Recommended)

1. **Connect Repository**
   - Go to [Vercel Dashboard](https://vercel.com/new)
   - Import your Git repository
   - Select the `apps/website` directory as the root

2. **Configure Build Settings**
   - Framework Preset: Next.js
   - Build Command: `npm run build`
   - Output Directory: `.next`
   - Install Command: `npm install`

3. **Set Environment Variables**
   
   In Vercel Dashboard → Project Settings → Environment Variables:
   
   **Production:**
   ```
   NEXT_PUBLIC_GRIDPILOT_MODE=pre-launch
   KV_REST_API_URL=<your_vercel_kv_url>
   KV_REST_API_TOKEN=<your_vercel_kv_token>
   NEXT_PUBLIC_SITE_URL=https://gridpilot.com
   ```
   
   **Preview (optional):**
   Same as production, or use different values for testing

4. **Deploy**
   - Click "Deploy"
   - Vercel will automatically deploy on every push to main branch

### Switching to Post-Launch Mode

When ready to launch the full platform:

1. Go to Vercel Dashboard → Project Settings → Environment Variables
2. Update `NEXT_PUBLIC_GRIDPILOT_MODE` to `alpha`
3. Redeploy the application (automatic if you save changes)

### Custom Domain Setup

1. Go to Vercel Dashboard → Project Settings → Domains
2. Add your domain (e.g., `gridpilot.com`)
3. Follow DNS configuration instructions
4. Update `NEXT_PUBLIC_SITE_URL` environment variable to match your domain

## Build & Test

### Build for Production

```bash
npm run build
```

This creates an optimized production build in `.next/` directory.

### Start Production Server

```bash
npm run start
```

### Lint

```bash
npm run lint
```

## Testing Email Signup

### Test Locally

1. Start the development server
2. Navigate to `http://localhost:3000`
3. Scroll to "Want Early Access?" section
4. Enter an email and click "Join Waitlist"

### Test Scenarios

- ✅ Valid email submission
- ✅ Invalid email format rejection
- ✅ Duplicate email prevention
- ✅ Rate limiting (5 submissions per hour)
- ✅ Loading states
- ✅ Error messages
- ✅ Success confirmation

### Test Rate Limiting

Submit the same email 5 times within an hour. The 6th submission should return a 429 error.

## Troubleshooting

### Email Signup Not Working

**Issue**: API returns 500 error

**Solution**: Check that `KV_REST_API_URL` and `KV_REST_API_TOKEN` are correctly set in environment variables

### Mode Switching Not Working

**Issue**: Routes still show 404 in alpha mode

**Solution**:
1. Ensure `NEXT_PUBLIC_GRIDPILOT_MODE` is set to `alpha`
2. Restart the development server or redeploy to Vercel
3. Clear browser cache

### Rate Limiting Issues

**Issue**: Rate limiting not working in development

**Solution**: Vercel KV may need to be properly configured. Check KV dashboard for errors.

## Project Structure

```
apps/website/
├── app/
│   ├── api/
│   │   └── signup/
│   │       └── route.ts          # Email signup API endpoint
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx                  # Landing page
├── components/
│   ├── landing/
│   │   ├── EmailCapture.tsx      # Email signup form
│   │   ├── FAQ.tsx
│   │   ├── FeatureGrid.tsx
│   │   ├── Hero.tsx
│   │   └── RatingExplainer.tsx
│   ├── mockups/                  # UI mockups
│   ├── shared/
│   │   └── ModeGuard.tsx         # Client-side mode guard
│   └── ui/                       # Reusable UI components
├── lib/
│   ├── email-validation.ts       # Email validation utilities
│   ├── mode.ts                   # Mode detection utilities
│   └── rate-limit.ts             # Rate limiting utilities
├── middleware.ts                 # Next.js middleware for route protection
├── .env.example                  # Environment variables template
└── README.md                     # This file
```

## Tech Stack

- **Framework**: Next.js 15 (App Router)
- **Language**: TypeScript
- **Styling**: Tailwind CSS
- **Validation**: Zod
- **Storage**: Vercel KV (Redis)
- **Deployment**: Vercel

## Support

For issues or questions, contact the development team or open an issue in the repository.