Skip to content

README.md

Latest commit

 

History

History
421 lines (297 loc) · 12.5 KB

README.md

File metadata and controls

421 lines (297 loc) · 12.5 KB

Useless Facts App

A comprehensive web application that demonstrates AI-aided software development, technical capabilities, and modern web development practices. Originally started as a toy project to test AI vibe coding capabilities, it has evolved into a full-featured application showcasing the complete software development lifecycle.

🌐 Live Demo: useless-app-nu.vercel.app

🚀 Project Evolution

This project began as a simple toy application to test AI vibe coding capabilities, but has grown into a comprehensive demonstration of:

  • AI-Aided Development: Complete software development lifecycle using AI vibe coding
  • Technical Capabilities: Full-stack development with modern technologies
  • Product Design: User experience design and feature planning
  • Development Lifecycle: From concept to production deployment
  • Tech Stack Integration: Frontend, backend, APIs, databases, and AI services
  • Data Processing: Real-time data ingestion and AI-powered content generation

✨ Features

🎯 Core Functionality

  • Random Facts: Generate and rate useless facts with persistent voting
  • Real-Time News Facts: AI-powered facts generated from latest news articles
  • Smart Topic Selection: Choose from trending topics extracted via NER and TF-IDF
  • Interactive Infographics: Data-driven visualizations (burger flipping science)
  • Blog System: Simple markdown-based blog for updates

🤖 AI & Machine Learning

  • Named Entity Recognition (NER): Extract topics from news using Google Gemini 2.0
  • TF-IDF Scoring: Rank topic relevance and importance
  • Intelligent Matching: Match user-selected topics with relevant articles
  • Streaming AI Generation: Real-time fact generation with progress indicators

🎨 User Experience

  • Dark/Light Mode: Automatic theme switching with system preference detection
  • Responsive Design: Mobile-first approach with Tailwind CSS
  • Modern UI: Built with shadcn/ui components and Lucide icons
  • Performance Optimized: Aggressive caching and efficient data loading

🛠️ Tech Stack

Frontend

  • Next.js 13 (App Router) with React 18
  • TypeScript for type safety
  • Tailwind CSS for styling
  • shadcn/ui for components
  • Chart.js for data visualization

Backend

  • Next.js API Routes for serverless functions
  • Turso (libSQL) for cloud database
  • Zod for runtime validation

AI & Data Processing

  • Google Gemini 2.0 Flash Lite for NER
  • RSS Parser for news ingestion
  • TF-IDF Algorithm for topic scoring

Deployment

  • Vercel with automatic CI/CD
  • Environment-based configuration

🎯 Development Process Demonstration

This project showcases the complete software development lifecycle using AI vibe coding:

1. Product Design & Planning

  • Feature ideation and user story mapping
  • Technical architecture planning
  • Database schema design
  • API endpoint specification

2. Frontend Development

  • React component architecture
  • State management and data flow
  • Responsive design implementation
  • User experience optimization

3. Backend Development

  • API route implementation
  • Database integration and queries
  • Authentication and security
  • Error handling and validation

4. AI Integration

  • Prompt engineering for content generation
  • Named Entity Recognition (NER) implementation
  • Topic extraction and scoring algorithms
  • Real-time AI content generation

5. Data Processing Pipeline

  • RSS feed ingestion and parsing
  • News article processing
  • Topic extraction and ranking
  • Content generation workflows

6. Testing & Debugging

  • Unit and integration testing
  • API endpoint testing
  • User interface testing
  • Performance optimization

7. Deployment & DevOps

  • Environment configuration
  • CI/CD pipeline setup
  • Security implementation
  • Production monitoring

🧠 Technical Capabilities Demonstrated

This project demonstrates proficiency in various technical domains:

Frontend Technologies

  • Modern React patterns and hooks
  • Next.js App Router and server components
  • TypeScript for type safety
  • Tailwind CSS for responsive design
  • Component library integration (shadcn/ui)

Backend & APIs

  • Next.js API routes and serverless functions
  • RESTful API design and implementation
  • Database integration and ORM patterns
  • Authentication and authorization
  • Error handling and validation

Database & Data Management

  • SQL database design and optimization
  • Cloud database integration (Turso)
  • Data migration and seeding
  • Query optimization and indexing
  • Data validation and sanitization

AI & Machine Learning

  • Large Language Model integration (Gemini)
  • Prompt engineering and optimization
  • Named Entity Recognition (NER)
  • TF-IDF algorithm implementation
  • Real-time AI content generation

Data Processing

  • RSS feed parsing and ingestion
  • Text processing and normalization
  • Topic extraction and scoring
  • Content aggregation and ranking
  • Automated data pipelines

DevOps & Deployment

  • Environment configuration management
  • CI/CD pipeline setup
  • Security best practices
  • Performance monitoring
  • Production deployment strategies

🤖 AI-Aided Development Showcase

This project demonstrates the power of AI vibe coding throughout the entire development process:

