SoftwareX/README.md

# BM Connect

A premium React + Vite landing page and community waitlist platform for a meme-coin launch. Features dynamic sections for problem/solution storytelling, tokenomics modals, roadmap visualization, and real-time waitlist tracking backed by Cloudflare D1 SQLite.

**Live:** https://react-example.white-glade-ab2c.workers.dev

## Overview

BM Connect delivers a high-trust launch narrative for community-driven web3 projects. The platform combines premium brand storytelling, conversion-focused messaging, and a production-ready waitlist system with real-time registration tracking and community stats.

## Key Features

- **Premium UI**: Dark, modern design with glassmorphic cards and smooth animations
- **Story-Driven Sections**: Hero, problem, solution, features, ecosystem, stats, roadmap
- **Interactive Modals**: Tokenomics breakdown and vision manifesto
- **Live Waitlist**: Real-time registration tracking with referral system and tier support
- **Community Stats**: Dynamic counter showing total registrations and funding progress
- **Responsive Design**: Mobile-first approach with Tailwind CSS
- **Type-Safe**: Full TypeScript throughout frontend and backend

## Tech Stack

**Frontend:**
- React 19 with TypeScript
- Vite (build tool & dev server)
- Tailwind CSS (styling)
- Framer Motion (animations)

**Backend:**
- Cloudflare Workers (serverless API)
- Cloudflare D1 (SQLite database)

**Infrastructure:**
- Firebase (optional: for app data beyond waitlist)
- Wrangler CLI (deployment & management)

## Project Structure

`
.
├── src/                                # React frontend
│   ├── components/
│   │   ├── layout/                    # Navbar, Footer
│   │   ├── sections/                  # Landing page sections
│   │   └── ui/                        # Reusable components (Button, Badge, etc.)
│   ├── data/                          # Static content (features, roadmap, tokenomics, FAQ)
│   ├── lib/
│   │   ├── firebase.ts               # Firebase configuration
│   │   ├── waitlist.ts               # Waitlist API client
│   │   └── utils.ts
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── worker/                            # Cloudflare Worker (backend API)
│   ├── src/
│   │   └── index.ts                  # Waitlist registration endpoints
│   └── wrangler.toml                 # Worker configuration & D1 binding
├── dist/                             # Production build
├── vite.config.ts
├── tsconfig.json
├── wrangler.jsonc                    # Build configuration
├── package.json
├── Dockerfile                        # Container build (optional)
└── README.md
`

## Getting Started

### Prerequisites

- Node.js 18+
- npm or yarn
- Cloudflare account (for deployment)

### Local Development

1. **Install dependencies:**
   `ash
   npm install
   `

2. **Configure environment variables:**
   `ash
   cp .env.example .env
   `
   
   Required variables:
   - VITE_FIREBASE_API_KEY - Firebase API key
   - VITE_FIREBASE_AUTH_DOMAIN - Firebase auth domain
   - VITE_FIREBASE_PROJECT_ID - Firebase project ID
   - VITE_WAITLIST_API_URL - Waitlist API endpoint (local: /api, production: Worker URL)
   - GEMINI_API_KEY - Google GenAI API key (optional)

3. **Start development server:**
   `ash
   npm run dev
   `
   The app runs on http://localhost:5173 (Vite default)

4. **Build for production:**
   `ash
   npm run build
   `

5. **Type checking:**
   `ash
   npm run lint
   `

## Database: Cloudflare D1

The waitlist backend is powered by **Cloudflare D1**, a serverless SQLite database. Configuration details:

- **Database name:** bm_connect_db
- **Database ID:** 5cf8ba8c-fe38-4db4-bf95-aa8fb8c09892
- **Binding:** DB (available in Worker via env.DB)
- **Tables:**
  - waitlist_entries - User registrations (email, name, tier, referral code, etc.)
  - waitlist_stats - Global statistics (total registered, funded amount)

### Worker API Endpoints

The Cloudflare Worker in worker/src/index.ts provides these endpoints:

- **POST /api/waitlist/register** - Register a new email with optional metadata
- **GET /api/waitlist/stats** - Get global registration and funding stats
- **POST /api/waitlist/verify** - Verify referral codes and registration status

## Deployment

### Deploy to Cloudflare Workers

1. **Ensure wrangler.toml is configured with D1 database:**
   `	oml
   [[d1_databases]]
   binding = "DB"
   database_name = "bm_connect_db"
   database_id = "5cf8ba8c-fe38-4db4-bf95-aa8fb8c09892"
   `

2. **Build and deploy:**
   `ash
   npm run build
   npx wrangler deploy
   `

3. **Verify deployment:**
   - Frontend: https://react-example.white-glade-ab2c.workers.dev
   - Worker API: https://react-example.white-glade-ab2c.workers.dev/api/waitlist/stats

### Environment Setup

For production, configure these environment variables in your Cloudflare dashboard:
- Worker secrets (via wrangler secret put)
- D1 database bindings (configured in wrangler.toml)

## Customization

### Content

Static content is managed in src/data/:
- features.ts - Feature cards and descriptions
- roadmap.ts - Milestone timeline
- tokenomics.ts - Token distribution and economics
- faq.ts - Frequently asked questions
- ecosystem.ts - Partner/ecosystem information

### Styling

- Global styles: src/index.css
- Tailwind config: tailwind.config.js (if present)
- Component-level: Tailwind classes in JSX

### API Integration

Update VITE_WAITLIST_API_URL to point to your deployed Worker:
- Local development: /api (proxied via Vite dev server)
- Production: https://your-worker.workers.dev

## Community & Support

For questions or issues, refer to:
- **Firebase Docs**: https://firebase.google.com/docs
- **Cloudflare Workers Docs**: https://developers.cloudflare.com/workers/
- **Vite Docs**: https://vitejs.dev/