🧠 AI Flashmob - AI-Powered Flashcard Generation System

Transform any content into interactive flashcards with cutting-edge AI. Generate study materials from text, images, or web content across multiple platforms - Web Application, Chrome Extension, and MCP Integration for seamless AI assistant workflows.

🌟 System Overview

AI Flashmob is a comprehensive flashcard generation platform featuring:

• 🌐 Web Application - Complete study platform with dashboard, analytics, and AI generation
• 🔌 Chrome Extension - Browser-based flashcard creation from any web content
• 🤖 MCP Integration - Model Context Protocol for Claude and AI assistant workflows
• 🎯 Smart AI - Google Gemini 2.5 Flash for text and vision processing

🚀 Core Features

✨ AI-Powered Generation

• 📝 Text Analysis - Convert articles, notes, and documents into flashcards
• 🖼️ Image Processing - Extract knowledge from screenshots, diagrams, and photos
• 🔄 Combined Input - Process text and images together for comprehensive understanding
• 🧠 Smart Recognition - Automatic content categorization and question optimization
• ⚡ Fast Generation - Average processing time under 3 seconds

📱 Multi-Platform Access

• 🌐 Web Dashboard - Complete study environment with progress tracking
• 🔌 Chrome Extension - Generate flashcards while browsing any website
• 🤖 MCP Integration - Work with Claude and other AI assistants directly
• 📊 Real-time Sync - Seamless data synchronization across all platforms

🎯 Study Features

• 📅 Spaced Repetition - Optimized review scheduling for maximum retention
• 🗂️ Category Organization - Group flashcards by subject or topic
• 📈 Progress Analytics - Monitor learning insights and study streaks
• 📤 Export Options - Download as Anki decks or CSV files
• 🔍 Smart Search - Find flashcards with full-text search

🎨 Rich Content Support

• 🖋️ Rich Text Editing - TipTap editor with math expressions and formatting
• 📷 Image Integration - Drag-and-drop image support with compression
• 🧮 Math Support - LaTeX/KaTeX rendering for mathematical expressions
• 🎨 Syntax Highlighting - Code blocks with language detection

🏗️ System Components

1. 🌐 Web Application

Modern React Frontend:

• Framework: React 18 + Vite + TypeScript
• UI: Material-UI + Tailwind CSS + Shadcn/UI components
• Authentication: JWT with Google OAuth 2.0 integration
• State: Context API + React Query for optimal performance

Core Features:

• Dashboard - Study analytics, recent activity, and quick actions
• AI Generator - Text and image input with real-time preview
• Study Modes - Spaced repetition with progress tracking
• Category Management - Organize flashcards by subject
• Profile Settings - Account management and quota tracking

Installation:

# Prerequisites: Node.js 18+, Google Cloud setup
git clone <repository-url>
cd ai-flashmob
cp .env.example .env

# Configure environment variables
GOOGLE_CLIENT_ID=your_client_id
GEMINI_API_KEY=your_gemini_key
DATABASE_URL=postgresql://user:pass@localhost/db

# Install and run
npm install
npm run migrate
npm run dev
# Access: http://localhost:5173

2. 🔌 Chrome Extension

Manifest V3 Architecture:

• Background: Service worker with AI integration
• Content Scripts: Text selection and screen capture
• Popup: Quick access interface and authentication status
• Storage: Secure token management with auto-sync

Core Features:

• Text Selection - Select any text on web pages to generate flashcards
• Screen Capture - Capture screenshots and extract content with AI
• One-Click Generation - Instant flashcard creation with category assignment
• Offline Support - Queue generations when offline, sync when online
• Authentication Sync - Seamless login state with web application

Installation:

# From Chrome Web Store (recommended)
1. Visit Chrome Web Store → Search "AI Flashmob"
2. Click "Add to Chrome"
3. Sign in with your account

# From Source (development)
1. Download extension package
2. Chrome → Extensions → Developer mode → Load unpacked
3. Select extension folder
4. Sign in with account credentials

Usage:

1. Browse any website
2. Select text or click capture button
3. Extension popup opens with selected content
4. Choose category and generate flashcards
5. Review and save to your collection

