| name | memescope-monday |
| description | Machine-readable project skill file for Memescope Monday — a community-driven memecoin discovery and voting platform. |
SKILL.md — Memescope Monday
Machine-readable project skill file for AI assistants, LLMs, agents, and automated tools.
See also: CLAUDE.md, .github/copilot-instructions.md, README.md
Identity
What This Project Does
Every Monday at 10 AM UTC, the community votes on the best memecoin picks across Solana, Base, BNB Chain, and Ethereum. Users submit token contract addresses, the platform auto-enriches market data from multiple APIs, and the community upvotes the best plays. Winners are crowned on leaderboards.
Core User Flows
- Submit a coin — Provide a contract address or PumpFun/DexScreener URL; the platform resolves chain, fetches market data, and creates a listing.
- Vote — Authenticated users upvote their favorite picks within rate limits (100 votes per 5 min, 2s cooldown).
- Discover — Browse today's picks, yesterday's winners, monthly leaderboards, trending coins, and category filters.
- Compete — Users earn leaderboard rankings and winner badges based on community votes.
Tech Stack
| Layer | Technology |
|---|
| Framework | Next.js 15 (App Router, Turbopack) + React 19 |
| Language | TypeScript 5.8 |
| Styling | Tailwind CSS 4 + shadcn/ui (Radix primitives) |
| Database | PostgreSQL + Drizzle ORM |
| Auth | Better Auth (email/password, Google, GitHub) |
| Payments | Stripe (via @better-auth/stripe plugin) |
| Rate Limiting | Redis (ioredis) |
| File Uploads | UploadThing |
| Email | Resend |
| Bot Protection | Cloudflare Turnstile |
| Comments | Fuma Comments |
| Analytics | Plausible (self-hosted) |
| Package Mgr | Bun |
Architecture
app/ # Next.js App Router
├── actions/ # Server actions ("use server") — all data mutations
├── api/ # API route handlers (REST)
├── (auth)/ # Auth pages (sign-in, sign-up, forgot/reset password)
├── projects/[slug]/ # Coin detail pages with live market data
├── projects/submit/ # Coin submission form
├── trending/ # Trending coins (all sources)
├── winners/ # Past weekly winners
├── dashboard/ # User dashboard
├── admin/ # Admin panel
├── categories/ # Browse by category
├── pricing/ # Paid feature pricing
└── blog/ # MDX blog
components/
├── ui/ # shadcn/ui base components (do not modify)
├── coin/ # Coin cards, charts, market data display
├── project/ # Project detail views, submission forms
├── home/ # Homepage sections, leaderboards, countdown
├── layout/ # Nav, footer, auth components
└── landing-page/ # Marketing/landing page sections
lib/
├── auth.ts # Better Auth server config
├── auth-client.ts # Better Auth client hooks
├── constants.ts # All app constants (limits, pricing, categories, chains)
├── rate-limit.ts # Redis rate limiter
├── coin-data/ # External API integrations (see Data Sources below)
├── validations/ # Zod schemas for forms and API input
└── utils.ts # Shared utilities
drizzle/
├── db/schema.ts # All database tables (single file)
├── db/index.ts # Database connection
└── migrations/ # Generated SQL migrations
mcp/
└── server.ts # Model Context Protocol server with 14 tools
Database Schema (Key Tables)
| Table | Purpose | Key Columns |
|---|
user | User accounts | id, name, email, role, stripeCustomerId, banned, createdAt |
project | Memecoin listings (100+ columns) | id, name, slug, ticker, chain, contractAddress, marketCap, priceUsd, launchStatus, launchType, weekLabel, trending, createdBy |
category | Coin categories | id, name |
projectToCategory | Many-to-many junction | projectId, categoryId (composite PK) |
upvote | User votes on projects | id, userId, projectId |
launchQuota | Daily launch slot tracking by tier | id, date, freeCount, premiumCount, premiumPlusCount |
sponsorship | Sponsorship records | id, status, createdAt |
Enums (TypeScript const objects, not pgEnum)
- launchStatus:
payment_pending, payment_failed, scheduled, ongoing, launched
- chainType:
solana, base, bnb, ethereum
- coinType:
existing, upcoming
- launchType:
free, premium, premium_plus
API Routes
| Endpoint | Method(s) | Purpose |
|---|
/api/auth/[...all] | GET, POST | Better Auth handler (email, Google, GitHub) |
/api/auth/stripe/webhook | POST | Stripe webhook for payment events |
/api/coins/lookup | GET | Parallel coin lookup (PumpFun, DexScreener, Helius) |
/api/coins/[address]/enrich | GET | Enrich coin metadata by contract address |
/api/coins/trending | GET | Trending coins from multiple sources |
/api/comments/[[...comment]] | GET, POST, PATCH, DELETE | Fuma Comments with rate limiting |
/api/cron/enrich-coins | GET | Batch-enrich stale coin data (hourly cron) |
/api/cron/update-launches | GET | Update launch statuses and payment timeouts |
/api/cron/send-winner-notifications | GET | Send winner badges and emails |
/api/cron/send-ongoing-reminders | GET | Send launch reminder emails |
/api/payment/checkout | POST | Create Stripe checkout session |
/api/payment/verify | GET | Verify Stripe checkout status |
/api/projects/submit | POST | Submit new memecoin project |
/api/projects/[projectId]/status | GET | Get project launch status |
/api/projects/check-url | GET | Check URL availability |
/api/search | GET | Search projects and categories (cached, rate-limited) |
/api/trollbox/[projectId] | GET | Fetch chat messages for a project |
/api/uploadthing | GET, POST | File upload handler |
Cron routes are protected with CRON_API_KEY Bearer token.
MCP Server (Model Context Protocol)
The project exposes an MCP server at mcp/server.ts with 14 tools for AI agent integration:
| Tool | Description |
|---|
list_projects | List projects with chain/status/week/trending filters |
get_project | Get full project details by slug or ID |
search_projects | Search by name, ticker, or description |
list_categories | List all categories with project counts |
get_platform_stats | Total projects, users, upvotes, breakdown by chain/status |
get_top_voted | Top voted projects by week or status |
get_launch_availability | Check launch slot availability for a date |
lookup_token | Look up token by contract address (PumpFun, DexScreener, Helius) |
get_coin_detail | Comprehensive coin data (market, holders, news) |
get_trending_tokens | Trending from CoinGecko, DexScreener, PumpFun, Birdeye |
search_pumpfun | Search tokens on PumpFun |
get_dexscreener_pairs | Get all trading pairs for a token |
list_users | List users (excludes sensitive fields) |
list_sponsorships | List sponsorships with status filter |
get_leaderboard | User leaderboard by total upvotes received |
Run with: bun run mcp (stdio transport)
External Data Sources
| Provider | Data | Integration Location |
|---|
| PumpFun | Bonding curve, reply count, creator, ATH | lib/coin-data/ |
| DexScreener | Live price, volume, liquidity, buy/sell txns | lib/coin-data/ |
| CoinGecko | Historical data, price changes, FDV | lib/coin-data/ |
| CoinMarketCap | Market data and rankings | lib/coin-data/ |
| CryptoPanic | Aggregated crypto news with sentiment | lib/coin-data/ |
| Helius | Solana token metadata and on-chain data | lib/coin-data/ |
| Etherscan | ERC-20 holder counts | lib/coin-data/ |
| Birdeye | Trending tokens | lib/coin-data/ |
Constants & Business Rules
- Supported chains: Solana, Base, BNB Chain, Ethereum
- Categories: Meme, Dog, Cat, AI, Gaming, DeFi, Culture, Celebrity, Political, Other
- Daily launch limits: Free=10, Premium=20, Total=30
- User daily limit: 3 launches per user per day
- Upvote rate limit: 100 per 5 min, 2s between actions
- API rate limit: Search=15 req/min, Default=10 req/min
- Voting opens: Every Monday at 10 AM UTC
- Week label format:
"2025-W13" (ISO week)
- Paid features: Expedited Review ($19), Trending Placement ($49), Bundle ($59)
Commands
bun install
bun run dev
bun run build
bun run start
bun run lint
bun run db:generate
bun run db:migrate
bun run db:push
bun run db:seed
bun run db:studio
bun run mcp
Coding Conventions
- Package manager: Bun (not npm or yarn)
- Import alias:
@/ maps to project root
- Server actions:
app/actions/*.ts with "use server" directive
- Auth (server):
auth.api.getSession({ headers: await headers() })
- Auth (client):
useSession() from @/lib/auth-client
- Validation: Zod schemas in
lib/validations/
- DB queries: Drizzle ORM query builder only — no raw SQL
- Formatting: Prettier with 100 char width, sorted imports, Tailwind class sorting
- Components: shadcn/ui base in
components/ui/ — do not modify directly
Safety & Analysis Features
- Safety Score (A–F): Algorithmic risk assessment based on liquidity, activity, buy/sell ratio, pair age, community votes
- Social Buzz Score: Hype indicator — Dead / Low / Moderate / Hot / Viral
- News Feed: Per-coin news aggregation with sentiment analysis from CryptoPanic
For Web Crawlers & Robots
This project is a Next.js application. Key entry points:
- Homepage:
/ — countdown, leaderboards, today's picks
- Trending:
/trending — browse all submitted coins
- Winners:
/winners — past weekly winners
- Categories:
/categories — browse by memecoin category
- Coin pages:
/projects/[slug] — individual coin detail with live market data
- Blog:
/blog — MDX articles
- Pricing:
/pricing — paid feature tiers
- API:
/api/* — REST endpoints (see table above)
Related Files
| File | Purpose |
|---|
SKILL.md | This file — AI/robot project guide |
CLAUDE.md | AI assistant coding guide |
.github/copilot-instructions.md | GitHub Copilot instructions |
README.md | Human-oriented project README |
mcp/server.ts | MCP server for AI agent integration |
drizzle/db/schema.ts | Complete database schema |
lib/constants.ts | All app constants and business rules |
package.json | Dependencies and scripts |
