AI-Powered Social Media Sentiment Analysis Platform

Empowering small teams and organizations to understand public sentiment at scale. Built for The AI Champion Ship hackathon.

🚀 Live Demo: https://beyondvelvet.sea1.vultrobjects.com/index.html

🎬 Demo Video: Watch on YouTube

Competing in:

• 🎯 Best Small Startup Agents - Force multiplier for small teams to monitor brand sentiment
• 🌍 Best AI Solution for Public Good - Democratizing sentiment analysis for nonprofits, researchers, and community organizations

The Information Cocoon Challenge: Social media algorithms create personalized bubbles where people primarily see content that confirms their existing views. This "information cocoon" or "filter bubble" makes it difficult to understand what the broader public actually thinks across different communities and perspectives.

The Accessibility Gap: Traditional sentiment analysis tools are expensive, complex, and require data science expertise. Small teams and public good organizations are locked out of insights that could help them make better decisions, respond to crises, and serve their communities.

The Result: People and organizations operate with distorted views of public opinion, leading to poor decisions, increased polarization, and missed opportunities to understand diverse perspectives.

BeyondVelvet breaks through the information cocoon by aggregating unfiltered public sentiment across social media platforms. Instead of relying on your algorithmically-curated feed, get an objective view of what everyone is actually saying.

Key Capabilities:

• 📱 Unfiltered Data Collection - Scrape raw, unfiltered social media posts from multiple platforms (Twitter/X deployed, Reddit/TikTok/YouTube architecture ready)
• 🤖 AI-Powered Analysis - Intelligent sentiment classification, keyword extraction, and opinion clustering
• 📊 Objective Insights - See all perspectives: positive, neutral, and negative sentiment distributions
• 🎯 Opinion Clustering - Understand different viewpoints and user segments beyond your bubble
• ⚡ Smart & Fast - 24-hour caching reduces costs by 95%, sub-second response for cached queries
• 🚀 Launch-Ready - Professional UI, error handling, and scalable architecture

Note: Multi-platform architecture is built and ready, but limited to Twitter/X for cost optimization during the hackathon period.

Social media algorithms create comfortable "velvet bubbles" - soft, pleasant environments where you only see content that aligns with your existing views. It feels good, but it limits your understanding of the broader conversation.

BeyondVelvet represents going beyond these comfortable bubbles to discover diverse perspectives and understand what the wider world actually thinks. It's about expanding your view, not just confirming it.

For Small Startups:

• Track brand reputation without expensive enterprise tools
• Early warning system for PR crises
• Understand customer feedback at scale
• Monitor competitors in real-time

For Public Good:

• Break Filter Bubbles - See what people across the political spectrum actually think
• Combat Misinformation - Understand public sentiment beyond your curated feed
• Research & Academia - Analyze genuine public opinion trends without algorithmic bias
• Community Organizations - Track local concerns across diverse populations
• Media & Journalism - Report on public sentiment with objective data

For Curious Users:

• Explore Any Topic - Discover what the world really thinks about topics you care about
• Escape Your Bubble - See perspectives you'd never encounter in your own feed
• Settle Debates - Get objective data on controversial topics instead of anecdotes
• Stay Informed - Understand public opinion on news, trends, and cultural moments

Specific Use Cases:

• 🏢 Small businesses monitoring product launches beyond their follower base
• 🌱 Environmental nonprofits tracking climate sentiment across all viewpoints
• 🏛️ Local governments understanding citizen concerns from diverse communities
• 📚 Academic researchers studying social trends without filter bubble bias
• 🎗️ Advocacy groups measuring campaign impact across political divides
• 📰 Journalists reporting on public opinion with unfiltered data
• 🎮 Curious individuals exploring what people really think about their favorite games, movies, or hobbies

Built on LiquidMetal AI's Raindrop Platform with Raindrop Smart Components:

┌─────────────────────────────────────────────────────────┐
│                    USER (Web Browser)                    │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              FRONTEND (React + Vite)                     │
│  • Interactive dashboard with real-time updates          │
│  • Beautiful charts and visualizations                   │
│  • Report generation and PDF export                      │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP/REST
                         ▼
