🎯 ByteForge - FocusFlow

Real-Time Meeting Assistant for ADHD and Neurodivergent Students

A comprehensive full-stack web application designed to help students with ADHD and Autism manage their studies more effectively. The platform processes notes, transcribes audio/video content, generates intelligent summaries, and provides an AI-powered chat assistant with context-aware responses.

✨ Features

📝 Process Notes

Upload and process PDF and text files
Extract text content from PDFs using advanced parsing
Generate ADHD-friendly summaries with key concepts, digestible chunks, and study tips
Automatically break down complex content into manageable sections

🎙️ Live Recording

Real-time meeting and lecture recording using browser MediaRecorder API
Instant transcription of recorded audio
Role-aware summaries tailored to user's perspective (Student, Developer, etc.)
Automatic generation of study artifacts (notes, flashcards, quizzes)

🎥 Upload Media

Upload audio/video files or provide YouTube URLs
Multiple transcription strategies with intelligent fallback:
- Supadata API for fast transcriptions
- AssemblyAI for comprehensive summaries
- Local transcription via Groq Whisper
Download and process YouTube videos automatically
Generate study materials from video content

💬 Ask Questions (Smart Chat)

Context-aware AI chat assistant
Intelligent Resource Filtering: Automatically detects when you mention specific resources
- "PDF notes" → Uses only PDF/notes context
- "YouTube video" → Uses only video/YouTube context
- "Live recording" → Uses only recording context
- No mention → Uses all available context
Retrieves context from all previous sessions stored in database
Real-time conversation with ADHD-friendly responses

📅 Study Schedule Generator

Create personalized study schedules based on exam dates
Input topics and available study hours
AI-generated day-by-day study plans with breaks and variety
Optimized for ADHD-friendly learning patterns

🛠️ Tech Stack

Backend

Node.js + Express.js - Server framework
MongoDB + Mongoose - Database and ODM
Groq SDK - AI/ML services (LLaMA 3.3 & Whisper)
JWT - Authentication tokens
bcrypt - Password hashing
Multer - File upload handling
pdf-parse (v2.4.5) - PDF text extraction
ytdl-core - YouTube video downloading
Zod - Input validation

Frontend

React 19 - UI framework
Vite - Build tool and dev server
Axios - HTTP client
CSS3 - Styling with modern features

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18.0.0 or higher)
npm or yarn package manager
MongoDB (local instance or MongoDB Atlas account)
Groq API Key (Get one here)

Optional (for YouTube processing)

Supadata API Key (for fast transcriptions)
AssemblyAI API Key (for advanced transcriptions)
yt-dlp (for YouTube download fallback)
FFmpeg (for audio conversion)

🚀 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd ByteForge

2. Backend Setup

cd backend
npm install

Create a .env file in the backend directory:

# Server Configuration
PORT=3001

# Database
MONGO_URI=mongodb://localhost:27017/focusflow
# Or for MongoDB Atlas:
# MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/focusflow

# JWT Secret (generate a strong random string)
JWT_SECRET=your_super_secret_jwt_key_here

# Groq AI API (Required)
GROQ_API_KEY=your_groq_api_key_here

# Optional: YouTube Transcription Services
SUPADATA_API_KEY=your_supadata_key_here
ASSEMBLYAI_API_KEY=your_assemblyai_key_here

# Optional: YouTube Download Settings
ALLOW_YOUTUBE_FALLBACK=true
ENABLE_YTDLP=true
ENABLE_FFMPEG=true
ENABLE_PIPED_FALLBACK=true
ENABLE_ASSEMBLYAI_URL=false

3. Frontend Setup

cd ../frontend
npm install

Create a .env file in the frontend directory (optional):

VITE_API_BASE_URL=http://localhost:3001

4. Start MongoDB

Local MongoDB:

# If using local MongoDB, make sure it's running
mongod

MongoDB Atlas:

Create a free cluster at MongoDB Atlas
Get your connection string and add it to .env

🏃 Running the Project

Development Mode

Terminal 1 - Backend:

cd backend
npm run dev

Server will run on http://localhost:3001

Terminal 2 - Frontend:

cd frontend
npm run dev

Frontend will run on http://localhost:5173 (or port shown in terminal)

Production Mode

Backend:

cd backend
npm start

Frontend:

cd frontend
npm run build
npm run preview

📡 API Endpoints

Authentication

POST /api/auth/signup - Create new account
POST /api/auth/signin - Login

Features

POST /api/process-notes - Upload and process PDF/text files
POST /api/transcribe - Transcribe audio file
POST /api/transcribe-media - Upload media or YouTube URL
POST /api/chat - Chat with AI assistant
POST /api/study-schedule - Generate study schedule

Results Management

GET /api/results - List all user results (optional: ?type=notes|media|transcribe)
GET /api/results/:id - Get specific result
DELETE /api/results/:id - Delete result

Health Check

GET /api/health - Server status

