PixelBoard 🟣

The Modern Million Pixel Billboard — 2026 Edition

Own a piece of the internet. 1,000,000 pixels. One URL. Forever.

---

🗂 Project Structure

pixelboard/
├── backend/
│   ├── server.js              # Express + Socket.IO entry point
│   ├── config/
│   │   ├── env.js             # Environment config
│   │   └── db.js              # PostgreSQL pool
│   ├── routes/
│   │   ├── blocks.js          # Pixel block CRUD + collision detection
│   │   ├── payments.js        # Stripe Checkout + webhook
│   │   ├── users.js           # Auth + user profile
│   │   ├── admin.js           # Admin panel API
│   │   └── stats.js           # Public stats endpoint
│   ├── middleware/
│   │   ├── auth.js            # JWT middleware
│   │   └── errorHandler.js    # Global error handler
│   └── services/
│       ├── pricing.js         # Dynamic + prime-zone pricing
│       ├── realtime.js        # Socket.IO setup
│       └── storage.js         # S3/Cloudinary image upload
│
├── frontend/
│   └── src/
│       ├── components/
│       │   ├── PixelGrid.jsx       # Canvas grid (zoom, pan, select)
│       │   ├── Sidebar.jsx         # Buy / Explore / Leaderboard
│       │   ├── BuyModal.jsx        # 3-step purchase flow
│       │   ├── BlockTooltip.jsx    # Hover tooltip
│       │   ├── MiniMap.jsx         # Overview minimap
│       │   ├── ActivityFeed.jsx    # Real-time purchases
│       │   ├── ShareCard.jsx       # Viral share card
│       │   └── AdminPanel.jsx      # Admin dashboard
│       ├── store/
│       │   ├── gridStore.js        # Zustand: blocks + occupancy
│       │   ├── pricingStore.js     # Zustand: live pricing
│       │   └── uiStore.js          # Zustand: modals, tabs
│       ├── hooks/
│       │   ├── useSocket.js        # Socket.IO connection
│       │   └── useOccupancy.js     # Binary occupancy check
│       └── pages/
│           ├── Home.jsx            # Main billboard page
│           ├── Success.jsx         # Post-payment success
│           └── Profile.jsx         # User's owned pixels
│
└── database/
    └── schema.sql             # Full PostgreSQL schema

---

⚡ Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 15+
• Stripe account (for payments)
• Cloudinary or S3 (for image uploads)

1. Clone & Install

git clone https://github.com/yourname/pixelboard
cd pixelboard

# Backend
cd backend && npm install

# Frontend
cd ../frontend && npm install

2. Environment Variables

backend/.env

PORT=4000
FRONTEND_URL=http://localhost:5173
DATABASE_URL=postgresql://user:pass@localhost:5432/pixelboard
JWT_SECRET=your-super-secret-jwt-key
IP_SALT=random-salt-for-ip-hashing

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Storage (choose one)
CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name
# or AWS:
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=pixelboard-images

# Pricing
BASE_PRICE_PER_PIXEL=0.10
PRIME_MULTIPLIER=2.0
MODERATION_REQUIRED=false

frontend/.env

VITE_API_URL=http://localhost:4000/api
VITE_WS_URL=http://localhost:4000
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...

3. Database Setup

psql -U postgres -c "CREATE DATABASE pixelboard;"
psql -U postgres -d pixelboard -f database/schema.sql

4. Run Development Servers

# Terminal 1 — Backend
cd backend && npm run dev

# Terminal 2 — Frontend
cd frontend && npm run dev

5. Stripe Webhook (local testing)

stripe listen --forward-to localhost:4000/api/payments/webhook

---

🔌 API Reference

Method	Endpoint	Description
GET	/api/blocks	All approved blocks
GET	/api/blocks/occupancy	Binary occupancy bitmap
POST	/api/blocks/check	Validate selection (no auth)
POST	/api/blocks	Create block (post-payment)
POST	/api/blocks/:id/click	Record click
GET	/api/blocks/search	Search + filter blocks
GET	/api/stats	Public statistics
POST	/api/payments/create-session	Stripe Checkout session
POST	/api/payments/webhook	Stripe webhook
GET	/api/admin/dashboard	Admin summary
PATCH	/api/admin/blocks/:id/status	Approve/reject

---

🏗 Key Architecture Decisions

Collision Detection (Two-layer)

1. Database layer: PostgreSQL GiST spatial index + BOX overlap operator (&&) + trigger that raises exception on any overlap. Zero false approvals possible.
2. Frontend layer: Server-fetched binary occupancy bitmap (125KB for 1M pixels, decoded as Uint8Array). Bit-level lookup = O(1) per pixel. Client checks before payment, server re-validates at write.

Performance

• Canvas 2D rendering (not DOM) for 1M-pixel grid — handles 10,000+ blocks smoothly
• Binary occupancy map transferred as application/octet-stream — 125KB vs ~MB for JSON
• Socket.IO broadcasts real-time block additions — clients patch their local bitmap
• DB GiST index makes spatial queries sub-millisecond

Pricing Engine

Base price: $0.10/pixel
Prime zone (center 400×400): $0.20/pixel

Dynamic scarcity multipliers:
  0–25% sold:  1.0×  → $0.10/px
 25–50% sold:  1.5×  → $0.15/px
 50–75% sold:  2.5×  → $0.25/px
 75–90% sold:  5.0×  → $0.50/px
 90–100% sold: 10×   → $1.00/px

Revenue at full sell-out (with prime): ~$116,000

---

📦 Dependencies

Backend

{
  "express": "^4.18",
  "pg": "^8.11",
  "stripe": "^14",
  "socket.io": "^4.6",
  "jsonwebtoken": "^9",
  "multer": "^1.4",
  "helmet": "^7",
  "express-rate-limit": "^7",
  "cloudinary": "^1.41"
}

Frontend

{
  "react": "^18",
  "vite": "^5",
  "zustand": "^4",
  "socket.io-client": "^4",
  "axios": "^1.6",
  "@stripe/stripe-js": "^2",
  "tailwindcss": "^3",
  "framer-motion": "^11"
}

---

🚀 Deployment

Recommended Stack

Layer	Service
Frontend	Vercel (auto-deploy from GitHub)
Backend	Railway or Render
Database	Supabase (managed Postgres)
Images	Cloudinary free tier → paid
CDN	Cloudflare (free)

Supabase Quickstart

Supabase provides PostgreSQL + realtime + storage out of the box. Replace pool with Supabase client and use their storage for images. The schema.sql works directly on Supabase.

---

💡 Seed Data

-- Add a demo admin user
INSERT INTO users (email, name, role) VALUES ('admin@pixelboard.io', 'Admin', 'admin');

-- Add example blocks
INSERT INTO pixel_blocks (x,y,width,height,tooltip_name,tooltip_desc,redirect_url,color,status,price_paid)
VALUES
  (10, 10,  80, 60, 'TechCorp',  'Building the future',   'https://techcorp.io',   '#534AB7', 'approved', 480),
  (120,20,  50, 50, 'GreenAI',   'Sustainable tech',      'https://greenai.com',   '#1D9E75', 'approved', 250),
  (200,100,100, 80, 'Launchpad', 'Startup accelerator',   'https://launchpad.io',  '#D85A30', 'approved', 800),
  (400,400,120,100, 'MetaVerse', 'Digital worlds',        'https://metaverse.xyz', '#3266ad', 'featured',2400),
  (600, 50,  60, 60, 'CryptoPay','Web3 payments',         'https://cryptopay.io',  '#BA7517', 'approved', 360);