3. 🤖 MCP (Model Context Protocol) Integration

AI Assistant Integration:

• Protocol: MCP server implementation for Claude integration
• Commands: Natural language flashcard management
• Real-time: Live data sync with web application
• Security: Secure API authentication and rate limiting

Core Features:

• Conversational Interface - Generate flashcards through chat
• Progress Tracking - View study analytics via natural language
• Category Operations - Create and manage categories conversationally
• Study Sessions - Start spaced repetition from Claude
• Smart Suggestions - AI-powered study recommendations

Installation:

# Install MCP server
npm install -g @ai-flashmob/mcp-server

# Configure connection
mcp-server configure \
  --endpoint https://your-api.com \
  --token your_api_token

# Test connection
mcp-server test

Usage with Claude:

# Generate flashcards
"Generate flashcards from: 'Photosynthesis is the process...'"

# Check progress
"Show my study progress for this week"

# Manage categories
"Create a new category called 'Biology' and add these flashcards to it"

# Start study session
"Begin spaced repetition for my Chemistry flashcards"

# Get recommendations
"What should I study next based on my progress?"

💼 Enterprise Features

🔒 Security & Compliance

• Enterprise SSO - SAML and LDAP integration available
• Data Encryption - End-to-end encryption for sensitive content
• Audit Trails - Comprehensive logging and user activity tracking
• GDPR Compliance - Full data protection and privacy controls

📊 Analytics & Reporting

• Learning Analytics - Detailed insights into study patterns
• Performance Metrics - Track retention rates and knowledge gaps
• Usage Reports - Monitor AI credit consumption and user engagement
• Custom Dashboards - Tailored analytics for administrators

🏢 Team Management

• Organization Accounts - Centralized billing and user management
• Shared Libraries - Collaborate on flashcard collections
• Role-based Access - Granular permissions for different user types
• Bulk Operations - Mass user provisioning and content management

💳 Pricing & Credits

🆓 Free Tier

• 10 AI generations per month
• 2,000 flashcards storage
• 50 categories
• Basic study modes
• Community support

⭐ Pro Tier - $9.99/month

• 100 AI generations per month
• 10,000 flashcards storage
• 500 categories
• Advanced analytics
• Priority support
• Export to Anki

🔥 Credit Top-ups

• 200 AI credits for $5.99
• Never expire
• Works with any tier
• Instant processing

📊 Technical Specifications

🔧 Performance Metrics

• Generation Speed: Average 2.8 seconds per request
• Image Processing: Up to 2048×2048 pixels (4.2M pixels)
• Text Processing: Up to 7,000 characters per request
• Uptime: 99.9% availability with automatic failover
• Scalability: Auto-scaling infrastructure for peak loads

🛡️ Security Standards

• Data Encryption: TLS 1.3 in transit, AES-256 at rest
• Authentication: Multi-factor with OAuth 2.0 and JWT
• Compliance: GDPR, SOC 2, and ISO 27001 standards
• Privacy: Zero data retention for AI processing
• Rate Limiting: Intelligent throttling and abuse prevention

🚀 Quick Start

For Developers:

# Prerequisites: Node.js 18+, PostgreSQL, Google Cloud account
git clone <repository-url>
cd ai-flashmob
cp .env.example .env

# Configure environment
GOOGLE_CLIENT_ID=your_client_id
GEMINI_API_KEY=your_gemini_key
DATABASE_URL=postgresql://user:pass@localhost/db

# Install and run
npm install
npm run migrate
npm run dev
# Access: http://localhost:5173

For End Users:

1. Web App: Visit https://ai-flashmob.com
2. Chrome Extension: Install from Chrome Web Store
3. Claude Integration: Configure MCP server for AI assistant access

Production Deployment

🎯 First-Time Deployment

# 1. Environment Setup
cp .env.example .env
# Edit .env with your production values (domains, secrets, API keys)

# 2. SSL Certificate Setup (Cloudflare Origin Certificate)
mkdir -p nginx/ssl
# Save your Origin Certificate as nginx/ssl/fullchain.pem
# Save your private key as nginx/ssl/privkey.pem
chmod 644 nginx/ssl/fullchain.pem
chmod 600 nginx/ssl/privkey.pem

