tapdotfun

A production-ready Solana waitlist application with Twitter OAuth, wallet verification, and referral system. Built with a modern, end-to-end type-safe stack.

Features

• 3-Step Onboarding Flow

  • Connect X (Twitter) via OAuth 2.0
  • Connect Solana Wallet (Phantom, Solflare, etc.)
  • Sign message for wallet verification (no gas fees)

• Referral System

  • Case-insensitive referral links (?ref=username)
  • Real-time leaderboard with top referrers
  • Automatic referral count tracking

• Modern Stack

  • End-to-end type safety with TypeScript, Zod, and oRPC
  • Monorepo architecture with Turborepo
  • PostgreSQL with Drizzle ORM

• 8-bit Retro Aesthetic

  • Pixelated UI components
  • Press Start 2P font
  • CRT scanlines and neon glow effects

Documentation

PLAYBOOK.md - A complete guide to shipping a Solana waitlist in under an hour. Covers brand asset gathering, UI library selection, font choices, wallet verification, referral logic, deployment, and lessons learned. Includes recommendations for Claude Code skills authored by domain experts (copywriting, frontend design, CRO, etc.).

Tech Stack

Layer	Technology
Frontend	Next.js 16 + React 19
Backend API	oRPC (type-safe RPC)
Database	PostgreSQL + Drizzle ORM
Authentication	Better Auth (Twitter OAuth)
Wallet	Jupiter Unified Wallet Kit
UI	shadcn/ui + TailwindCSS 4
State	TanStack Query
Monorepo	Turborepo + Bun

Project Structure

tapdotfun/
├── apps/
│   └── web/                    # Next.js fullstack app
│       ├── src/
│       │   ├── app/            # App router pages
│       │   ├── components/     # React components
│       │   ├── lib/            # Auth client
│       │   └── utils/          # oRPC client
│       └── public/             # Static assets
│
├── packages/
│   ├── api/                    # oRPC routers & procedures
│   ├── auth/                   # Better Auth configuration
│   ├── db/                     # Drizzle schema & migrations
│   ├── env/                    # Environment validation
│   └── config/                 # Shared TypeScript config

Getting Started

Prerequisites

• Bun 1.3+
• PostgreSQL 15+ (or Docker)
• Twitter Developer Account (for OAuth)

Installation

1. Clone the repository:

git clone https://github.com/SivaramPg/tapdotfun-waitlist-referral-system.git
cd tapdotfun-waitlist-referral-system

2. Install dependencies:

bun install

3. Set up environment variables:

cp apps/web/.env.example apps/web/.env

4. Configure your .env file:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/tapdotfun

# Better Auth
BETTER_AUTH_SECRET=your-minimum-32-character-secret-key
BETTER_AUTH_URL=http://localhost:3001
CORS_ORIGIN=http://localhost:3001

# Twitter OAuth
TWITTER_CLIENT_ID=your_twitter_client_id
TWITTER_CLIENT_SECRET=your_twitter_client_secret

# Environment
NODE_ENV=development

Database Setup

Option 1: Using Docker (recommended)

cd packages/db
docker-compose up -d

Option 2: Using existing PostgreSQL

Update DATABASE_URL in your .env file.

Then push the schema:

bun run db:push

Running the App

Start the development server:

bun run dev

Open http://localhost:3001 in your browser.

Available Scripts

Command	Description
bun run dev	Start all apps in development mode
bun run build	Build all applications
bun run check-types	TypeScript type checking
bun run check	Run Oxlint and Oxfmt
bun run db:push	Push schema changes to database
bun run db:studio	Open Drizzle Studio UI
bun run db:migrate	Run database migrations

API Endpoints

All endpoints are type-safe via oRPC. OpenAPI docs available at /api/rpc/api-reference.

Endpoint	Auth	Description
healthCheck	Public	Server health check
getLeaderboard	Public	Top 10 referrers
joinWaitlist	Protected	Create waitlist entry
updateWallet	Protected	Store wallet + signature
checkWaitlist	Protected	Get user's waitlist status
getReferralCount	Protected	Get user's referral stats

Twitter OAuth Setup

1. Go to Twitter Developer Portal
2. Create a new project and app
3. Enable OAuth 2.0 with:
   • Type: Web App
   • Callback URL: http://localhost:3001/api/auth/callback/twitter
4. Copy Client ID and Client Secret to your .env

Deployment

Environment Variables

Ensure these are set in your deployment platform:

DATABASE_URL
BETTER_AUTH_SECRET
BETTER_AUTH_URL
CORS_ORIGIN
TWITTER_CLIENT_ID
TWITTER_CLIENT_SECRET
NODE_ENV=production

Vercel

This project is optimized for Vercel deployment:

1. Connect your repository to Vercel
2. Set environment variables in project settings
3. Deploy

The turbo.json is pre-configured with all required env vars for the build.

Customization

Rebranding

1. Update logo in apps/web/src/components/tap-logo.tsx
2. Modify colors in apps/web/src/app/globals.css
3. Replace favicon and OG image in apps/web/public/

Adding New API Endpoints

1. Define procedures in packages/api/src/routers/index.ts
2. Use publicProcedure or protectedProcedure based on auth requirements
3. Add Zod schemas for input validation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Author

Built by @SivaramPg. Available for freelance Solana/Web3 projects. DMs open.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Better-T-Stack
• UI components from shadcn/ui
• Wallet integration via Jupiter