┌─────────────────────────────────────────────────────────┐
│         BACKEND API (Raindrop + Hono.js)                │
│                                                          │
│  ┌────────────────────────────────────────────┐         │
│  │       Data Collection Layer                │         │
│  │  • Social media scraping (Apify)           │         │
│  │  • Multi-platform support ready            │         │
│  │  • Smart rate limiting & caching           │         │
│  └────────────────────────────────────────────┘         │
│                                                          │
│  ┌────────────────────────────────────────────┐         │
│  │       Analysis & Processing                │         │
│  │  • Keyword-based sentiment detection       │         │
│  │  • Opinion clustering algorithms           │         │
│  │  • Trend analysis and aggregation          │         │
│  └────────────────────────────────────────────┘         │
│                                                          │
│  ┌────────────────────────────────────────────┐         │
│  │       Raindrop Smart Components            │         │
│  │  • SmartBucket: AI-powered storage         │         │
│  │  • SQL Database: Structured data           │         │
│  │  • KV Cache: High-performance caching      │         │
│  └────────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              EXTERNAL SERVICES                           │
│  • Apify (Social media scraping platform)               │
│  • Social Media APIs (Twitter/X, Reddit*, TikTok*)      │
│    * Architecture ready, not deployed (cost optimized)  │
└─────────────────────────────────────────────────────────┘

• ✅ Social Media Data Collection - Scrape posts from social media platforms using Apify (Twitter/X deployed, Reddit/TikTok/YouTube ready)
• ✅ Sentiment Analysis - Keyword-based emotional classification (positive, neutral, negative)
• ✅ Smart Caching - 24-hour intelligent caching to optimize costs and performance
• ✅ Keyword Extraction - Identify trending terms and topics from collected posts
• ✅ Opinion Clustering - Segment and analyze different user perspectives
• ✅ Interactive Dashboards - Beautiful data visualizations with Recharts
• ✅ Report Generation - Create detailed sentiment reports with PDF export
• ✅ Favorites System - Save and track topics of interest over time
• ✅ Query History - Track all previous analyses with localStorage persistence

• 📈 Trend Analysis - Sentiment distribution and engagement metrics
• 🔍 Sample Posts - View representative examples from each sentiment category
• 🎨 Customizable UI - Dark mode support and responsive design
• ⚡ Performance Optimized - Sub-second response for cached queries

• Raindrop Platform: Entire backend deployed on Raindrop serverless infrastructure ✅
• AI Coding Assistant: Built with Claude Code (Anthropic) throughout development ✅
• Vultr Services Integration:
  • Frontend: Vultr Object Storage (Seattle region) ✅
  • Backend: Vultr infrastructure via Raindrop platform ✅
• Smart Components Utilized:
  • SmartBucket (reports-store) - AI-powered document storage for sentiment reports and scraped data
  • SQL Database (app-db) - Structured data storage with automatic migrations (users, reports, query cache)
  • KV Cache (session-cache) - High-performance caching layer for query optimization
• Launch-Ready Quality: Professional UI, error handling, caching, favorites system, PDF export
• Working Demo: Live at https://beyondvelvet.sea1.vultrobjects.com/index.html ✅
• Open Source: MIT License with complete source code ✅

• Frontend Deployment: Static site hosting on Vultr Object Storage (Seattle region)
• Backend Services: Hono.js HTTP service on Raindrop with 8 active modules (deployed on Vultr infrastructure)
• Smart Caching: Reduces API costs by ~95% using query hash and 24-hour TTL
• Data Pipeline: Social media scraping → sentiment analysis → SmartBucket storage → cached results
• Type Safety: Full TypeScript implementation with Raindrop-generated types
• AWS S3 Integration: Configured AWS CLI for Vultr Object Storage deployment

• ✅ Live deployed application at beyondvelvet.sea1.vultrobjects.com/index.html
• ✅ Public GitHub repository (MIT License)
• ✅ Demo video (max 3 minutes)
• ✅ Comprehensive documentation (setup, deployment, API configuration)

• SmartBucket - AI-powered document storage and semantic search for reports
• SQL Database (D1) - Relational database with automatic migrations
• KV Cache - High-performance key-value caching layer

• Raindrop Framework (v0.13.0) - Serverless application platform by LiquidMetal AI
• Hono.js (v4) - Lightweight, ultra-fast HTTP router
• Kysely (v0.27.2) - Type-safe SQL query builder
• Zod (v3) - TypeScript schema validation
• TypeScript (v5.0.4) - End-to-end type safety