# 3. First-Time Deploy (includes automatic migrations)
docker compose -f docker-compose.prod.yml up -d --build

# 4. Verify deployment
curl -I https://yourdomain.com/
curl -I https://api.yourdomain.com/health

🔄 Update Deployment (Code Changes)

# 1. Pull latest changes
git pull origin main

# 2. Rebuild and deploy
docker compose -f docker-compose.prod.yml up -d --build

# 3. Verify services are healthy
docker compose -f docker-compose.prod.yml ps

🗄️ Manual Migration (if needed)

# Only needed if migrations fail during deployment
docker compose -f docker-compose.prod.yml exec migration npm run migrate

🏗️ Architecture

Development

Frontend (React) ←→ Backend (Node.js) ←→ PostgreSQL
Port 5173           Port 3002          Port 5432
                         ↓
                    Gmail API
                (Email Verification)

Production (Dockerized + SSL)

Cloudflare ←→ Nginx (SSL) ←→ Frontend (React) ←→ Backend (Node.js) ←→ PostgreSQL
443/80        443/80          Container:5173     Container:3002      Container:5432
                                   ↓
                              Gmail/Gemini API
                           (Email + AI Generation)

🔧 Configuration

Environment Variables

Key configuration in .env:

# Google OAuth (Required)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3002/api/auth/google/callback

# Gmail API (Required)
GMAIL_REFRESH_TOKEN=your-gmail-refresh-token
[email protected]

# AI Configuration
GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL=gemini-2.5-flash-preview-05-20

# Security (Change for production)
JWT_SECRET=your-jwt-secret
SESSION_SECRET=your-session-secret

🛠️ Commands

# Development
npm run dev                 # Local development mode
npm run dev:stop            # Stop local services

# Production
npm run deploy              # Full Docker deployment
npm run deploy:stop         # Stop all services

# Database Management
npm run db:migrate          # Run database migrations
npm run db:seed             # Seed with demo data
npm run db:reset            # Reset database

# Gmail API Setup (Required)
cd backend
node scripts/setupGmail.js  # Generate Gmail refresh token

📱 System Components

🌐 Frontend Web Application (/frontend)

• Framework: React 18 + Vite with hot module replacement
• UI Components: Material-UI (@mui/material) + Shadcn/UI (@radix-ui) with Tailwind CSS
• Routing: React Router with protected routes and lazy loading
• State Management: Context API for authentication + React Query for server state
• Authentication: Multi-method login with extension sync
• Features: Dashboard, flashcard management, study modes, AI generation interface

🔌 Chrome Extension (/extension)

• Architecture: Manifest V3 with service workers
• Background Script: AI integration and cross-platform communication
• Content Scripts: Screen capture and text selection
• Popup Interface: Authentication status and quick actions
• Features: Screen capture, text selection, AI generation, authentication sync

🚀 Backend API Server (/backend)

• Framework: Node.js + Express with comprehensive middleware
• Authentication: JWT + Passport.js with Google OAuth 2.0
• AI Integration: Google Gemini 2.5 Flash API for advanced generation
• Email Service: Gmail API integration for verification emails
• Security: Rate limiting, CORS, input validation, session management
• Features: RESTful API, quota management, transaction logging

🗄️ Database Layer (/database)

• Engine: PostgreSQL 15 with advanced indexing
• ORM: Knex.js with automated migrations and rollback support
• Schema: Users, flashcards, categories, quota transactions, email verification
• Features: Full-text search, referential integrity, performance optimization
• Analytics: Usage tracking, quota management, audit trails

🌍 Production Deployment Guide

1. SSL Certificate Setup (Cloudflare)

Recommended: Cloudflare Origin Certificates

1. Create Origin Certificate:

   • Go to Cloudflare Dashboard → Your Domain → SSL/TLS → Origin Server
   • Click "Create Certificate"
   • Include hostnames: yourdomain.com, www.yourdomain.com, api.yourdomain.com
   • Choose RSA (2048), 15 years validity
   • Save Origin Certificate as nginx/ssl/fullchain.pem
   • Save Private Key as nginx/ssl/privkey.pem

