BossDuck Token - Meme Crypto Website

A full-stack Next.js application for managing and displaying a Solana-based meme token with wallet integration, balance tracking, and admin features.

Features

• 🔗 Solana Wallet Connection - Connect with Phantom, Solflare, and other Solana wallets
• 💰 Token Balance Display - View your token and SOL balance in real-time with server-side rate limiting
• 🚦 Rate Limiting Queue - Server-side request queue manages Solana RPC calls (configurable via admin panel)
• 🔐 Admin Panel - Restricted admin features for managing token properties
• 🗄️ PostgreSQL Database - PostgreSQL 17 database (container for dev, Cloud SQL for production)
• 🐳 Docker Support - Ready for deployment with Docker Compose
• ☁️ Google Cloud Ready - One-command Cloud Run deployment with Cloud SQL

Prerequisites

• Node.js 20+
• npm or yarn
• PostgreSQL 17 (or Docker for local development)
• Solana wallet (Phantom, Solflare, etc.)

Setup

1. Clone the repository

   git clone <your-repo-url>
   cd token-meme

2. Install dependencies

   npm install

3. Set up environment variables

   Copy .env.example to .env and fill in your values:

   cp .env.example .env

   Required environment variables:

   • DATABASE_URL - PostgreSQL connection string (or use POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB)
   • SOLANA_RPC_ENDPOINT - Solana RPC endpoint URL (e.g., drpc endpoint: https://lb.drpc.live/solana/YOUR_API_KEY)
   • NEXT_PUBLIC_SOLANA_NETWORK - Solana network (devnet or mainnet-beta)
   • ADMIN_WALLET_ADDRESS - Wallet address that has admin access

   Note: Token mint address is configured via the admin panel and stored in the database, not via environment variables.

4. Set up PostgreSQL database

   If using Docker Compose, the database will be automatically set up:

   docker-compose -f docker-compose.dev.yml up

   The database schema will be automatically migrated on first startup using versioned migrations. No manual setup required!

5. Run the development server

   npm run dev

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

Docker Deployment

Development with Docker Compose

For development with hot reload (includes PostgreSQL 17):

# Make sure you have a .env file with all required variables
docker-compose -f docker-compose.dev.yml up

This will start both the PostgreSQL database and the Next.js app. The database schema will be automatically migrated on first startup using MD5 checksum verification - no manual setup required!

Or run in detached mode:

docker-compose up -d

To stop:

docker-compose down

To rebuild after dependency changes:

docker-compose up --build

Production Docker Build

Build the Docker image:

docker build -t token-meme .

Run locally with Docker:

docker run -p 3000:3000 --env-file .env token-meme

Deploy to Google Cloud (Production)

Quick Deployment:

Deploy to Compute Engine VM with Cloud SQL PostgreSQL 17:

cd deployment/gcp
.\deploy.ps1

Manual Deployment:

See deployment/gcp/README.md for detailed step-by-step instructions.

The deployment includes:

• Compute Engine VM running the application in Docker
• Cloud SQL PostgreSQL 17 managed database
• Automatic Docker image building
• Environment variable configuration
• Firewall rules setup

Project Structure

token-meme/
├── app/                    # Next.js app directory
│   ├── api/
│   │   ├── solana/
│   │   │   └── balances/  # Combined SOL + token balance endpoint
│   │   ├── admin/         # Admin configuration endpoints
│   │   └── config/        # Public configuration endpoints
│   ├── layout.tsx         # Root layout with wallet providers
│   ├── page.tsx           # Main page
│   ├── my-duck/           # User balance page
│   └── globals.css        # Global styles
├── components/            # React components
│   ├── AdminPanel.tsx     # Admin configuration panel
│   ├── BalanceDisplay.tsx # Token balance display
├── lib/                   # Utility libraries
│   ├── admin.ts          # Admin functions
│   ├── db.ts             # PostgreSQL database connection
│   ├── solana.ts         # Solana blockchain integration
│   ├── solanaQueue.ts    # Server-side RPC request queue with rate limiting
│   └── wallet.ts         # Wallet adapter setup
├── migrations/            # Database migration files
│   ├── 001_initial_schema.sql  # Versioned migration files
│   └── migrations.json    # Migration catalog
├── public/                # Static assets
│   └── images/          # Images (logos, banners, icons)
│       ├── logos/      # Brand and token logos
│       ├── banners/    # Marketing banners
│       └── icons/      # UI icons
├── deployment/            # Production deployment files
│   └── gcp/              # Google Cloud Platform deployment
└── Dockerfile            # Docker configuration

Admin Features

Admin features are restricted to wallets specified in:

1. ADMIN_WALLET_ADDRESS environment variable
2. Wallets added to the admin_wallets table in PostgreSQL

Admin users can:

• Update token configuration (token address, social links)
• Configure rate limiting
• Manage application settings stored in the database

Rate Limiting

The application uses a server-side queue system to manage Solana RPC requests:

• Configurable Rate Limit: Rate limits are configurable via admin panel
• Queue Management: Server-side queue prevents rate limit violations
• Client Timeout: Requests have a timeout to prevent hanging
• Error Handling: Returns 503 (Service Unavailable) when queue is full, rate limits are exceeded, or RPC errors occur
• Dynamic Configuration: Rate limit can be adjusted in real-time via the admin panel without code changes

See RATE_LIMITING.md for detailed information.

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes*
POSTGRES_USER	PostgreSQL username (if not using DATABASE_URL)	No*
POSTGRES_PASSWORD	PostgreSQL password (if not using DATABASE_URL)	No*
POSTGRES_DB	PostgreSQL database name (if not using DATABASE_URL)	No*
SOLANA_RPC_ENDPOINT	Solana RPC endpoint URL (e.g., https://lb.drpc.live/solana/YOUR_API_KEY)	Yes
NEXT_PUBLIC_SOLANA_NETWORK	devnet or mainnet-beta	Yes
ADMIN_WALLET_ADDRESS	Admin wallet address	Yes

*Either use DATABASE_URL or the individual POSTGRES_* variables

License

See LICENSE file for details.