8000 GitHub - lorsabyan/vaf-bg-ai-lab: AI driven experimental app prototype named Brainograph AI Lab powered by VAF
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

lorsabyan/vaf-bg-ai-lab

BranchesTags

Repository files navigation

Brainograph AI Lab - VAF Educational Platform

🎉 Recently migrated from Create React App to Next.js for improved performance and static site generation!

🚀 Live Demo V1 | Live Demo V2 | 📋 Documentation | 🔗 VAF Website

An AI-driven Next.js application that combines article exploration and quiz generation functionality. Built for the VAF (Visual Armenia Development Foundation) educational platform.

Features

📚 Article Explorer

  • Search & Browse: Search through educational articles
  • Enhanced Text Selection Tooltips: Select any text in articles to get comprehensive information:
    • 💡 AI-Powered Explanations: Contextual explanations using Gemini AI
    • 🖼️ Relevant Images: Visual content from Google Image Search
    • 🔗 Educational Links: Curated web resources from educational sites
    • 📚 Academic Citations: Scholarly references and academic sources
  • Multi-Strategy Search: Intelligent fallback mechanisms for optimal results
  • Contextual Search: Uses article context to improve search relevance
  • Key Points Extraction: AI-generated summaries of main article points
  • Article Translation: Translate articles to different languages while preserving formatting
  • Responsive Article Viewer: Clean, readable article display with mobile optimization

🧠 AI-Powered Quiz Generation

  • Smart Quiz Creation: Generate quizzes from any article using Google's Gemini AI
  • Customizable Instructions: Specify exactly what type of quiz you want
  • Multiple AI Models: Choose from different Gemini models (Flash, Pro, etc.)
  • Temperature Control: Adjust creativity vs accuracy of generated questions
  • Interactive Quiz Taking: Clean, modern quiz interface with progress tracking

📊 Quiz History & Analytics

  • Complete History: Track all completed quizzes with scores and details
  • Performance Analytics: View statistics including average scores and progress
  • Detailed Results: Review individual quiz answers and explanations
  • Export & Persistence: Quiz history saved locally with backup/restore options

🔐 Authentication & Security

  • User Authentication: Secure login system
  • API Key Management: Secure storage and management of Gemini API keys
  • Session Management: Persistent user sessions with token-based auth

📱 Modern UI/UX

  • Mobile-First Design: Fully responsive across all devices
  • TailwindCSS Styling: Modern, clean, and accessible design
  • Armenian Language Support: Localized interface in Armenian
  • Dark/Light Theme: Support for multiple themes
  • Loading States: Comprehensive loading and error handling

Technology Stack

  • Frontend: Next.js 14 with React 18 functional components and hooks
  • Styling: TailwindCSS 3 for responsive design
  • AI Integration: Google Generative AI (Gemini) SDK for explanations and quiz generation
  • Search Integration: Google Custom Search API for images, links, and citations
  • State Management: React Context API with useReducer
  • Build Tool: Next.js with static site generation
  • Deployment:
    • GitHub Pages with multi-version support
    • Automated CI/CD with GitHub Actions
    • Optimized static export for production

Getting Started

Prerequisites

Installation

  1. Clone the repository:

    git clone https://github.com/lorsabyan/vaf-bg-ai-lab.git
cd vaf-bg-ai-lab

  2. Install dependencies:

    npm install

  3. Start development server:

    npm run dev

  4. Open in browser: Navigate to http://localhost:3000

Deployment

Single Version Deployment

For deploying a single version to GitHub Pages:

npm run deploy

Multi-Version Deployment

The project supports deploying multiple versions simultaneously:

  • V1 (Stable): https://lorsabyan.github.io/vaf-bg-ai-lab/ (root path)
  • V2 (Latest): https://lorsabyan.github.io/vaf-bg-ai-lab/v2/
  • Version Selector: https://lorsabyan.github.io/vaf-bg-ai-lab/version-info.html

Automatic Deployment (Recommended):

  • Push to release/v1 or release/v2 branches
  • GitHub Actions automatically deploys both versions

Manual Multi-Version Deployment:

# Deploy both V1 and V2 from their respective branches
./deploy.sh

# Alternative using npm script
npm run deploy:versions