2. Set Proper Permissions:

   chmod 644 nginx/ssl/fullchain.pem
   chmod 600 nginx/ssl/privkey.pem

2. Domain Configuration

Update .env with your domain:

WEB_APP_URL=https://yourdomain.com
API_BASE_URL=https://api.yourdomain.com/api
GOOGLE_CALLBACK_URL=https://api.yourdomain.com/api/auth/google/callback
EMAIL_VERIFICATION_BASE_URL=https://yourdomain.com
CORS_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

3. Google Console Updates

1. Add production redirect URI: https://api.yourdomain.com/api/auth/google/callback
2. Update OAuth consent screen with production domain
3. Re-generate Gmail refresh token for production environment

4. Security

Generate secure production secrets:

JWT_SECRET=super-secure-production-secret-minimum-32-characters
SESSION_SECRET=another-secure-production-secret

5. Docker Deployment

🎯 New Deployment Process (Simplified)

# 1. Single command deployment with automatic migrations
docker compose -f docker-compose.prod.yml up -d --build

# The system will automatically:
# - Start PostgreSQL database
# - Run migrations in a dedicated container
# - Start backend only after migrations complete
# - Start frontend and nginx

# 2. Verify deployment
docker compose -f docker-compose.prod.yml ps
curl https://api.yourdomain.com/health

📋 Deployment Flow

1. PostgreSQL starts first and waits for health check
2. Migration container runs migrations and exits
3. Backend starts only after migrations complete successfully
4. Frontend and Nginx start after backend is ready

6. Production Setup Checklist

✅ These steps are now automated with the migration container:

1. Database Migrations (Automatic)

   Migrations now run automatically during deployment! The migration container:

   • Runs after PostgreSQL is healthy
   • Completes all migrations before backend starts
   • Exits after successful completion
   • Prevents connection pool conflicts

   Manual migration (only if needed):

   # If you need to run migrations manually
   docker compose -f docker-compose.prod.yml run --rm migration npm run migrate
      
   # Verify migrations completed
   docker exec ai_flashmob_postgres psql -U flashcard_user -d flashcard_db -c "\dt"

2. Gmail API Setup (Required)

   cd backend
   node scripts/setupGmail.js
   # Follow the authorization flow and update .env with the refresh token

3. Verify Services

   # Check all containers are healthy
   docker compose -f docker-compose.prod.yml ps
   
   # Test API health
   curl https://api.yourdomain.com/health
   
   # Test frontend
   curl -I https://yourdomain.com/
   
   # Test database connection
   docker logs ai_flashmob_backend | grep "Database connected"

4. Test OAuth Flow (Important)

   # Test Google OAuth (should work without errors)
   # 1. Go to https://yourdomain.com
   # 2. Click "Sign in with Google"
   # 3. Complete OAuth flow
   # 4. Should redirect back successfully
   
   # If OAuth fails, check:
   docker logs ai_flashmob_backend | grep -i oauth
   docker logs ai_flashmob_backend | grep -i error

5. Production Health Check

   # All these should return success
   curl -f https://yourdomain.com/
   curl -f https://api.yourdomain.com/health
   docker compose -f docker-compose.prod.yml ps --filter "status=running"

🔍 Troubleshooting

SSL/Nginx Issues

# Check nginx configuration
docker exec ai_flashmob_nginx nginx -t

# View nginx logs
docker logs ai_flashmob_nginx

# Common 521 errors (Cloudflare)
# - Ensure SSL certificates are in nginx/ssl/
# - Check nginx container is running and healthy
# - Verify Cloudflare proxy settings

Gmail API Issues

# Test email sending
docker exec ai_flashmob_backend node test-email.js

# Re-generate token if needed
cd backend && node scripts/setupGmail.js

Database Issues

# Check PostgreSQL logs
docker compose -f docker-compose.prod.yml logs postgres

# Test database connection
docker compose -f docker-compose.prod.yml exec postgres psql -U flashcard_user -d flashcard_db -c "SELECT version();"

# Re-run migrations if needed
cd database
NODE_ENV=production npm run migrate

# Reset database (DANGER: removes all data)
cd database
NODE_ENV=production npx knex migrate:rollback --all
NODE_ENV=production npm run migrate