• React 18 - Modern UI library with hooks
• Vite 6 - Next-generation build tool
• Tailwind CSS - Utility-first styling
• Radix UI - Accessible component primitives
• Recharts - Data visualization library
• React Hook Form - Performant form management
• Lucide React - Icon library
• Sonner - Toast notifications

• Apify - Web scraping infrastructure for social media data collection (supports Twitter/X, Reddit, TikTok, YouTube via different actors)

• Node.js 18+ installed
• Raindrop CLI installed: npm install -g @liquidmetal-ai/raindrop
• Raindrop account (sign up)
• Apify account with API token (free tier available)

# 1. Clone the repository
git clone https://github.com/yourusername/BeyondVelvet.git
cd BeyondVelvet

# 2. Install backend dependencies
cd backend
npm install

# 3. Authenticate with Raindrop
raindrop auth login

# 4. Select your organization (if applicable)
raindrop auth select

# 5. Configure Apify API token
raindrop build env setup
# Enter your APIFY_API_TOKEN when prompted

# 6. Build TypeScript
npm run build

# 7. Deploy and start backend
raindrop build deploy --start

# 8. View deployment status
raindrop build status

Your backend API will be deployed at: https://api.<your-tenant>.lmapp.run

# 1. Navigate to frontend directory
cd ../frontend

# 2. Install dependencies
npm install

# 3. Update API endpoint in frontend/src/config.ts
# Set API_BASE_URL to your deployed backend URL

# 4. Start development server
npm run dev

# 5. Open browser
# Navigate to http://localhost:3000

If joining an existing project:

# 1. Pull latest code
git pull origin main

# 2. Install dependencies (both backend and frontend)
cd backend && npm install
cd ../frontend && npm install

# 3. Authenticate with Raindrop
raindrop auth login
raindrop auth select  # Select team organization

# 4. Generate types from manifest
cd ../backend
raindrop build generate

# 5. Build to verify setup
npm run build

# You're ready to develop!

Additional documentation in /doc:

• DEPLOYMENT.md - Deploy frontend to production (Vercel/Netlify/Vultr)
• APIFY_SETUP.md - Multi-platform scraping configuration
• RAINDROP.md - Raindrop framework reference
• FRONTEND.md - React frontend architecture

1. Navigate to Chat Page - Click on the Chat tab in the navigation
2. Enter Query - Type a search topic (e.g., "Tesla", "iPhone 15", "climate change")
3. Wait for Analysis - Fresh scraping takes 10-30 seconds, cached results < 1 second
4. View Results - Comprehensive dashboard showing:
   • 📊 Emotion breakdown chart (positive/neutral/negative distribution)
   • 🔑 Top keywords (ranked by frequency)
   • 📈 Engagement metrics (mentions, authors, average engagement)
   • 💬 Sample posts from each sentiment category
   • 🎯 Opinion clusters (user segment breakdown)
   • 📱 Platform distribution

• View History - Access the "Me" page to see all past analyses
• Detailed Reports - Click any report for full visualizations and insights
• Export PDF - Download professional reports for presentations
• Delete Reports - Remove unwanted analyses from history

• Save Topics - Mark frequently analyzed topics as favorites
• Quick Access - One-click analysis from the Home page
• Color Coding - Customize with gradient color labels
• Manage - Add, remove, or update favorite topics

Set these in Raindrop dashboard or via CLI:

# Required
APIFY_API_TOKEN=your_apify_token_here

# Optional (for future features)
# REDDIT_CLIENT_ID=your_reddit_client_id
# REDDIT_CLIENT_SECRET=your_reddit_client_secret

Setting secrets via CLI:

raindrop build env set APIFY_API_TOKEN "your_token" --secret

In backend/src/api/config.ts:

SCRAPER_CONFIG.MAX_POSTS_PER_QUERY: 8    // Scraping limit (dev: 8, prod: 100-500)
SCRAPER_CONFIG.SAMPLE_POSTS_LIMIT: 3     // Sample posts to display
CACHE_CONFIG.TTL_HOURS: 24               // Cache expiration time