For detailed deployment documentation, see DEPLOYMENT.md.

Usage Guide

1. Authentication

  • Log in with your credentials on the home screen
  • The system supports user authentication with persistent sessions

2. Article Exploration

  • Use the "Հոդվածների որոնում" (Article Search) tab
  • Search for articles using keywords
  • Click on any article to view its content
  • Enhanced Text Selection Features:
    • Click "Select and Explain" to enable selection mode
    • Select any text to open an enhanced tooltip with 4 tabs:
      • 💡 Explanation: AI-powered contextual explanations
      • 🖼️ Images: Relevant visual content from Google Search
      • 🔗 Links: Educational web resources and articles
      • 📚 Citations: Academic references and scholarly sources
  • Key Points: Generate AI-powered summaries of article highlights
  • Translation: Translate articles while preserving HTML formatting

3. Quiz Generation

  • Switch to the "Վիկտորինա" (Quiz) tab
  • First, select an article from the Article Explorer
  • Configure your Gemini API key by clicking the 🔑 button in the header
  • Customize quiz instructions (e.g., "Create 10 multiple choice questions about the main concepts")
  • Choose AI model and creativity level
  • Click "Ստեղծել վիկտորինա" (Generate Quiz)
  • Click "Սկսել վիկտորինան" (Start Quiz) when ready

4. Taking Quizzes

  • Navigate through questions using Previous/Next buttons
  • Select answers by clicking on options
  • View progress bar at the top
  • Complete quiz to see detailed results and score

5. Quiz History

  • Switch to the "Պատմություն" (History) tab
  • View all completed quizzes with scores and dates
  • Click "View Details" to review individual answers
  • See performance statistics and trends
  • Delete individual quiz results or clear all history

Configuration

API Keys

  • Gemini AI: Required for quiz generation and text explanations
    • Get your key from Google AI Studio
    • Add the key via the 🔑 button in the app header
  • Google Custom Search (Optional): Enables enhanced tooltips with images, links, and citations

Environment Variables

For production deployment, you can set:

  • REACT_APP_GEMINI_API_KEY: Default Gemini API key
  • REACT_APP_GOOGLE_SEARCH_API_KEY: Google Custom Search API key
  • REACT_APP_GOOGLE_SEARCH_ENGINE_ID: Google Custom Search Engine ID

Project Structure & Deployment

Development Branches

  • main: Primary development branch
  • release/v1: Stable production version (deployed to root path)
  • release/v2: Latest development version (deployed to /v2 path)

GitHub Pages Setup

  • Automatic Deployment: GitHub Actions workflow triggers on pushes to release branches
  • Multi-Version Support: Both versions deployed simultaneously to different paths
  • Version Selector: Beautiful landing page to choose between versions

For detailed deployment configuration, see DEPLOYMENT.md.

Directory Structure

src/
├── components/
│   ├── articles/          # Article search and viewing
│   ├── auth/             # Authentication components
│   ├── common/           # Layout and navigation
│   ├── quiz/             # Quiz generation and taking
│   └── ui/               # Reusable UI components
├── context/              # React Context for state management
├── services/             # API and external service calls
│   ├── articleService.js    # Article data management
│   ├── authService.js       # Authentication logic
│   ├── googleSearchService.js # Google Search API integration
│   └── quizService.js       # Gemini AI quiz generation
└── utils/                # Constants and utilities

Key Components

  • AppContext: Global state management
  • QuizGenerator: AI-powered quiz creation
  • QuizInterface: Interactive quiz taking
  • QuizHistory: Results tracking and analytics
  • ArticleViewer: Article display with AI explanations and enhanced tooltips
  • EnhancedTooltip: Multi-tab tooltip with images, links, and citations
  • GoogleSearchService: Integration with Google Custom Search API

Performance Optimizations

The application has been optimized for performance with the following React optimizations:

🚀 Memoization Strategy

  • useMemo: Expensive calculations cached to prevent unnecessary recalculation

    • Article content formatting (HTML parsing and text extraction)
    • Language-specific difficulty mappings
    • Quiz question metadata processing
    • Search result filtering and sorting

  • useCallback: Event handlers memoized to prevent child component re-renders

    • Text selection handlers for AI explanations
    • Quiz navigation and answer selection
    • Modal and dialog interactions
    • API call handlers for quiz generation and translation

  • React.memo: Components wrapped to prevent unnecessary re-renders

    • Layout component for stable UI structure
    • ArticleViewer for heavy content processing
    • Quiz interface components for smooth interactions