Container Issues

# View logs
docker compose -f docker-compose.prod.yml logs backend

# Restart services
docker compose -f docker-compose.prod.yml restart

# Clean rebuild
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d --build

# Check container health
docker ps
docker compose -f docker-compose.prod.yml ps

Common Production Issues

521 Error (Cloudflare)

• nginx container is restarting → Check nginx logs
• SSL certificates missing → Verify nginx/ssl/ contains fullchain.pem and privkey.pem
• Config syntax error → Run docker exec ai_flashmob_nginx nginx -t

OAuth Issues

"invalid_grant" Error (Code Reuse)

# Symptoms: OAuth works first time, then fails with "invalid_grant"
# Cause: Authorization codes are single-use and expire quickly

# Solutions:
1. Don't refresh the callback URL after OAuth success
2. Check browser network tab for duplicate callback requests
3. Clear browser cookies/session if stuck in OAuth loop
4. Restart backend to clear OAuth state cache: docker restart ai_flashmob_backend

"Invalid State" Error

# Symptoms: OAuth fails with "invalid_state" or "expired OAuth session"
# Cause: CSRF protection or state parameter issues

# Solutions:
1. Ensure cookies are enabled in browser
2. Don't use OAuth in incognito/private mode
3. Check that domain in .env matches your actual domain
4. Restart backend: docker restart ai_flashmob_backend

Database Connection Issues

"Knex: Timeout acquiring a connection" Error

# Symptoms: Migration fails with "pool is probably full"
# Cause: This issue is now RESOLVED with the migration container

# ✅ NEW: Automatic resolution
# The migration container runs in isolation before backend starts,
# eliminating connection pool conflicts entirely.

# Manual migration (if somehow needed):
docker compose -f docker-compose.prod.yml run --rm migration npm run migrate

# Check migration container logs
docker compose -f docker-compose.prod.yml logs migration

"relation does not exist" Errors

# Symptoms: OAuth fails with "users table does not exist"
# Cause: Database migrations not run (should not happen with migration container)

# ✅ NEW: This is automatically prevented
# The migration container ensures all tables exist before backend starts.

# If this still happens, manually run migrations:
docker compose -f docker-compose.prod.yml run --rm migration npm run migrate

# Verify tables exist
docker exec ai_flashmob_postgres psql -U flashcard_user -d flashcard_db -c "\dt"

Backend/Frontend Not Loading

• Check all containers are running: docker ps
• Verify environment variables in .env
• Check network connectivity between containers
• Verify database migrations completed: docker logs ai_flashmob_backend | grep "Database connected"

📚 Comprehensive Documentation

🏗️ Architecture Documentation

Complete technical documentation covering all system components:

• 📖 EXTENSION_ARCHITECTURE.md - Chrome Extension Manifest V3 architecture

  • Service worker background tasks and AI integration
  • Popup interface and content script functionality
  • Authentication sync and cross-platform communication
  • Screen capture workflows and API communication

• 🌐 FRONTEND_ARCHITECTURE.md - React 18 application architecture

  • Component structure and routing system
  • Authentication context and state management
  • API client with interceptors and error handling
  • UI components and Material-UI integration

• 🚀 BACKEND_ARCHITECTURE.md - Node.js API server architecture

  • Express middleware and route organization
  • JWT authentication and OAuth 2.0 integration
  • Google Gemini AI service integration
  • Database layer and email service setup

• 🗄️ DATABASE_ARCHITECTURE.md - PostgreSQL database design

  • Complete schema with relationships and constraints
  • Migration system and performance optimization
  • Query patterns and indexing strategies
  • Security measures and backup procedures

• 🔗 SYSTEM_INTEGRATION.md - Complete system integration

  • Cross-component communication patterns
  • Authentication flows and data synchronization
  • Error handling and recovery mechanisms
  • Performance optimization and caching strategies

• 📊 SEQUENCE_DIAGRAMS.md - Visual workflow documentation

  • Authentication flows (extension ↔ web app ↔ backend)
  • AI generation workflows (screen capture and text processing)
  • Data management operations (CRUD and batch processing)
  • Error handling and recovery scenarios