• Cache Strategy: 24-hour TTL dramatically reduces redundant scraping
• Scraping Limits: 8 posts (development) / 100-500 posts (production)
• Cost Optimization:
  • Fresh scrape: ~$0.01-0.05 per query (Apify pricing)
  • Cached query: $0.00 (completely free!)
• Response Time:
  • Cached queries: <1 second
  • Fresh scraping: 10-30 seconds
  • Report generation: <5 seconds

BeyondVelvet/
├── backend/                    # Backend (Raindrop serverless)
│   ├── src/
│   │   ├── api/                # API endpoints & services
│   │   │   ├── index.ts        # Main API routes (chat, reports, favorites)
│   │   │   ├── config.ts       # Configuration constants
│   │   │   └── services/
│   │   │       ├── twitter-scraper.ts   # Apify Twitter integration
│   │   │       └── reddit-scraper.ts    # Reddit scraper (disabled)
│   │   └── _app/               # App-level configuration
│   │       ├── auth.ts         # JWT authentication
│   │       └── cors.ts         # CORS policy
│   ├── db/
│   │   └── app-db/             # Database migrations
│   │       ├── 0000_initial_schema.sql
│   │       └── 0001_add_query_cache.sql
│   ├── raindrop.manifest       # Infrastructure definition
│   ├── package.json
│   └── tsconfig.json
│
├── frontend/                   # React frontend application
│   ├── src/
│   │   ├── components/
│   │   │   ├── pages/          # Main pages (Home, Chat, Me, ReportDetail)
│   │   │   ├── chat/           # Chat components (ChatInput, ResultsPanel, ResultCard, etc.)
│   │   │   └── ui/             # Radix UI components (~48 files)
│   │   ├── api/
│   │   │   └── client.ts       # API client & types
│   │   ├── utils/              # Storage utilities (reportStorage, favoriteStorage)
│   │   └── App.tsx             # Main app router
│   ├── package.json
│   └── vite.config.ts
│
├── doc/                        # Documentation
│   ├── DEPLOYMENT.md
│   ├── APIFY_SETUP.md
│   ├── RAINDROP.md
│   └── FRONTEND.md
│
├── .gitignore                  # Git ignore rules
└── README.md                   # This file

Backend:

npm run build      # Compile TypeScript to dist/
npm run start      # Deploy and start on Raindrop
npm run stop       # Stop the application
npm run restart    # Restart (redeploy)
npm run format     # Format code with Prettier
npm run lint       # Lint with ESLint
npm run test       # Run tests with Vitest

Frontend:

npm run dev        # Start development server
npm run build      # Production build
npm run preview    # Preview production build

# View real-time logs
raindrop logs tail

# Query historical logs
raindrop logs query --since 30m

# Check deployment status
raindrop build status

# Find service URLs
raindrop build find

• ✅ Twitter/X sentiment analysis
• ✅ Smart caching system
• ✅ Interactive dashboards
• ✅ Report generation and export
• ✅ Favorites management

• Activate Multi-Platform Collection - Enable Reddit, YouTube, TikTok scrapers (architecture ready, requires API budget allocation)
• User Authentication - Personalized dashboards and saved preferences
• Historical Trend Analysis - Compare sentiment across time periods
• Real-time Streaming - Live updates as new posts are collected
• Advanced Filtering - Date ranges, verified users, engagement thresholds
• Collaborative Features - Share reports with team members
• Email Notifications - Alerts for saved topics
• Premium Tier - Enhanced features and higher scraping limits
• SmartInference Integration - Advanced AI model-based sentiment analysis
• SmartSQL Queries - Natural language database querying
• SmartMemory - Conversational context tracking across sessions

• Raindrop Documentation: https://docs.liquidmetal.ai/
• Raindrop Dashboard: https://liquidmetal.run
• Apify Platform: https://apify.com/

MIT License

Copyright (c) 2025 BeyondVelvet Team

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

• LiquidMetal AI Raindrop Platform - Serverless infrastructure and Smart Components
• Vultr - Cloud infrastructure, Object Storage for frontend hosting
• Apify - Web scraping infrastructure and social media data collection
• shadcn/ui - Beautiful UI components (MIT License)

Made with ❤️ for The AI Champion Ship Hackathon

Expanding perspectives beyond the bubble. 🚀