PRD.md

Planning Guide

A professional market sentiment tracking platform that allows communities to express conviction in cryptocurrencies through a pump-based voting system, with time-based filtering and point rewards for meaningful engagement.

Experience Qualities:

1. Professional - Clean, minimalistic design that conveys credibility and trustworthiness in financial sentiment tracking
2. Efficient - Instant access to sorted sentiment data with minimal clicks and maximum information density
3. Focused - Single-purpose interface centered on pump counts and temporal filtering without distractions

Complexity Level: Light Application (multiple features with basic state)

• The platform focuses on displaying ranked coins, filtering by timeframes, and managing user interactions through modals. State management is primarily client-side with simulated data persistence.

Essential Features

Coin Sentiment Dashboard

• Functionality: Displays all cryptocurrencies in a unified table/grid with pump counts, rankings, and metadata
• Purpose: Provides immediate visual hierarchy of community sentiment across all tracked assets
• Trigger: Auto-loads on page load
• Progression: User lands on page → Sees sorted coin list (default: all-time) → Can scroll through rankings
• Success criteria: All coins visible in descending pump count order with clear visual differentiation

Timeframe Filtering

• Functionality: Toggle between Daily/Weekly/Monthly/Yearly/All-Time views to see pump counts for different periods
• Purpose: Allows users to identify short-term momentum vs long-term conviction
• Trigger: User selects timeframe filter (tabs or segmented control)
• Progression: User clicks timeframe → List re-sorts instantly → Rankings update to reflect selected period
• Success criteria: Smooth transitions, accurate sorting, clear active state on selected timeframe

Pump Action System

• Functionality: Authenticated users can pump one coin per day by pressing and holding the pump button until it fills completely
• Purpose: Captures genuine community conviction through rate-limited engagement with satisfying haptic-like feedback
• Trigger: User presses and holds pump button on a coin
• Progression: User presses and holds pump → Progress bar fills with increasing sound intensity → User must hold until 100% filled → Success sound plays → Pump count increments → Points awarded → Button disabled for 24h (OR) User releases early → Fail sound plays → Pump cancelled
• Success criteria: Visual fill animation, continuous sound feedback during hold, distinct success/fail sounds, accurate state management

Coin Discovery Modal

• Functionality: Allows users to add new coins from CoinMarketCap (once per week)
• Purpose: Keeps the platform current with newly tracked assets while preventing spam
• Trigger: User clicks "Add Coin" button
• Progression: User clicks Add Coin → Modal opens → User searches/enters CoinMarketCap symbol → Validation (not duplicate, weekly limit check) → Coin added to platform → User earns EXPL points
• Success criteria: Smooth modal experience, clear validation messages, successful addition with point reward

Twitter/X Authentication

• Functionality: OAuth sign-in exclusively through Twitter/X accounts with a prominent dark button in the navbar
• Purpose: Ensures one account per user for fair rate limiting and point distribution
• Trigger: User clicks "Log In with X" button in navbar or attempts gated action
• Progression: User clicks Log In with X → Redirected to Twitter OAuth → Approves → Returns to platform logged in → Can pump and add coins
• Success criteria: Seamless OAuth flow, persistent session, clear logged-in state with user avatar in navbar

EXPL Points System

• Functionality: Users earn points for coin discovery (+100 points) and daily pumps (+10 points), with a global leaderboard tracking top contributors
• Purpose: Gamifies contribution and rewards early discovery and consistent engagement
• Trigger: Automatic on successful pump or coin addition
• Progression: User completes action → Points calculated → Total updated → Visual feedback shown → Leaderboard updates
• Success criteria: Accurate point calculation, persistent storage, visible in user profile/header and leaderboard

User Leaderboard

• Functionality: Displays all platform users ranked by EXPL points with Twitter profile links
• Purpose: Creates competitive engagement and recognizes top contributors
• Trigger: User clicks floating trophy button in bottom-left corner
• Progression: User clicks trophy button → Modal opens → See ranked list of users → Can click to view Twitter profiles
• Success criteria: Accurate ranking, smooth modal animation, working Twitter links, real-time point updates

Platform Statistics Banner

• Functionality: Displays aggregate platform metrics (total pumps, total EXPL generated, active users)
• Purpose: Demonstrates platform activity and growth to build credibility and FOMO
• Trigger: Auto-displays below header on all pages
• Progression: User views any page → Stats banner visible → Numbers animate when updated
• Success criteria: Accurate calculations, smooth number animations, responsive layout

Market Impact Meter

• Functionality: Visual progress bar showing platform impact from 1x to 1000x based on total pump activity
• Purpose: Gamifies collective progress and creates aspirational goal for community
• Trigger: Auto-displays below stats banner across entire width
• Progression: Platform loads → Impact calculated from pump formula → Progress bar animates → Rocket icon moves with progress
• Success criteria: Smooth animations, accurate formula (1000x at 10,000 total pumps), visually striking design

First Place Animation

• Functionality: The #1 ranked coin displays an animated rocket icon
• Purpose: Creates visual excitement around the leading coin and aspirational positioning
• Trigger: Automatic when coin achieves rank 1
• Progression: Coin reaches #1 → Rocket appears and animates → Floats/pulses beside coin entry
• Success criteria: Smooth looping animation, clear visual association with #1 coin

Edge Case Handling