Development Lifecycle with AI

  • Planning: AI-assisted feature ideation and technical architecture
  • Design: User experience design and interface prototyping
  • Implementation: Code generation, debugging, and optimization
  • Testing: Automated testing and quality assurance
  • Deployment: CI/CD setup and production monitoring

AI Vibe Coding Benefits

  • Rapid Prototyping: Quick iteration and feature development
  • Code Quality: Consistent patterns and best practices
  • Problem Solving: AI-assisted debugging and optimization
  • Learning: Real-time education and skill development
  • Productivity: Faster development cycles and reduced time-to-market

Technical Implementation

  • Prompt Engineering: Optimized AI prompts for content generation
  • Data Processing: Automated topic extraction and scoring
  • Real-time Generation: Live AI content creation from news sources
  • User Experience: Seamless integration of AI capabilities

🚀 Quick Start

Prerequisites

  • Node.js 22.x or later
  • npm or yarn
  • Turso database account
  • Google Gemini API key

Installation

  1. Clone the repository

    git clone https://github.com/werther41/useless-app.git
cd useless-facts-app

  2. Install dependencies

    npm install

  3. Environment Setup

    Create a .env.local file:

    # Database
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-turso-token

# AI Services
GOOGLE_API_KEY=your-gemini-api-key

# Security (for admin features)
ADMIN_SECRET=your-secure-admin-secret
CRON_SECRET=your-cron-secret

  4. Initialize Database

    # Seed with initial data (requires admin authentication)
curl -X POST "http://localhost:3000/api/seed" \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET"

  5. Start Development Server

    npm run dev

    Visit http://localhost:3000

📁 Project Structure

├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── facts/         # Fact management endpoints
│   │   ├── topics/        # Topic extraction endpoints
│   │   └── cron/          # Scheduled tasks
│   ├── admin/             # Admin interfaces (protected)
│   ├── deep-dive/         # Infographic pages
│   └── blog/              # Blog system
├── components/            # React components
│   └── ui/                # shadcn/ui base components
├── lib/                   # Utilities and business logic
├── types/                 # TypeScript definitions
├── content/               # Markdown content
└── public/                # Static assets

🔧 Configuration

Environment Variables

Variable Description Required
TURSO_DATABASE_URL Turso database connection string ✅
TURSO_AUTH_TOKEN Turso authentication token ✅
GOOGLE_API_KEY Google Gemini API key for AI features ✅
ADMIN_SECRET Secret for admin authentication ✅
CRON_SECRET Secret for cron job endpoints ✅

Admin Access

Admin features are protected by authentication. To access:

  1. Admin Pages: Add ?admin_secret=YOUR_SECRET to URLs

    • /admin/import?admin_secret=YOUR_SECRET
    • /admin/topics?admin_secret=YOUR_SECRET

  2. API Endpoints: Include Authorization: Bearer YOUR_SECRET header

    curl -X POST "http://localhost:3000/api/seed" \
  -H "Authorization: Bearer YOUR_ADMIN_SECRET"

📊 API Documentation

Public Endpoints

Endpoint Method Description
/api/facts/random GET Get a random fact
/api/facts GET Get facts with pagination
/api/facts/{id}/rate POST Rate a fact
/api/topics GET Get trending topics
/api/facts/real-time POST Generate AI fact from news

Admin Endpoints (Protected)

Endpoint Method Description
/api/seed POST Seed database
/api/facts/import POST Bulk import facts
/api/test-db GET Test database connection

Example Usage

# Get a random fact
curl http://localhost:3000/api/facts/random

# Get trending topics
curl http://localhost:3000/api/topics?limit=10

# Generate AI fact with topics
curl -X POST http://localhost:3000/api/facts/real-time \
  -H "Content-Type: application/json" \
  -d '{"selectedTopics": ["AI", "Technology"]}'

🚀 Deployment

Vercel Deployment

  1. Connect Repository

    • Link your GitHub repository to Vercel
    • Enable automatic deployments

  2. Environment Variables

    • Add all required environment variables in Vercel dashboard
    • Ensure ADMIN_SECRET and CRON_SECRET are set

  3. Database Setup

    • Create a Turso database
    • Add connection details to environment variables

Manual Deployment

# Build the application
npm run build

# Start production server
npm run start

🧪 Testing

# Run all tests
./scripts/test-all.sh

# Test specific features
npx tsx scripts/test-topic-extraction.ts

# Lint and type check
npm run lint
npm run typecheck

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📞 Support

If you have questions or need help:

  1. Check the documentation
  2. Open an issue
  3. Review the API documentation

🎯 Project Impact

This project demonstrates the evolution from a simple toy application to a comprehensive showcase of:

  • AI-Aided Development: Complete software lifecycle using AI vibe coding
  • Technical Proficiency: Full-stack development with modern technologies
  • Product Development: From concept to production deployment
  • Learning & Growth: Continuous improvement and feature enhancement
  • Real-World Application: Practical implementation of cutting-edge technologies

Note: This is a demonstration application showcasing AI-aided development capabilities. For production use, implement proper authentication, rate limiting, and security measures.