diff --git a/README.md b/README.md index 18de5f7..a248f54 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,958 @@ -# πŸš€ ThonHub +# πŸš€ ThonHub - ML Simulator Platform -ThonHub is a GenAI-powered **Hackathon Collaboration Hub** that connects **students, developers, and organizations**. -It makes hackathons easier to explore, join, and manage β€” with teammate matching, AI-powered assistance, project tracking, and organizational tools for universities/companies. +
+ +![ThonHub Banner](https://via.placeholder.com/1200x300/667eea/ffffff?text=ThonHub+ML+Simulator) + +[![Hacktoberfest](https://img.shields.io/badge/Hacktoberfest-2025-orange?style=for-the-badge&logo=hacktoberfest)](https://hacktoberfest.com) +[![GitHub issues](https://img.shields.io/github/issues/GDGoC-GLAU/ThonHub?style=for-the-badge)](https://github.com/GDGoC-GLAU/ThonHub/issues) +[![GitHub stars](https://img.shields.io/github/stars/GDGoC-GLAU/ThonHub?style=for-the-badge)](https://github.com/GDGoC-GLAU/ThonHub/stargazers) +[![GitHub forks](https://img.shields.io/github/forks/GDGoC-GLAU/ThonHub?style=for-the-badge)](https://github.com/GDGoC-GLAU/ThonHub/network) +[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](LICENSE) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](CONTRIBUTING.md) + +**An interactive machine learning simulator for education and experimentation** + +[🎯 Features](#-features) β€’ [πŸ› οΈ Tech Stack](#️-tech-stack) β€’ [πŸš€ Getting Started](#-getting-started) β€’ [πŸ“š Documentation](#-documentation) β€’ [🀝 Contributing](#-contributing) + +
+ +--- + +## πŸ“‹ Table of Contents + +- [Overview](#-overview) +- [Features](#-features) +- [Tech Stack](#️-tech-stack) +- [Project Structure](#-project-structure) +- [Getting Started](#-getting-started) + - [Prerequisites](#prerequisites) + - [Installation](#installation) + - [Running Locally](#running-locally) +- [API Documentation](#-api-documentation) +- [Model Documentation](#-model-documentation) +- [Usage Examples](#-usage-examples) +- [Contributing](#-contributing) +- [Code of Conduct](#code-of-conduct) +- [Troubleshooting](#-troubleshooting) +- [Roadmap](#-roadmap) +- [Contributors](#-contributors) +- [License](#-license) +- [Acknowledgments](#-acknowledgments) +- [Support](#-support) + +--- + +## 🎯 Overview + +**ThonHub** is a comprehensive, open-source machine learning simulator platform designed to democratize ML education. Built for students, educators, and ML enthusiasts, ThonHub provides an intuitive interface to learn, experiment, and master various machine learning algorithms without writing complex code. + +### 🌟 Why ThonHub? + +- πŸŽ“ **Learn by Doing**: Interactive hands-on experience with real ML algorithms +- πŸ”§ **Zero Setup Required**: Web-based platform, no local installations needed +- πŸ“Š **Visual Learning**: Real-time charts, plots, and performance metrics +- πŸ€– **AI-Powered Insights**: Resume analysis and intelligent recommendations +- πŸ“± **Cross-Platform**: Works on desktop, tablet, and mobile devices +- 🌍 **Open Source**: Free forever, community-driven development + +### 🎯 Perfect For + +- πŸ“š Students learning machine learning concepts +- πŸ‘¨β€πŸ« Educators teaching data science courses +- πŸ”¬ Researchers experimenting with algorithms +- πŸ’Ό Professionals upskilling in ML +- πŸš€ Anyone curious about artificial intelligence --- ## ✨ Features -### πŸ‘©β€πŸ’» For Students & Developers -- πŸ” **Search & Filter Hackathons** – with reminders + calendar integration -- πŸ‘₯ **Teammate Finder** – smart ranking based on GitHub, LinkedIn, and skills -- πŸ’¬ **Chat + AI Copilot** – discuss ideas, resolve queries, and get AI suggestions -- πŸ† **Profiles & Badges** – showcase hackathon history, badges, and AI-analyzed resumes -- πŸ“… **Personal Hackathon Page** – manage team, project details, and custom notes +### πŸ€– Machine Learning Models + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AlgorithmTypeUse CasesDifficulty
Logistic RegressionClassificationDisease prediction, spam detection, customer churn🟒 Beginner
Linear RegressionRegressionPrice prediction, sales forecasting, trend analysis🟒 Beginner
Decision TreeBothCredit approval, medical diagnosis, rule extraction🟑 Intermediate
Random ForestEnsembleComplex classification, feature importance🟑 Intermediate
K-Nearest NeighborsBothRecommendation systems, pattern recognition🟒 Beginner
Support Vector MachineClassificationText classification, image recognitionπŸ”΄ Advanced
+ +### 🎨 Platform Features + +#### πŸ“Š Data Management +- βœ… **CSV Upload**: Upload your own datasets +- βœ… **Sample Datasets**: Pre-loaded datasets for quick start +- βœ… **Data Preview**: View and explore your data before training +- βœ… **Missing Value Handling**: Automatic data cleaning +- βœ… **Feature Selection**: Choose relevant features for training + +#### 🧠 Model Training +- βœ… **Interactive Parameters**: Adjust hyperparameters in real-time +- βœ… **Train/Test Split**: Configurable data splitting +- βœ… **Progress Tracking**: Real-time training status +- βœ… **Model Comparison**: Compare multiple models side-by-side +- βœ… **Save Models**: Export trained models for later use + +#### πŸ“ˆ Visualizations +- βœ… **Confusion Matrix**: Interactive heatmap for classification +- βœ… **ROC Curve**: AUC-ROC analysis with interpretation +- βœ… **Feature Importance**: Identify key predictive features +- βœ… **Prediction Distribution**: Probability histograms +- βœ… **Residual Plots**: For regression analysis +- βœ… **Learning Curves**: Model performance over time + +#### πŸ“Š Performance Metrics +- βœ… **Accuracy Score**: Overall prediction accuracy +- βœ… **Precision & Recall**: Class-specific metrics +- βœ… **F1-Score**: Harmonic mean of precision and recall +- βœ… **AUC-ROC**: Area under the curve analysis +- βœ… **RΒ² Score**: Regression model fit (for regression) +- βœ… **MSE/RMSE/MAE**: Error metrics (for regression) -### 🏒 For Organizations -- πŸ› οΈ **Launch & Manage Hackathons** – create and organize events -- πŸ“Š **Participation Analytics** – track hackathon stats (via Streamlit dashboard) -- πŸŽ“ **Talent Discovery** – access student developer records for placements/internships -- πŸ“’ **Announcements & Reminders** – send updates to participants +#### πŸ€– AI Features +- βœ… **Resume Upload & Analysis**: AI-powered resume scoring +- βœ… **Skill Detection**: Automatic skill extraction +- βœ… **Career Recommendations**: Job role suggestions +- βœ… **Strength Analysis**: Identify resume strengths +- βœ… **Improvement Suggestions**: Actionable feedback + +#### πŸ“₯ Export & Sharing +- βœ… **Download Reports**: Export analysis as JSON/CSV +- βœ… **Share Results**: Generate shareable links +- βœ… **Model Export**: Save trained models +- βœ… **Screenshot Capture**: Save visualizations --- -## πŸ—οΈ Tech Stack +## πŸ› οΈ Tech Stack + +### Frontend Technologies + +![React](https://img.shields.io/badge/React-18.2.0-61DAFB?style=flat-square&logo=react&logoColor=white) +![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=flat-square&logo=javascript&logoColor=black) +![HTML5](https://img.shields.io/badge/HTML5-E34F26?style=flat-square&logo=html5&logoColor=white) +![CSS3](https://img.shields.io/badge/CSS3-1572B6?style=flat-square&logo=css3&logoColor=white) +![Axios](https://img.shields.io/badge/Axios-1.6.0-5A29E4?style=flat-square&logo=axios&logoColor=white) +![React Router](https://img.shields.io/badge/React_Router-6.0-CA4245?style=flat-square&logo=react-router&logoColor=white) + +**Libraries:** +- **Axios** - HTTP client for API communication +- **React Router** - Client-side routing +- **Chart.js / Plotly** - Interactive visualizations +- **Bootstrap / Tailwind** - UI components and styling + +### Backend Technologies + +![Python](https://img.shields.io/badge/Python-3.9+-3776AB?style=flat-square&logo=python&logoColor=white) +![Flask](https://img.shields.io/badge/Flask-3.0.0-000000?style=flat-square&logo=flask&logoColor=white) +![Scikit-learn](https://img.shields.io/badge/Scikit--learn-1.3.0-F7931E?style=flat-square&logo=scikit-learn&logoColor=white) +![Pandas](https://img.shields.io/badge/Pandas-2.0.0-150458?style=flat-square&logo=pandas&logoColor=white) +![NumPy](https://img.shields.io/badge/NumPy-1.24.0-013243?style=flat-square&logo=numpy&logoColor=white) + +**Libraries:** +- **Flask** - Web framework for REST API +- **Flask-CORS** - Cross-Origin Resource Sharing +- **Scikit-learn** - Machine learning algorithms +- **Pandas** - Data manipulation and analysis +- **NumPy** - Numerical computing +- **PyPDF2** - PDF text extraction +- **python-docx** - DOCX file processing -- **Frontend:** React + Tailwind CSS -- **Backend:** Flask (REST APIs) -- **Database:** MongoDB -- **Async Tasks & Notifications:** Redis + Celery -- **AI Copilot:** OpenAI / LangChain (pluggable module) -- **Analytics Dashboard:** Streamlit +### Visualization & Analysis + +![Plotly](https://img.shields.io/badge/Plotly-5.17.0-3F4F75?style=flat-square&logo=plotly&logoColor=white) +![Matplotlib](https://img.shields.io/badge/Matplotlib-3.7.0-11557c?style=flat-square) +![Seaborn](https://img.shields.io/badge/Seaborn-0.12.0-3776AB?style=flat-square) + +**Libraries:** +- **Plotly** - Interactive plots and charts +- **Matplotlib** - Static visualizations +- **Seaborn** - Statistical data visualization + +### Development & DevOps + +![Git](https://img.shields.io/badge/Git-F05032?style=flat-square&logo=git&logoColor=white) +![GitHub](https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white) +![VS Code](https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visual-studio-code&logoColor=white) +![npm](https://img.shields.io/badge/npm-CB3837?style=flat-square&logo=npm&logoColor=white) +![Postman](https://img.shields.io/badge/Postman-FF6C37?style=flat-square&logo=postman&logoColor=white) + +**Tools:** +- **Git** - Version control +- **GitHub** - Code hosting and collaboration +- **VS Code** - Code editor +- **npm** - Package management +- **Postman** - API testing --- -## πŸ“‚ Project Structure (Initial Setup) +## πŸ“ Project Structure ThonHub/ -│── backend/ # Flask backend -β”‚ β”œβ”€β”€ app.py -β”‚ β”œβ”€β”€ routes/ -β”‚ β”œβ”€β”€ models/ -β”‚ β”œβ”€β”€ services/ -β”‚ └── utils/ β”‚ -│── frontend/ # React frontend -β”‚ β”œβ”€β”€ public/ -β”‚ └── src/ -β”‚ β”œβ”€β”€ components/ -β”‚ β”œβ”€β”€ pages/ -β”‚ β”œβ”€β”€ hooks/ -β”‚ └── App.js +β”œβ”€β”€ πŸ“‚ .github/ # GitHub configuration +β”‚ β”œβ”€β”€ ISSUE_TEMPLATE/ # Issue templates +β”‚ β”œβ”€β”€ PULL_REQUEST_TEMPLATE.md # PR template +β”‚ └── workflows/ # GitHub Actions (CI/CD) +β”‚ +β”œβ”€β”€ πŸ“‚ backend/ # Backend API (Python/Flask) +init.py +β”‚ β”œβ”€β”€ πŸ“„ app.py # Main Flask application +β”‚ β”œβ”€β”€ πŸ“„ config.py # Configuration settings +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ routes/ # API route handlers +init.py +β”‚ β”‚ β”œβ”€β”€ πŸ“„ ml_routes.py # ML model training routes +β”‚ β”‚ β”œβ”€β”€ πŸ“„ resume_routes.py # Resume upload/analysis routes +β”‚ β”‚ β”œβ”€β”€ πŸ“„ auth_routes.py # Authentication routes +β”‚ β”‚ └── πŸ“„ data_routes.py # Dataset management routes +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ services/ # Business logic layer +init.py +β”‚ β”‚ β”œβ”€β”€ πŸ“„ ml_trainer.py # ML model training service +β”‚ β”‚ β”œβ”€β”€ πŸ“„ resume_analyzer.py # Resume analysis service +β”‚ β”‚ β”œβ”€β”€ πŸ“„ data_processor.py # Data preprocessing +β”‚ β”‚ └── πŸ“„ visualization.py # Chart generation +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ models/ # Database models (SQLAlchemy) +init.py +β”‚ β”‚ β”œβ”€β”€ πŸ“„ user.py # User model +β”‚ β”‚ β”œβ”€β”€ πŸ“„ resume.py # Resume model +β”‚ β”‚ └── πŸ“„ ml_model.py # ML model metadata +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ utils/ # Utility functions +init.py +β”‚ β”‚ β”œβ”€β”€ πŸ“„ validators.py # Input validation +β”‚ β”‚ β”œβ”€β”€ πŸ“„ helpers.py # Helper functions +β”‚ β”‚ └── πŸ“„ decorators.py # Custom decorators +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ uploads/ # File upload storage +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ datasets/ # Uploaded datasets +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ resumes/ # Uploaded resumes +β”‚ β”‚ └── πŸ“„ .gitkeep +β”‚ β”‚ +β”‚ └── πŸ“‚ tests/ # Backend unit tests +β”‚ β”œβ”€β”€ πŸ“„ test_ml.py +β”‚ β”œβ”€β”€ πŸ“„ test_resume.py +β”‚ └── πŸ“„ test_api.py β”‚ -│── analytics/ # Streamlit dashboards -β”‚ └── dashboard.py +β”œβ”€β”€ πŸ“‚ frontend/ # Frontend application (React) +β”‚ β”œβ”€β”€ πŸ“‚ public/ # Static assets +β”‚ β”‚ β”œβ”€β”€ πŸ“„ index.html +β”‚ β”‚ β”œβ”€β”€ πŸ“„ favicon.ico +β”‚ β”‚ β”œβ”€β”€ πŸ“„ manifest.json +β”‚ β”‚ └── πŸ“‚ images/ +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“‚ src/ # Source code +β”‚ β”‚ β”œβ”€β”€ πŸ“„ App.js # Main app component +β”‚ β”‚ β”œβ”€β”€ πŸ“„ index.js # Entry point +β”‚ β”‚ β”œβ”€β”€ πŸ“„ App.css # Global styles +β”‚ β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ components/ # Reusable components +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ Navbar.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ Footer.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ ModelCard.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ DataUpload.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ ResumeUpload.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ ConfusionMatrix.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ ROCCurve.jsx +β”‚ β”‚ β”‚ └── πŸ“„ MetricsCard.jsx +β”‚ β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ pages/ # Page components +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ HomePage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ ProfilePage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ LogisticRegressionPage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ LinearRegressionPage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ DecisionTreePage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ RandomForestPage.jsx +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ KNNPage.jsx +β”‚ β”‚ β”‚ └── πŸ“„ SVMPage.jsx +β”‚ β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ utils/ # Utility functions +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ api.js # Base Axios configuration +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ mlApi.js # ML-specific API calls +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ resumeApi.js # Resume API calls +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ authApi.js # Authentication API +β”‚ β”‚ β”‚ └── πŸ“„ helpers.js # Helper functions +β”‚ β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ hooks/ # Custom React hooks +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ useAuth.js +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ useModel.js +β”‚ β”‚ β”‚ └── πŸ“„ useUpload.js +β”‚ β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ πŸ“‚ context/ # React Context +β”‚ β”‚ β”‚ β”œβ”€β”€ πŸ“„ AuthContext.js +β”‚ β”‚ β”‚ └── πŸ“„ ModelContext.js +β”‚ β”‚ β”‚ +β”‚ β”‚ └── πŸ“‚ styles/ # Component styles +β”‚ β”‚ β”œβ”€β”€ πŸ“„ components.css +β”‚ β”‚ └── πŸ“„ pages.css +β”‚ β”‚ +β”‚ β”œβ”€β”€ πŸ“„ package.json # Frontend dependencies +β”‚ β”œβ”€β”€ πŸ“„ package-lock.json +β”‚ └── πŸ“„ .env.example # Environment variables template β”‚ -│── CONTRIBUTING.md -│── README.md -│── requirements.txt -│── package.json +β”œβ”€β”€ πŸ“‚ docs/ # Comprehensive documentation +β”‚ β”œβ”€β”€ πŸ“„ README.md # Documentation overview +β”‚ β”œβ”€β”€ πŸ“„ logistic_regression.md # Logistic Regression guide +β”‚ β”œβ”€β”€ πŸ“„ linear_regression.md # Linear Regression guide +β”‚ β”œβ”€β”€ πŸ“„ decision_tree.md # Decision Tree guide +β”‚ β”œβ”€β”€ πŸ“„ random_forest.md # Random Forest guide +β”‚ β”œβ”€β”€ πŸ“„ knn.md # KNN guide +β”‚ β”œβ”€β”€ πŸ“„ svm.md # SVM guide +β”‚ └── πŸ“‚ assets/ # Documentation images +β”‚ β”œβ”€β”€ πŸ“‚ logistic_regression/ +β”‚ β”œβ”€β”€ πŸ“‚ linear_regression/ +β”‚ └── ... +β”‚ +β”œβ”€β”€ πŸ“„ .gitignore # Git ignore rules +β”œβ”€β”€ πŸ“„ LICENSE # MIT License +β”œβ”€β”€ πŸ“„ README.md # This file +β”œβ”€β”€ πŸ“„ CONTRIBUTING.md # Contribution guidelines +β”œβ”€β”€ πŸ“„ CODE_OF_CONDUCT.md # Code of conduct +β”œβ”€β”€ πŸ“„ requirements.txt # Python dependencies + + --- ## πŸš€ Getting Started -### Backend (Flask) +### Prerequisites + +Before setting up ThonHub, ensure you have the following installed: + +| Software | Version | Download Link | +|----------|---------|---------------| +| **Node.js** | β‰₯ 16.0.0 | [nodejs.org](https://nodejs.org/) | +| **Python** | β‰₯ 3.9.0 | [python.org](https://www.python.org/) | +| **npm** | β‰₯ 8.0.0 | Comes with Node.js | +| **Git** | Latest | [git-scm.com](https://git-scm.com/) | +| **pip** | Latest | Comes with Python | + +**Optional but Recommended:** +- **VS Code** - [Download](https://code.visualstudio.com/) +- **Postman** - [Download](https://www.postman.com/) +- **Python venv** - For virtual environments + +### Installation + +#### Step 1: Clone the Repository + +Clone via HTTPS +git clone https://github.com/GDGoC-GLAU/ThonHub.git + +OR clone via SSH +git clone git@github.com:GDGoC-GLAU/ThonHub.git + +Navigate to project directory +cd ThonHub + +text + +#### Step 2: Backend Setup + +Navigate to backend directory cd backend + +Create a virtual environment (recommended) +python -m venv venv + +Activate virtual environment +On Windows: venv\Scripts\activate + +On macOS/Linux: +source venv/bin/activate + +Upgrade pip +python -m pip install --upgrade pip + +Install Python dependencies pip install -r requirements.txt -python wsgi.py -### Frontend (React) +Create uploads directories +mkdir -p uploads/datasets uploads/resumes + +Create environment file +cp .env.example .env + +Edit .env file with your configuration +Set SECRET_KEY, DATABASE_URL, etc. +text + +**Backend `.env` Configuration:** +FLASK_APP=app.py +FLASK_ENV=development +SECRET_KEY=your-secret-key-here +DATABASE_URL=sqlite:///thonhub.db +UPLOAD_FOLDER=uploads +MAX_CONTENT_LENGTH=16777216 # 16MB +http://localhost:3000 + +text + +#### Step 3: Frontend Setup + +Navigate to frontend directory (from root) cd frontend + +Install Node.js dependencies npm install + +Create environment file +cp .env.example .env + +Edit .env with your API configuration +text + +**Frontend `.env` Configuration:** +REACT_APP_API_BASE_URL=http://localhost:5000/api +REACT_APP_API_TIMEOUT=30000 +text + +### Running Locally + +#### πŸ”Ή Start Backend Server + +From backend directory +cd backend + +Activate virtual environment (if not already active) +Windows: +venv\Scripts\activate + +macOS/Linux: +source venv/bin/activate + +Run Flask application +python app.py + +Or use Flask CLI +flask run + +Backend server will start on: http://localhost:5000 +text + +**Expected Output:** +Running on http://127.0.0.1:5000 + +Debugger is active! + +Debugger PIN: xxx-xxx-xxx + +text + +#### πŸ”Ή Start Frontend Development Server + +From frontend directory (open new terminal) +cd frontend + +Start React development server npm start -### Analytics (Streamlit) -cd analytics +Frontend will automatically open at: http://localhost:3000 +text + +**Expected Output:** +Compiled successfully! + +You can now view thonhub in the browser. + +Local: http://localhost:3000 +On Your Networkhttp://192.168.1.x:3000 + +text + +#### πŸŽ‰ Access the Application + +- **Frontend (User Interface)**: [http://localhost:3000](http://localhost:3000) +- **Backend (API)**: [http://localhost:5000](http://localhost:5000) +- **API Documentation**: [http://localhost:5000/api/docs](http://localhost:5000/api/docs) + +--- + +## πŸ“‘ API Documentation + +### Base URL + +http://localhost:5000/api + +text + +### Authentication + +Most endpoints require JWT authentication. Include the token in the header: + +Authorization: Bearer + +text + +### Machine Learning Endpoints + +#### Train Model + +POST /api/models/{model_type}/train +Content-Type: appli + +{ +"features": ["feature1", "feature2" +, "target": "target_colu +n", "test_size" +0.2, "parame +ers": { "max +i +text + +**Response:** +{ +"success": tru +, "data +: { "accuracy +: 0.95, "confusion_matrix": [, ], +1][2][3][4] +roc_auc": 0. +2, "metrics": +"precisi +n": 0.94, +r +c +text + +#### Predict + +POST /api/models/{model_type}/predict +{ +"features": [value1, value2, value +text + +### Resume Endpoints + +#### Upload Resume + +POST /api/resume/upload +Content-T + +file: [binary-resume-file] + +text + +**Response:** +{ +"success": tru +, "filename": "resume.p +f", "analys +s": { "s +ore": 85, "skills": ["Python", "React", "Machi +e Learning"], "experience_l +v +text + +### Data Endpoints + +#### Upload Dataset + +POST /api/data/upload +Content-Typ + +file: [binary-csv-file] + +text + +#### Get Sample Dataset + +GET /api/data/sample/{dataset_name} + +text + +--- + +## πŸ“š Model Documentation + +Comprehensive documentation for each ML model: + +### Quick Access + +| Model | Documentation | Complexity | Best For | +|-------|---------------|------------|----------| +| **Logistic Regression** | [πŸ“– View Docs](docs/logistic_regression.md) | 🟒 Beginner | Binary classification | +| **Linear Regression** | [πŸ“– View Docs](docs/linear_regression.md) | 🟒 Beginner | Continuous prediction | +| **Decision Tree** | [πŸ“– View Docs](docs/decision_tree.md) | 🟑 Intermediate | Interpretable models | +| **Random Forest** | [πŸ“– View Docs](docs/random_forest.md) | 🟑 Intermediate | Robust classification | +| **K-Nearest Neighbors** | [πŸ“– View Docs](docs/knn.md) | 🟒 Beginner | Pattern recognition | +| **Support Vector Machine** | [πŸ“– View Docs](docs/svm.md) | πŸ”΄ Advanced | Complex boundaries | + +### Documentation Includes + +Each model documentation provides: + +βœ… **Overview** - What the model does and when to use it +βœ… **How to Run** - Step-by-step usage instructions +βœ… **Parameters** - Detailed explanation of all parameters +βœ… **Visualizations** - How to interpret each plot +βœ… **Metrics** - Understanding performance indicators +βœ… **Best Practices** - Tips for optimal results +βœ… **Troubleshooting** - Common issues and solutions +βœ… **Examples** - Real-world use cases + +--- + +## πŸ’‘ Usage Examples + +### Example 1: Train Logistic Regression Model + +// Frontend Code +import mlApi from + +const trainModel = async () => { +const trainingData = +{ features: ['age', 'income', 'credit_sc +re'], target: 'loan_ +pproved', t +st_size: 0.2, +parameters: +{ + +const response = await mlApi.trainLogisticRegression(trainingData); + +if (response.success) { +console.log('Accuracy:', response.data.accura +y); console.log('AUC Score:', response.data.r +c +text + +### Example 2: Upload and Analyze Resume + +// Frontend Code +import resumeApi from './ + +const analyzeResume = async (file) => { +const response = await resumeApi.uploadResume(file, (progress) => +Upload progress: ${progress}%); +if (response.success) { +console.log('Score:', response.data.analysis.sco +e); console.log('Skills:', response.data.analysis. +k +text + +### Example 3: Using the Python Backend + +Backend Code +from services.ml_trainer import MLTrainer +Load data +df = pd.read_csv('data.csv') + +Initialize trainer +trainer = MLTrainer(model_type='logistic_regression') + +Train model +results = trainer.train( +X=df[['feature1', 'feature2 +]], y=df['t +rget'], t +print(f"Accuracy: {results['accuracy']}") +print(f"AUC: {results['roc_a + +text + +--- + +## 🀝 Contributing + +We ❀️ contributions! ThonHub is an open-source project and welcomes contributions from developers of all skill levels. + +### How to Contribute + +#### 1️⃣ Fork the Repository + +Click the "Fork" button at the top-right of this page. + +#### 2️⃣ Clone Your Fork + +git clone https://github.com/YOUR-USERNAME/ThonHub.git +cd ThonHu + +text + +#### 3️⃣ Create a Branch + +Create a new branch for your feature +git checkout -b feature/your-feature-name + +Or for bug fixes +git checkout -b fix/bug-description + +text + +#### 4️⃣ Make Your Changes + +- Write clean, readable code +- Follow existing code style +- Add comments where necessary +- Update documentation if needed + +#### 5️⃣ Test Your Changes + +Backend tests +cd backend +python -m py + +Frontend tests +cd frontend +text + +#### 6️⃣ Commit Your Changes + +git add . +git commit -m "Add: Brief description of you + +text + +**Commit Message Guidelines:** +- `Add:` for new features +- `Fix:` for bug fixes +- `Update:` for updates to existing features +- `Docs:` for documentation changes +- `Refactor:` for code refactoring +- `Test:` for adding tests + +#### 7️⃣ Push to Your Fork + +git push origin feature/your-feature-name + +text + +#### 8️⃣ Create a Pull Request + +1. Go to the original ThonHub repository +2. Click "New Pull Request" +3. Select your fork and branch +4. Fill in the PR template with: + - Description of changes + - Issue number (if applicable) + - Screenshots (if UI changes) + - Testing done + +### Contribution Guidelines + +πŸ“– **Read** [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines + +βœ… **Code Quality** +- Follow PEP 8 for Python code +- Use ES6+ standards for JavaScript +- Write meaningful variable and function names +- Add comments for complex logic + +βœ… **Testing** +- Write unit tests for new features +- Ensure all existing tests pass +- Test on multiple browsers (Chrome, Firefox, Safari) + +βœ… **Documentation** +- Update README if you add features +- Add docstrings to functions +- Update API documentation for new endpoints + +βœ… **Pull Request** +- Link related issues +- Provide clear description +- Include screenshots for UI changes +- Be responsive to feedback + +### Good First Issues + +Looking for a place to start? Check out issues labeled: +- [`good first issue`](https://github.com/GDGoC-GLAU/ThonHub/labels/good%20first%20issue) +- [`beginner-friendly`](https://github.com/GDGoC-GLAU/ThonHub/labels/beginner-friendly) +- [`documentation`](https://github.com/GDGoC-GLAU/ThonHub/labels/documentation) + +### Hacktoberfest + +ThonHub participates in Hacktoberfest! πŸŽƒ + +- Look for issues tagged [`hacktoberfest`](https://github.com/GDGoC-GLAU/ThonHub/labels/hacktoberfest) +- Valid PRs count toward your Hacktoberfest goal +- Follow quality guidelines for PR acceptance + +--- + +## πŸ“œ Code of Conduct + +We are committed to providing a welcoming and inclusive experience for everyone. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing. + +**Our Standards:** +- βœ… Be respectful and inclusive +- βœ… Welcome newcomers +- βœ… Accept constructive criticism +- βœ… Focus on what's best for the community +- ❌ No harassment or discrimination +- ❌ No trolling or insulting comments + +--- + +## πŸ› Troubleshooting + +### Common Issues and Solutions + +#### Backend Issues + +**Issue: `ModuleNotFoundError: No module named 'flask'`** + +Solution: Install dependencies pip install -r requirements.txt -streamlit run dashboard.py +text + +**Issue: Port 5000 already in use** + +Solution: Change port in app.py or kill the process +Windows: +netstat -ano | findstr :5000 +tas /F + +macOS/Linux: +lsof -ti:5000 | xargs kill -9 + +text + +**Issue: CORS errors** + +Solution: Ensure Flask-CORS is installed and configured +pip install flask-cors + +In app.py: +from flask_cors import CORS +text + +#### Frontend Issues + +**Issue: `npm install` fails** + +Solution: Clear cache and retry +npm cache clean --force +rm -rf node_modules package-lock.json +text + +**Issue: API connection refused** + +Solution: Ensure backend is running +Check .env file has correct API_BASE_URL +REACT_APP_API_BASE_URL=http://localhost:5000/api + +text + +**Issue: React app won't start** + +Solution: Check if port 3000 is free +Kill process on port 3000 +Windows: +netstat -ano | findstr :3000 + /F + +macOS/Linux: +lsof -ti:3000 | xargs kill -9 + +text + +### Getting Help + +- πŸ“ [Open an issue](https://github.com/GDGoC-GLAU/ThonHub/issues/new) +- πŸ’¬ Join our [Discord community](#) +- πŸ“§ Email: support@thonhub.com +- πŸ“š Check [documentation](docs/) + +--- + +## πŸ—ΊοΈ Roadmap + +### Version 1.1 (Q1 2026) +- [ ] User authentication and profiles +- [ ] Model comparison dashboard +- [ ] Export trained models (pickle/joblib) +- [ ] API rate limiting +- [ ] Enhanced resume parser (work experience, education) + +### Version 1.2 (Q2 2026) +- [ ] Neural Networks support +- [ ] Deep Learning models (CNN, RNN) +- [ ] Real-time collaboration +- [ ] Model deployment to cloud +- [ ] Mobile app (React Native) + +### Version 2.0 (Q3 2026) +- [ ] AutoML capabilities +- [ ] Hyperparameter tuning automation +- [ ] Model explainability (SHAP, LIME) +- [ ] Time series analysis +- [ ] Natural Language Processing models + +### Future Ideas +- [ ] Jupyter Notebook integration +- [ ] Video tutorials +- [ ] Certification courses +- [ ] Community datasets library +- [ ] Model marketplace + +**Want to see a feature?** [Suggest it here](https://github.com/GDGoC-GLAU/ThonHub/issues/new?labels=enhancement) + +--- + +## πŸ‘₯ Contributors + +Thanks to all our amazing contributors! πŸŽ‰ + + + + + +### How to Become a Contributor + +1. Fork the repository +2. Make meaningful contributions +3. Submit quality pull requests +4. Get your PR merged +5. You'll be automatically added to contributors! + +--- + +## πŸ“„ License + +This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. diff --git a/backend/app/__init__.py b/backend/app/__init__.py index 943f0c8..9487bbb 100644 --- a/backend/app/__init__.py +++ b/backend/app/__init__.py @@ -3,6 +3,18 @@ from dotenv import load_dotenv import os +from flask import Flask +from flask_cors import CORS +from routes.resume_routes import resume_bp + +app = Flask(__name__) +CORS(app) + +# Register resume blueprint +app.register_blueprint(resume_bp, url_prefix='/api/resume') + +# ... rest of your existing code + def create_app(): # Load environment variables load_dotenv() diff --git a/backend/app/models/resume_model.py b/backend/app/models/resume_model.py new file mode 100644 index 0000000..a663787 --- /dev/null +++ b/backend/app/models/resume_model.py @@ -0,0 +1,22 @@ +""" +Resume Database Model +Author: Akshit +""" + +from datetime import datetime +from flask_sqlalchemy import SQLAlchemy + +db = SQLAlchemy() + +class Resume(db.Model): + """Resume model for database""" + id = db.Column(db.Integer, primary_key=True) + user_id = db.Column(db.Integer, db.ForeignKey('user.id'), nullable=False) + filename = db.Column(db.String(255), nullable=False) + filepath = db.Column(db.String(500), nullable=False) + upload_date = db.Column(db.DateTime, default=datetime.utcnow) + analysis_score = db.Column(db.Integer) + skills = db.Column(db.JSON) + + def __repr__(self): + return f'' diff --git a/backend/app/routes/resume_routes.py b/backend/app/routes/resume_routes.py new file mode 100644 index 0000000..aa26903 --- /dev/null +++ b/backend/app/routes/resume_routes.py @@ -0,0 +1,59 @@ +""" +Resume Upload Routes +Author: Akshit +Date: October 13, 2025 +""" + +from flask import Blueprint, request, jsonify +from werkzeug.utils import secure_filename +import os +from services.resume_analyzer import ResumeAnalyzer + +resume_bp = Blueprint('resume', __name__) +UPLOAD_FOLDER = 'backend/uploads' +ALLOWED_EXTENSIONS = {'pdf', 'docx', 'txt'} + +def allowed_file(filename): + return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS + +@resume_bp.route('/upload', methods=['POST']) +def upload_resume(): + """Upload and analyze resume""" + if 'file' not in request.files: + return jsonify({'error': 'No file provided'}), 400 + + file = request.files['file'] + + if file.filename == '': + return jsonify({'error': 'No file selected'}), 400 + + if file and allowed_file(file.filename): + filename = secure_filename(file.filename) + filepath = os.path.join(UPLOAD_FOLDER, filename) + file.save(filepath) + + # Analyze resume + analyzer = ResumeAnalyzer() + analysis = analyzer.analyze_file(filepath) + + return jsonify({ + 'success': True, + 'filename': filename, + 'analysis': analysis + }), 200 + + return jsonify({'error': 'Invalid file type'}), 400 + +@resume_bp.route('/analyze', methods=['POST']) +def analyze_resume(): + """Analyze resume text""" + data = request.json + text = data.get('text', '') + + analyzer = ResumeAnalyzer() + analysis = analyzer.analyze_text(text) + + return jsonify({ + 'success': True, + 'analysis': analysis + }), 200 diff --git a/backend/app/services/resume_analyzer.py b/backend/app/services/resume_analyzer.py new file mode 100644 index 0000000..8b80bf1 --- /dev/null +++ b/backend/app/services/resume_analyzer.py @@ -0,0 +1,78 @@ +""" +AI Resume Analyzer Service +Author: Akshit +Date: October 13, 2025 +""" + +import PyPDF2 +import docx +import re +from collections import Counter + +class ResumeAnalyzer: + def __init__(self): + self.tech_skills = [ + 'Python', 'Java', 'JavaScript', 'React', 'Node.js', + 'SQL', 'MongoDB', 'AWS', 'Docker', 'Kubernetes', + 'Machine Learning', 'Deep Learning', 'TensorFlow', + 'PyTorch', 'HTML', 'CSS', 'Git', 'REST API' + ] + + def extract_text_from_pdf(self, filepath): + """Extract text from PDF""" + with open(filepath, 'rb') as file: + reader = PyPDF2.PdfReader(file) + text = '' + for page in reader.pages: + text += page.extract_text() + return text + + def extract_text_from_docx(self, filepath): + """Extract text from DOCX""" + doc = docx.Document(filepath) + text = '\n'.join([para.text for para in doc.paragraphs]) + return text + + def extract_text_from_txt(self, filepath): + """Extract text from TXT""" + with open(filepath, 'r', encoding='utf-8') as file: + return file.read() + + def analyze_file(self, filepath): + """Analyze resume file""" + ext = filepath.rsplit('.', 1)[1].lower() + + if ext == 'pdf': + text = self.extract_text_from_pdf(filepath) + elif ext == 'docx': + text = self.extract_text_from_docx(filepath) + else: + text = self.extract_text_from_txt(filepath) + + return self.analyze_text(text) + + def analyze_text(self, text): + """Analyze resume text with AI""" + # Detect skills + detected_skills = [skill for skill in self.tech_skills + if skill.lower() in text.lower()] + + # Extract email + email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' + emails = re.findall(email_pattern, text) + + # Extract phone + phone_pattern = r'[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}' + phones = re.findall(phone_pattern, text) + + # Calculate score + score = min(100, len(detected_skills) * 10 + 20) + + return { + 'skills': detected_skills, + 'email': emails[0] if emails else None, + 'phone': phones[0] if phones else None, + 'score': score, + 'word_count': len(text.split()), + 'experience_level': 'Mid-Level' if len(detected_skills) > 5 else 'Junior' + } diff --git a/frontend/src/components/resumeupload.jsx b/frontend/src/components/resumeupload.jsx new file mode 100644 index 0000000..4db8737 --- /dev/null +++ b/frontend/src/components/resumeupload.jsx @@ -0,0 +1,53 @@ +/** + * Resume Upload Component + * Author: Akshit + */ + +import React, { useState } from 'react'; +import resumeApi from '../utils/resumeApi'; + +const ResumeUpload = () => { + const [file, setFile] = useState(null); + const [uploading, setUploading] = useState(false); + const [progress, setProgress] = useState(0); + const [analysis, setAnalysis] = useState(null); + + const handleFileChange = (e) => { + setFile(e.target.files[0]); + }; + + const handleUpload = async () => { + if (!file) return; + + setUploading(true); + const response = await resumeApi.uploadResume(file, (prog) => { + setProgress(prog); + }); + + if (response.success) { + setAnalysis(response.data.analysis); + } + setUploading(false); + }; + + return ( +
+

πŸ“€ Upload Resume

+ + + + {analysis && ( +
+

Analysis Results

+

Score: {analysis.score}/100

+

Skills: {analysis.skills.join(', ')}

+

Experience: {analysis.experience_level}

+
+ )} +
+ ); +}; + +export default ResumeUpload; diff --git a/frontend/src/pages/profilepage.jsx b/frontend/src/pages/profilepage.jsx new file mode 100644 index 0000000..8a232c4 --- /dev/null +++ b/frontend/src/pages/profilepage.jsx @@ -0,0 +1,18 @@ +/** + * Profile Page with Resume Upload + * Author: Akshit + */ + +import React from 'react'; +import ResumeUpload from '../components/ResumeUpload'; + +const ProfilePage = () => { + return ( +
+

πŸ‘€ User Profile

+ +
+ ); +}; + +export default ProfilePage; diff --git a/frontend/src/services/api.js b/frontend/src/services/api.js index e69de29..9303f23 100644 --- a/frontend/src/services/api.js +++ b/frontend/src/services/api.js @@ -0,0 +1,239 @@ +/** + * Axios API Service for ML Simulator + * Author: Akshit + * Date: October 13, 2025 + * Purpose: Centralized API service for secure backend communication + */ + +import axios from 'axios'; + +// Base API configuration +const API_BASE_URL = process.env.REACT_APP_API_BASE_URL || 'http://localhost:5000/api'; +const API_TIMEOUT = 30000; // 30 seconds + +/** + * Create Axios instance with default configuration + */ +const apiClient = axios.create({ + baseURL: API_BASE_URL, + timeout: API_TIMEOUT, + headers: { + 'Content-Type': 'application/json', + 'Accept': 'application/json', + }, +}); + +/** + * Request Interceptor + * Add authentication token and modify request before sending + */ +apiClient.interceptors.request.use( + (config) => { + // Add authentication token if available + const token = localStorage.getItem('auth_token'); + if (token) { + config.headers.Authorization = `Bearer ${token}`; + } + + // Add timestamp to prevent caching + config.headers['X-Request-Time'] = new Date().getTime(); + + // Log request in development + if (process.env.NODE_ENV === 'development') { + console.log('πŸš€ API Request:', { + method: config.method?.toUpperCase(), + url: config.url, + data: config.data, + }); + } + + return config; + }, + (error) => { + console.error('❌ Request Error:', error); + return Promise.reject(error); + } +); + +/** + * Response Interceptor + * Handle responses and errors globally + */ +apiClient.interceptors.response.use( + (response) => { + // Log response in development + if (process.env.NODE_ENV === 'development') { + console.log('βœ… API Response:', { + status: response.status, + url: response.config.url, + data: response.data, + }); + } + + return response.data; + }, + (error) => { + // Handle different error scenarios + if (error.response) { + // Server responded with error status + const { status, data } = error.response; + + switch (status) { + case 400: + console.error('❌ Bad Request:', data.message || 'Invalid request'); + break; + case 401: + console.error('❌ Unauthorized: Please login again'); + // Clear token and redirect to login + localStorage.removeItem('auth_token'); + window.location.href = '/login'; + break; + case 403: + console.error('❌ Forbidden: You do not have permission'); + break; + case 404: + console.error('❌ Not Found:', data.message || 'Resource not found'); + break; + case 500: + console.error('❌ Server Error:', data.message || 'Internal server error'); + break; + case 503: + console.error('❌ Service Unavailable: Server is down'); + break; + default: + console.error('❌ Error:', data.message || 'An error occurred'); + } + + return Promise.reject({ + status, + message: data.message || 'An error occurred', + data: data, + }); + } else if (error.request) { + // Request made but no response received + console.error('❌ Network Error: No response from server'); + return Promise.reject({ + status: 0, + message: 'Network error. Please check your connection.', + data: null, + }); + } else { + // Something else happened + console.error('❌ Error:', error.message); + return Promise.reject({ + status: 0, + message: error.message || 'An unexpected error occurred', + data: null, + }); + } + } +); + +/** + * API Service Methods + */ +const apiService = { + /** + * GET request + * @param {string} endpoint - API endpoint + * @param {object} params - Query parameters + * @returns {Promise} Response data + */ + get: async (endpoint, params = {}) => { + try { + const response = await apiClient.get(endpoint, { params }); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, + + /** + * POST request + * @param {string} endpoint - API endpoint + * @param {object} data - Request body + * @returns {Promise} Response data + */ + post: async (endpoint, data = {}) => { + try { + const response = await apiClient.post(endpoint, data); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, + + /** + * PUT request + * @param {string} endpoint - API endpoint + * @param {object} data - Request body + * @returns {Promise} Response data + */ + put: async (endpoint, data = {}) => { + try { + const response = await apiClient.put(endpoint, data); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, + + /** + * PATCH request + * @param {string} endpoint - API endpoint + * @param {object} data - Request body + * @returns {Promise} Response data + */ + patch: async (endpoint, data = {}) => { + try { + const response = await apiClient.patch(endpoint, data); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, + + /** + * DELETE request + * @param {string} endpoint - API endpoint + * @returns {Promise} Response data + */ + delete: async (endpoint) => { + try { + const response = await apiClient.delete(endpoint); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, + + /** + * Upload file with multipart/form-data + * @param {string} endpoint - API endpoint + * @param {FormData} formData - Form data with file + * @param {function} onProgress - Progress callback + * @returns {Promise} Response data + */ + uploadFile: async (endpoint, formData, onProgress = null) => { + try { + const response = await apiClient.post(endpoint, formData, { + headers: { + 'Content-Type': 'multipart/form-data', + }, + onUploadProgress: (progressEvent) => { + if (onProgress) { + const percentCompleted = Math.round( + (progressEvent.loaded * 100) / progressEvent.total + ); + onProgress(percentCompleted); + } + }, + }); + return { success: true, data: response }; + } catch (error) { + return { success: false, error }; + } + }, +}; + +export default apiService; diff --git a/frontend/src/services/resumeapi.js b/frontend/src/services/resumeapi.js new file mode 100644 index 0000000..3dcad58 --- /dev/null +++ b/frontend/src/services/resumeapi.js @@ -0,0 +1,20 @@ +/** + * Resume API Service + * Author: Akshit + */ + +import apiService from './api'; + +const resumeApi = { + uploadResume: async (file, onProgress) => { + const formData = new FormData(); + formData.append('file', file); + return await apiService.uploadFile('/resume/upload', formData, onProgress); + }, + + analyzeResume: async (text) => { + return await apiService.post('/resume/analyze', { text }); + }, +}; + +export default resumeApi;