kqjy/EduCatWeb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
EduCatWeb/README.md
inubimambo df1505bf48 Update README
2025-07-09 22:51:51 +08:00

402 lines
14 KiB
Markdown
Raw Permalink Blame History

# EduCat - AI-Powered Note Revision Platform
EduCat is a modern web application that helps students improve their study notes using AI. Built with Node.js, Express, and EJS, it features secure file upload capabilities, AI-powered note revision, interactive quizzes, and an intelligent chatbot.
## Features
### 🔐 **Security & Authentication**
- Secure login and registration system
- Session-based authentication with flash messages
- Password hashing with bcrypt
- Strict file type whitelisting for secure uploads
### 📁 **Document Processing**
- Upload notes in multiple formats (PDF, DOC, DOCX, XLSX, XLS, TXT, MD, JSON, CSV, XML)
- Secure document extraction with proper error handling
- File preview with extraction information and metadata
- Separate storage for original uploads and AI-revised notes
### 🤖 **AI-Powered Features**
- **Note Revision**: Automatically improve, summarize, and generate study questions
- **Interactive Chatbot**: Chat with AI for study assistance
- **Quiz Generation**: Create interactive quizzes from uploaded documents
- **Smart Content Extraction**: Extract text from various document formats
### 📊 **Dashboard & Management**
- Modern dashboard to manage uploaded files
- Separate sections for original files and AI-revised notes
- File preview with extraction status and metadata
- Download and delete functionality for all file types
### 🎯 **Quiz System**
- Generate quizzes from uploaded documents
- Multiple question types (multiple choice, true/false, short answer)
- Comprehensive quiz review with explanations
- Statistics tracking for quiz performance
### 🎨 **Modern UI/UX**
- Beautiful, responsive design with Bootstrap 5
- Custom SVG favicon and branded interface
- Improved file icons and visual indicators
- Mobile-friendly responsive layout
### 🔗 **AI Integration**
- Connected to Flowise at https://flowise.suika.cc/
- RAG (Retrieval-Augmented Generation) capabilities
- Secure API integration with proper error handling-Powered Note Revision Platform
EduCat is a modern web application that helps students improve their study notes using AI. Built with Node.js, Express, and EJS, it features file upload capabilities, AI-powered note revision, and an interactive chatbot.
## Features
- <20> **User Authentication**: Secure login and registration system
- <20>📁 **File Upload**: Upload notes in various formats (PDF, DOC, TXT, images)
- 🤖 **AI-Powered Revision**: Automatically improve, summarize, and generate study questions
- 💬 **Interactive Chatbot**: Chat with AI for study assistance
- 📊 **Dashboard**: Manage and track your uploaded notes
- 🎨 **Modern UI**: Beautiful, responsive design with Bootstrap
- 🔗 **Flowise Integration**: Connected to Flowise at https://flowise.suika.cc/
## Technologies Used
- **Backend**: Node.js, Express.js
- **Frontend**: EJS templates, Bootstrap 5, Font Awesome
- **Authentication**: bcrypt for password hashing, express-session
- **File Handling**: Multer for secure file uploads with type validation
- **Document Processing**:
- PDFParse for PDF extraction
- Mammoth for Word document processing
- ExcelJS for secure Excel file handling (replaced vulnerable xlsx)
- **AI Integration**: Flowise API integration with RAG capabilities
- **Session Management**: Express Session with flash messages
- **Security**: File type whitelisting, secure extraction methods
- **Styling**: Custom CSS with Bootstrap and custom SVG favicon
## Installation
1. **Clone the repository**:
```bash
git clone <repository-url>
cd EduCat
```
2. **Install dependencies**:
```bash
npm install
```
**Key Dependencies:**
- `express` - Web framework
- `ejs` - Template engine
- `multer` - File upload handling
- `bcrypt` - Password hashing
- `express-session` - Session management
- `pdf-parse` - PDF text extraction
- `mammoth` - Word document processing
- `exceljs` - Secure Excel file handling
- `axios` - HTTP client for API calls
3. **Configure environment variables**:
- Copy `.env.example` to `.env` (if exists) or create a new `.env` file
- Update the following variables:
```
PORT=3000
SESSION_SECRET=your-secret-key-here
FLOWISE_API_URL=https://flowise.suika.cc/api/v1/prediction
FLOWISE_CHATFLOW_ID=your-chatflow-id-here
```
4. **Set up your Flowise chatflow**:
- Go to https://flowise.suika.cc/
- Create or find your chatflow
- Copy the chatflow ID and update it in the `.env` file
5. **Start the application**:
```bash
npm start
```
For development with auto-reload:
```bash
npm run dev
```
6. **Access the application**:
- Open your browser and navigate to `http://localhost:3000`
## Usage
### Authentication
1. Visit `http://localhost:3000`
2. Click "Login" or "Register" to create an account
3. Use demo accounts:
- **Admin**: username `admin`, password `password`
- **Student**: username `student`, password `password`
### Uploading Notes
1. After logging in, click "Upload Notes" in the navigation
2. Drag and drop your file or click to browse
3. Select a supported file type:
- **Documents**: PDF, DOC, DOCX
- **Spreadsheets**: XLSX, XLS
- **Text Files**: TXT, MD, JSON, CSV, XML
4. Click "Upload & Process"
5. View file preview with extraction information
### Revising Notes
1. Go to your Dashboard to see uploaded files
2. Click "Revise with AI" on any file
3. Choose revision type:
- **Improve & Enhance**: Makes notes more comprehensive
- **Summarize**: Creates concise summaries
- **Generate Questions**: Creates study questions
4. Click "Revise with AI" to process
5. Save and download revised notes from the "AI-Revised Notes" section
### Quiz System
1. Upload a document to generate quizzes from
2. Navigate to the quiz section
3. Take interactive quizzes with multiple question types
4. Review answers with detailed explanations
5. Track your quiz performance and statistics
### Using the Chatbot
1. Navigate to the "Chat" section
2. Type your questions about study materials or academic topics
3. Get instant AI-powered responses using RAG technology
## Project Structure
```
EduCat/
├── public/
│ ├── css/
│ │ └── style.css
│ ├── js/
│ │ └── main.js
│ ├── images/
│ │ └── favicon.svg
│ ├── favicon.svg
│ └── favicon-32x32.svg
├── views/
│ ├── partials/
│ │ ├── header.ejs
│ │ └── footer.ejs
│ ├── index.ejs
│ ├── upload.ejs
│ ├── revise.ejs
│ ├── chat.ejs
│ ├── dashboard.ejs
│ ├── quiz.ejs
│ └── error.ejs
├── uploads/
│ └── revised-notes/
├── data/
│ ├── user-files/
│ ├── revised-files/
│ └── quiz-results/
├── server.js
├── package.json
└── .env
```
## API Endpoints
### Authentication & Core Routes
- `GET /` - Home page
- `GET /login` - Login page
- `POST /login` - Handle login
- `GET /register` - Registration page
- `POST /register` - Handle registration
- `GET /logout` - Logout user
### File Management
- `GET /upload` - File upload page
- `POST /upload` - Handle file uploads with validation
- `GET /dashboard` - User dashboard with file management
- `GET /api/files/:fileId/preview` - File preview with extraction info
- `DELETE /api/files/:fileId` - Delete uploaded file
### AI-Powered Features
- `GET /revise/:fileId` - Note revision page
- `POST /api/revise` - AI revision endpoint
- `POST /api/save-revised` - Save revised notes
- `GET /api/download-revised/:fileId` - Download revised notes
- `GET /api/revised-files/:fileId/info` - Get revised file info
- `DELETE /api/revised-files/:fileId` - Delete revised file
### Quiz System
- `GET /quiz` - Quiz interface
- `POST /api/quiz/generate` - Generate quiz from document
- `POST /api/quiz/submit` - Submit quiz answers
- `GET /api/quiz/results` - Get quiz statistics
### Chat Integration
- `GET /chat` - Chat interface
- `POST /api/chat` - Chat API endpoint with RAG support
## Configuration
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `SESSION_SECRET` | Session encryption key | `educat-secret-key` |
| `FLOWISE_API_URL` | Flowise API base URL | `https://flowise.suika.cc/api/v1/prediction` |
| `FLOWISE_CHATFLOW_ID` | Your Flowise chatflow ID | Required |
### File Upload Settings
- **Maximum file size**: 10MB
- **Allowed formats**: PDF, DOC, DOCX, XLSX, XLS, TXT, MD, JSON, CSV, XML
- **Upload directory**: `uploads/` (original files)
- **Revised notes directory**: `uploads/revised-notes/`
- **Security**: Strict file type whitelisting with MIME type validation
- **Processing**: Automatic text extraction with error handling
## Customization
### Styling
- Edit `public/css/style.css` to customize the appearance
- The design uses Bootstrap 5 with custom CSS variables
- Custom SVG favicon and file icons for better visual consistency
- Responsive design optimized for mobile and desktop
### AI Integration
- Modify the Flowise API calls in `server.js`
- Update prompts in the `/api/revise` endpoint
- Customize chat responses in the `/api/chat` endpoint
- Configure RAG settings for document-based queries
### Security
- File type restrictions configured in server.js and main.js
- MIME type validation for uploaded files
- Secure document extraction methods
- Session security with proper secret management
### Adding Features
- Add new routes in `server.js`
- Create corresponding EJS templates in `views/`
- Add client-side JavaScript in `public/js/main.js`
- Update CSS in `public/css/style.css`
## Troubleshooting
### Common Issues
1. **File upload fails**:
- Check file size (max 10MB)
- Verify file format is supported (PDF, DOC, DOCX, XLSX, XLS, TXT, MD, JSON, CSV, XML)
- Ensure `uploads/` and `uploads/revised-notes/` directories exist
- Check file type validation in both client and server
2. **Document extraction errors**:
- Verify document is not corrupted
- Check extraction status in file preview
- Ensure proper permissions for file access
- Review server logs for specific extraction errors
3. **AI responses don't work**:
- Verify Flowise API URL is correct
- Check if your chatflow ID is valid
- Ensure Flowise server is accessible
- Verify RAG configuration for document-based queries
4. **Quiz generation fails**:
- Ensure document has sufficient text content
- Check if document extraction was successful
- Verify AI service is properly connected
- Review quiz generation prompts
5. **Session issues**:
- Verify SESSION_SECRET is set in .env
- Check if sessions are properly configured
- Clear browser cookies and try again
6. **Revised notes not saving**:
- Ensure `uploads/revised-notes/` directory exists
- Check file permissions
- Verify sufficient disk space
- Review server logs for save errors
### Development
To run in development mode with auto-reload:
```bash
npm install -g nodemon
npm run dev
```
## Recent Updates & Security Improvements
### Version 2.0 Security Enhancements
- **🔒 Enhanced Security**: Replaced vulnerable `xlsx` library with secure `exceljs` for Excel processing
- **🛡️ File Type Whitelisting**: Implemented strict file type validation to prevent malicious uploads
- **🔍 MIME Type Validation**: Added comprehensive file type checking on both client and server
- **🗂️ Secure Document Processing**: Improved extraction methods with proper error handling
### UI/UX Improvements
- **🎨 Custom Favicon**: Added custom SVG favicon for brand consistency
- **📱 Responsive Design**: Enhanced mobile-friendly interface with improved layouts
- **🔧 File Icons**: Updated file type icons for better visual clarity
- **📊 Dashboard Enhancements**: Separate sections for original and revised files
- **🏷️ Badge System**: Improved status indicators and badge alignment
### New Features
- **💾 Revised Notes Management**: Save, download, and manage AI-revised notes separately
- **🎯 Enhanced Quiz System**: Fixed short-answer questions with explanations
- **📈 Quiz Statistics**: Comprehensive tracking of quiz performance
- **🔍 File Preview**: Detailed extraction information and metadata display
- **📁 Persistent Storage**: Improved file tracking and session management
### Performance & Reliability
- **⚡ Optimized Extraction**: Faster and more reliable document processing
- **🔄 Error Handling**: Comprehensive error handling for all file operations
- **💪 Robust API**: Improved API endpoints with better validation
- **🧹 Code Refactoring**: Cleaner, more maintainable codebase
## Deployment & Production
### Production Considerations
- Set strong `SESSION_SECRET` in production environment
- Configure proper file upload limits based on server capacity
- Set up proper logging and monitoring
- Implement rate limiting for API endpoints
- Configure HTTPS for secure file uploads
- Set up backup procedures for uploaded files and data
### Environment Setup
- Ensure Node.js 14+ is installed
- Create proper directory structure with correct permissions
- Configure environment variables for production
- Set up reverse proxy (nginx/Apache) if needed
- Configure SSL certificates for HTTPS
### Monitoring & Maintenance
- Monitor disk space for uploads directory
- Set up log rotation for application logs
- Regular security updates for dependencies
- Monitor API usage and performance
- Backup user data and quiz results regularly
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
## License
This project is licensed under the MIT License.
## Support
For support or questions, please contact the EduCat development team.
---
**Made with ❤️ by the EduCat Team**
Reference in New Issue View Git Blame Copy Permalink