• Rate Limit Reached: Disable pump button with tooltip explaining "Next pump available in Xh Ym"
• Pump Released Early: Play fail sound and reset progress bar without incrementing pump count
• Duplicate Coin Addition: Show validation error "This coin already exists on ONE pump"
• Invalid CoinMarketCap Symbol: Display error "Could not find coin. Verify the symbol on CoinMarketCap"
• Authentication Required: Redirect to sign-in flow with return-to-action context
• Network Errors: Show toast notification with retry option, maintain optimistic UI updates
• No Coins Available: Display empty state with call-to-action to add the first coin
• Empty Leaderboard: Show placeholder message encouraging users to pump and earn points

Design Direction

The design should feel like a professional financial terminal with crypto-native sensibilities - clean, data-dense, and highly scannable with minimal ornamentation, prioritizing clarity and speed of information access over decorative elements.

Color Selection

Custom palette - Using a vibrant purple as the primary brand color against a deep navy background, with a minimalist dark navbar for clean separation.

• Primary Color: Vibrant Purple #a147e1 - Bold and energetic, used for primary CTAs, accents, and focus states
• Secondary Colors: Dark slate for cards and surfaces, providing depth without distraction
• Accent Color: Vibrant Purple #a147e1 - Draws attention to pump actions and active states
• Foreground/Background Pairings:
  • Background (Deep Navy #0d1421): White text oklch(0.98 0 0) - High contrast ✓
  • Navbar (Dark Gray #1d1d1d): White text oklch(0.98 0 0) - High contrast ✓
  • Card (Dark Slate): Light Gray text oklch(0.90 0 0) - High contrast ✓
  • Primary (Vibrant Purple #a147e1): White text oklch(0.98 0 0) - High contrast ✓
  • Accent (Vibrant Purple #a147e1): White text oklch(0.98 0 0) - High contrast ✓

Font Selection

Typography should balance technical readability with modern aesthetics - using Inter for its exceptional clarity at small sizes in data-dense layouts while maintaining a contemporary, professional feel.

• Typographic Hierarchy:
  • H1 (Platform Name): Inter Bold / 32px / -0.02em letter spacing
  • H2 (Section Headers): Inter SemiBold / 24px / -0.01em letter spacing
  • H3 (Coin Names): Inter Medium / 18px / normal letter spacing
  • Body (Metadata): Inter Regular / 14px / normal letter spacing
  • Caption (Timestamps, Labels): Inter Regular / 12px / 0.01em letter spacing
  • Data (Pump Counts): Inter SemiBold / 16px / tabular-nums

Animations

Animations should be intense and evident where appropriate - the pump hold interaction deserves dramatic feedback with escalating sound and visual fill effects, while platform-wide elements use subtle purposeful motion for stats updates and ranking changes.

• Purposeful Meaning: Press-and-hold pump actions feature dramatic scale, fill animations, and escalating sound frequency to create Facebook-like satisfying haptic feedback; smooth opacity transitions for filter changes; rocket animation for #1 coin
• Hierarchy of Movement: Pump button hold interactions deserve primary animation focus (scale + fill + sound escalation + particle burst), impact meter progress bar secondary (smooth fill + shimmer), modal transitions tertiary (slide + fade), stats number updates quaternary (count-up animation)

Component Selection

• Components:

  • Table - Primary coin listing with sortable columns for rank, name, symbol, pump count
  • Tabs - Timeframe selector (Daily/Weekly/Monthly/Yearly/All-Time)
  • Dialog - Coin addition modal and leaderboard modal with form validation
  • Button - Pump actions (press-and-hold with fill), Add Coin (secondary), Sign In (primary), Leaderboard trigger (floating)
  • Card - Individual coin cards if using grid layout alternative
  • Avatar - User profile display in header and leaderboard
  • Badge - Point totals, rank indicators
  • Input - Coin symbol search in add modal
  • Tooltip - Rate limit explanations, icon clarifications
  • Sonner - Toast notifications for actions/errors

• Customizations:

  • Press-and-hold pump button with progress bar fill, escalating sound, and particle burst on success
  • Impact meter with gradient fill, shimmer effect, and rocket position indicator
  • Stats banner with animated number count-ups
  • Leaderboard-style ranking indicators (1st, 2nd, 3rd with medal/trophy icons)
  • Floating leaderboard button with pulsing glow effect
  • First-place rocket animation that floats beside the leading coin
  • Point animation component for incremental rewards

• States:

  • Buttons: Default (high contrast), Hover (subtle glow), Active (scale down), Disabled (50% opacity + tooltip)
  • Table Rows: Default, Hover (background lighten), Selected (subtle border)
  • Pump Button: Available (enabled), Pumped Today (success state), Limit Reached (disabled)

• Icon Selection:

  • TrendUp - Pump action icon
  • Plus - Add coin
  • XLogo - Twitter/X authentication button and profile links
  • Trophy - Points/rewards and leaderboard
  • Medal - 2nd and 3rd place in leaderboard
  • Rocket - First place indicator, impact meter icon
  • Users - Active users stat
  • Sparkle - Total EXPL stat
  • DiscordLogo - Discord link in footer

• Spacing:

  • Container padding: p-6 (24px) on desktop, p-4 (16px) on mobile
  • Card spacing: gap-4 (16px) between cards/rows
  • Component internal spacing: p-3 or p-4 for buttons and inputs
  • Section margins: mb-8 (32px) between major sections

• Mobile:

  • Table converts to card-based layout below 768px
  • Tabs become scrollable horizontal tabs on mobile
  • Modal becomes full-screen sheet on mobile
  • Sticky header with user info collapses to hamburger menu
  • Touch-friendly button sizes (minimum 44px height)