🔧 API Documentation

Visit /api/docs when backend is running for interactive API documentation.

Authentication Endpoints

• POST /api/auth/register - User registration with email verification
• POST /api/auth/login - Email/password authentication
• GET /api/auth/google - Google OAuth 2.0 login initiation
• POST /api/auth/verify-email - Email verification with token
• POST /api/auth/refresh - JWT token refresh for extensions
• POST /api/auth/logout - Secure logout with cookie clearing

AI Generation Endpoints

• POST /api/ai/generate-cards - Generate flashcards from images
• POST /api/ai/generate-text-cards - Generate flashcards from text
• GET /api/ai/usage - AI usage statistics and quota information

Data Management Endpoints

• GET /api/flashcards - Paginated flashcard listing with search
• POST /api/flashcards - Create individual flashcard
• POST /api/flashcards/bulk - Bulk flashcard creation
• PUT /api/flashcards/:id - Update flashcard content
• DELETE /api/flashcards/:id - Delete flashcard
• GET /api/categories - User categories with flashcard counts
• POST /api/categories - Create new category
• GET /api/quota - Current quota balance and transaction history

📋 Development Features

Each documentation file includes:

• Component Overview: Core functions and responsibilities
• Key Files: Detailed file structure with line references
• Function Documentation: Method descriptions with code examples
• Dependency Mapping: Complete endpoint calling patterns
• Communication Protocols: Inter-component message flows
• Security Considerations: Authentication, validation, and data protection
• Performance Optimization: Caching, batching, and database optimization
• Error Handling: Comprehensive error recovery mechanisms

🔒 Security Features

• HTTP-only Cookies - XSS protection for web application
• JWT Authentication - Secure tokens with 32+ character secrets
• Dual Auth Support - HTTP-only cookies (web) + Bearer tokens (extension/API)
• OAuth 2.0 Integration - Google Sign-In with state validation
• Rate Limiting - Protection against brute force attacks
• CORS Protection - Domain whitelisting for cross-origin requests
• Input Validation - Server-side validation with detailed error messages
• Session Management - Automatic token cleanup and validation
• Security Headers - CSP, CSRF protection, and secure cookie settings

📄 License

MIT License - see LICENSE file for details.

🌟 System Highlights

✅ Enterprise-Grade Architecture - Multi-platform synchronization with robust authentication
✅ Advanced AI Integration - Google Gemini 2.5 Flash with vision and text processing
✅ Comprehensive Documentation - Complete technical reference with sequence diagrams
✅ Production Deployment - Docker containerization with SSL and monitoring
✅ Security by Design - Multi-layer authentication, input validation, and data protection
✅ Performance Optimized - Caching, connection pooling, and batch operations

🤝 Support & Community

📞 Get Help

• 📧 Email: [email protected]
• 💬 Discord: AI Flashmob Community
• 📖 Documentation: Complete guides and API references
• 🐛 Bug Reports: GitHub Issues for technical problems

🚀 Enterprise Solutions

• Custom Deployment: On-premise or private cloud options
• Advanced Integration: SSO, LDAP, and custom authentication
• Priority Support: Dedicated success manager and 24/7 support
• Custom Training: Tailored AI models for specific domains

🔗 Useful Links

• 🌐 Web Application: https://ai-flashmob.com
• 🔌 Chrome Extension: Chrome Web Store
• 📚 Documentation: Complete Documentation
• 🔧 API Reference: API Documentation
• 🎮 Demo: Try Interactive Demo

🌟 Why Choose AI Flashmob?

✅ 🤖 Cutting-Edge AI - Google Gemini 2.5 Flash for superior content understanding
✅ 📱 Multi-Platform - Seamless experience across web, extension, and AI assistants
✅ 🔒 Enterprise Security - Bank-grade encryption and compliance standards
✅ ⚡ Lightning Fast - Sub-3-second generation with 99.9% uptime
✅ 🎯 Learning Focused - Spaced repetition and analytics for optimal retention
✅ 🔧 Developer Friendly - Complete APIs, SDKs, and comprehensive documentation

Transform your learning with AI-powered flashcards. Start creating smarter study materials today.