Note: All endpoints except /api/health and /api/auth/* require JWT authentication.

📁 Project Structure

ByteForge/
├── backend/
│   ├── src/
│   │   ├── config/
│   │   │   └── db.js              # MongoDB connection
│   │   ├── controllers/          # Business logic
│   │   │   ├── authController.js
│   │   │   ├── chatController.js
│   │   │   ├── mediaController.js
│   │   │   ├── notesController.js
│   │   │   ├── scheduleController.js
│   │   │   ├── transcribeController.js
│   │   │   └── resultsController.js
│   │   ├── middleware/
│   │   │   ├── authMiddleware.js  # JWT verification
│   │   │   ├── errorHandler.js   # Error handling
│   │   │   └── validateInput.js # Input validation
│   │   ├── models/
│   │   │   ├── userModel.js      # User schema
│   │   │   └── resultModel.js    # Results schema
│   │   ├── routes/
│   │   │   ├── api.js            # API routes
│   │   │   └── authRoutes.js    # Auth routes
│   │   ├── utils/
│   │   │   ├── aiGenerator.js    # Groq AI integration
│   │   │   ├── fileHandler.js    # File upload config
│   │   │   ├── tokenUtils.js     # JWT utilities
│   │   │   └── youtube.js        # YouTube processing
│   │   └── server.js             # Express app setup
│   ├── uploads/                  # Temporary file storage
│   └── package.json
│
└── frontend/
    ├── src/
    │   ├── components/
    │   │   ├── ChatAssistant.jsx
    │   │   ├── Login.jsx
    │   │   ├── MeetingAssistant.jsx
    │   │   ├── MeetingTranscriber.jsx
    │   │   ├── NotesProcessor.jsx
    │   │   ├── StudySchedule.jsx
    │   │   └── Icon.jsx
    │   ├── App.jsx               # Main component
    │   ├── App.css               # Global styles
    │   └── main.jsx              # React entry point
    └── package.json

🔑 Key Features Explained

Context-Aware Chat System

The chat assistant intelligently filters context based on your question:

Resource Detection: Analyzes your question for keywords like "PDF", "YouTube", "recording"
Smart Filtering: Only uses relevant stored data from previous sessions
Context Combination: Merges current tab context with database context
Real-time Updates: Automatically loads context from all previous sessions

Multi-Strategy YouTube Processing

When processing YouTube videos, the system requires:

ytdl-core (direct download)
ffmpeg (installed with ytdl)

This ensures maximum reliability and uptime.

PDF Processing with Modern API

Uses pdf-parse v2.4.5 with the new PDFParse class API:

Creates parser instance with buffer data
Extracts text using getText() method
Properly cleans up resources with destroy()
Handles both PDF and plain text files

Role-Aware Summaries

Transcriptions can be customized for different roles:

Student: Focus on learning objectives, key concepts
Developer: Technical details, code references
Manager: Action items, decisions, follow-ups
Default: General-purpose summary

🔒 Security Features

Password Hashing: bcrypt with 10 salt rounds
JWT Authentication: Secure token-based auth (7-day expiration)
Rate Limiting: 100 requests per 15 minutes per IP
Input Validation: Zod schema validation for all user inputs
CORS Protection: Configured for secure cross-origin requests
Error Handling: Comprehensive error handling with user-friendly messages

📝 Usage Examples

Processing a PDF

Navigate to "Process Notes" tab
Drag and drop or select a PDF file
Wait for processing (shows progress)
View the processed, ADHD-friendly breakdown

Recording a Meeting

Go to "Live Recording" tab
Click "Start Recording"
Speak or let the meeting record
Click "Stop Recording"
View transcript and AI-generated summary

Asking Questions

Go to "Ask Questions" tab
Type: "Summarize the key points from my PDF notes"
The system automatically filters to only PDF context
Get a precise answer based on your notes

YouTube Video Processing

Go to "Upload Media" tab
Paste a YouTube URL
System downloads and transcribes automatically
Get transcript, summary, flashcards, and quiz

🐛 Troubleshooting

MongoDB Connection Issues

Ensure MongoDB is running locally or Atlas cluster is accessible
Check .env file has correct MONGO_URI
Verify network connectivity

PDF Parsing Errors

Ensure PDF files are not corrupted
Check file size (max 50MB)
Verify pdf-parse package is installed correctly

YouTube Download Failures

Check if video is publicly accessible
Enable fallback options in .env
Verify yt-dlp is installed if using that option

AI API Errors

Verify GROQ_API_KEY is set correctly
Check API quota limits
Ensure internet connection is stable

🤝 Contributing

This project was built as a hackathon submission. Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

This project is open source and available for educational purposes.

🙏 Acknowledgments

Groq for providing fast AI inference
MongoDB for database services
All open-source libraries used in this project

📧 Contact

For questions or support, please open an issue on the repository.

Built with ❤️ for ADHD and Neurodivergent Students

FilesExpand file tree

README.md

Latest commit

History