⚡ Performance Benefits

  • Reduced Re-renders: Significant reduction in unnecessary component updates
  • Faster Text Processing: Article formatting operations cached for reuse
  • Smoother Interactions: Quiz and article interactions respond faster
  • Memory Efficiency: Expensive operations computed only when dependencies change
  • Better UX: More responsive interface, especially on mobile devices

🔧 Technical Implementation

  • Strategic use of dependency arrays in hooks to control re-computation
  • Content memoization for AI operations (explanations, translations, key points)
  • Event handler optimization to prevent child component cascading updates
  • Component-level memoization for heavy rendering operations

Features in Detail

AI Quiz Generation

The app uses Google's Gemini AI to generate contextual quizzes from any article:

  • Analyzes article content and structure
  • Creates relevant multiple-choice questions
  • Ensures questions test comprehension and key concepts
  • Supports various difficulty levels and question types

Enhanced Text Selection Tooltips

Select any text in articles to get comprehensive information through a modern, tabbed interface:

💡 AI Explanations

  • Contextual Definitions: Understanding terms within their article context
  • Historical Background: Relevant historical information and context
  • Concept Connections: How selected terms relate to broader topics
  • Simplified Explanations: Complex concepts broken down for better understanding

🖼️ Visual Content (Google Images)

  • Relevant Images: Contextually appropriate visual content
  • Educational Focus: Prioritizes educational and informative images
  • Multiple Search Strategies: Fallback mechanisms for optimal results
  • High-Quality Sources: Curated from reliable image sources

🔗 Educational Resources (Web Links)

  • Curated Sources: Links from educational institutions (.edu, .org, .gov)
  • Wikipedia Integration: Reliable encyclopedia entries
  • Academic Publishers: Links to britannica.com and other educational sites
  • Contextual Relevance: Links related to the selected text and article context

📚 Academic Citations

  • Scholarly Sources: Research papers and academic publications
  • Citation Metadata: Author information and publication years when available
  • Academic Databases: Sources from ResearchGate, Academia.edu, ArXiv, PubMed
  • Google Scholar Integration: Academic search results with proper citations

🔧 Technical Features

  • Multi-Strategy Search: Tries simple, enhanced, and minimal search approaches
  • Contextual Keywords: Uses surrounding article text to improve search relevance
  • Performance Optimization: Concurrent API calls with intelligent fallbacks
  • Comprehensive Debugging: Detailed logging for troubleshooting and optimization

Mobile-First Design

  • Responsive navigation with collapsible sidebar
  • Touch-optimized quiz interface
  • Readable typography on all screen sizes
  • Optimized loading states for slower connections

Contributing

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

License

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

Support

For support and questions:

  • Create an issue on GitHub
  • Contact the VAF development team

Roadmap

🚀 Upcoming Features

  • Advanced quiz types (true/false, short answer)
  • Collaborative quiz sharing
  • Advanced analytics and progress tracking
  • Offline mode support
  • Multiple language support for tooltips
  • Integration with more AI models
  • Cross-version feature synchronization
  • Version-specific settings and preferences

🔄 Multi-Version Development

  • Branch-specific feature toggles
  • Version comparison tools
  • Automated version migration utilities
  • Independent version analytics

🔍 Search & Discovery Enhancements

  • Advanced article filtering and categorization
  • Bookmarking and favorites system
  • Full-text search across articles
  • Related articles suggestions

🌐 Google Search API Improvements

  • Video content integration from YouTube EDU
  • News articles related to selected topics
  • Interactive maps and geographical context
  • Timeline integration for historical topics
  • Scientific data and charts integration

📊 Analytics & Insights

  • Learning progress tracking
  • Topic mastery indicators
  • Personalized content recommendations
  • Usage analytics and insights dashboard

Built with ❤️ for the VAF Educational Platform

About

AI driven experimental app prototype named Brainograph AI Lab powered by VAF

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages
0