diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..dda57c9 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,136 @@ +# Development Guide 🛠️ + +Welcome! This guide helps you set up your development environment and understand the contribution workflow for the UN SDG Advocate tool. + +## 📋 System Requirements + +Before you begin, ensure you have the following installed: + +- **Node.js**: `v18.0.0` or higher (Recommended: `v20.x`) +- **Python**: `v3.8` to `v3.11` +- **Git**: For version control + +Verify your versions: +```bash +node --version +npm --version +python --version +``` + +--- + +## 💻 Setup Instructions + +### Linux / macOS + +1. **Clone and Setup**: + ```bash + git clone https://github.com/chaoss/UNSDG-classifier-tool.git + cd UNSDG-classifier-tool + ``` + +2. **Backend Setup**: + ```bash + cd backend + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + ``` + +3. **Frontend Setup**: + ```bash + cd ../frontend + npm install + ``` + +### Windows (PowerShell) + +1. **Clone the repository**: + ```powershell + git clone https://github.com/chaoss/UNSDG-classifier-tool.git + cd UNSDG-classifier-tool + ``` + +2. **Backend Setup**: + ```powershell + cd backend + python -m venv venv + .\venv\Scripts\Activate.ps1 + pip install -r requirements.txt + ``` + *Note: If you get an "Execution Policy" error, run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`* + +3. **Frontend Setup**: + ```powershell + cd ..\frontend + npm install + ``` + +--- + +## 🔑 Environment Variables (Optional) + +The application can function without these, but they are recommended for full feature support. + +1. Navigate to the `backend/` directory. +2. Copy `.env.example` to `.env`: + ```bash + # Linux / macOS + cp .env.example .env + ``` + ```powershell + # Windows PowerShell + copy .env.example .env + ``` +3. Open `backend/.env` and add your tokens if needed: + - `GITHUB_TOKEN`: Increases GitHub API rate limits. [Create one here](https://github.com/settings/tokens). + - `OSDG_TOKEN`: Required only for the OSDG model tab. + +--- + +## 🚀 Running the Application + +Run the backend and frontend in separate terminal windows. + +**Terminal 1 (Backend):** +```bash +cd backend +# Activate venv if not already active +source venv/bin/activate # Linux/macOS +# OR +.\venv\Scripts\Activate.ps1 # Windows +python app.py +``` +*Expected: Running on http://127.0.0.1:5000* + +**Terminal 2 (Frontend):** +```bash +cd frontend +npm run dev +``` +*Expected: Running on http://localhost:3000* + +--- + +## ⚠️ Troubleshooting + +### First-Time Model Download +The first time you run a classification (especially the Sentence Transformer models), the application will download large AI models (approx. 1.5GB - 2GB total). +- **Symptom**: The backend may seem unresponsive while downloading. +- **Solution**: Monitor the backend terminal for progress. Ensure you have a stable internet connection. + +### Windows: "Scripts cannot be loaded..." +- **Fix**: Run PowerShell as Administrator and execute: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` + +### Backend: "ModuleNotFoundError" +- **Fix**: Ensure your virtual environment is activated and you have run `pip install -r requirements.txt`. + +--- + +## 🤝 Contribution Workflow + +1. **Find an Issue**: Look for [good first issues](https://github.com/chaoss/UNSDG-classifier-tool/issues). +2. **Fork & Branch**: Fork the repo and create a branch: `git checkout -b feature/your-feature-name`. +3. **Commit**: Keep commits small and descriptive. +4. **Test**: Verify your changes locally (both frontend and backend). +5. **PR**: Submit a Pull Request with a clear description of your changes. diff --git a/README.md b/README.md index f77c0ef..8fcd02e 100644 --- a/README.md +++ b/README.md @@ -27,42 +27,46 @@ Our project is officially listed in the [Code4GoodTech Dedicated Mentoring Progr ## Quick Start +For detailed setup instructions, troubleshooting, and contributor guidelines, please see our **[Development Guide (DEVELOPMENT.md)](./DEVELOPMENT.md)**. + ### Prerequisites -- Node.js 18+ and npm (Download link: https://nodejs.org/en/download/) -- Python 3.8+ (Download link: https://www.python.org/downloads/) +- **Node.js**: v18+ and npm +- **Python**: v3.8+ -### 1. Clone and Setup +### 1. Clone the Repository ```bash -git clone -cd UNSDG-advocate +git clone https://github.com/chaoss/UNSDG-classifier-tool.git +cd UNSDG-classifier-tool ``` -### 2. Bash script approach +### 2. Fast Setup (Linux/macOS) -- Make sure you have all of your prerequisites installed in your local computer like Node.js and Python -- Make sure you are inside the folder. +If you have all prerequisites, you can use the provided script: ```bash chmod +x ./bash.sh ./bash.sh ``` -### 3. Manual approach - -### 3.1. Backend Setup +### 3. Manual Setup (Cross-Platform) +#### Backend Setup ```bash cd backend -python3 -m venv myvenv -source ./myvenv/bin/activate +python -m venv venv + +# Activate (Linux/macOS) +source venv/bin/activate +# Activate (Windows PowerShell) +.\venv\Scripts\Activate.ps1 + pip install -r requirements.txt -python3 app.py +python app.py ``` -### 3.2. Frontend Setup - +#### Frontend Setup ```bash cd frontend npm install @@ -71,8 +75,10 @@ npm run dev ### 4. Access the Application -- Frontend: http://localhost:3000 -- Backend API: http://127.0.0.1:5000 +- **Frontend**: [http://localhost:3000](http://localhost:3000) +- **Backend API**: [http://127.0.0.1:5000](http://127.0.0.1:5000) + +> **Note**: On the first run, the backend will download AI models (approx. 2GB). Please ensure you have a stable internet connection. ## Usage diff --git a/backend/.env.example b/backend/.env.example new file mode 100644 index 0000000..04b8143 --- /dev/null +++ b/backend/.env.example @@ -0,0 +1,6 @@ +# Optional: increases GitHub API rate limits to avoid throttling +# Generate one at: https://github.com/settings/tokens +GITHUB_TOKEN= + +# Optional: required only for OSDG API classification features +OSDG_TOKEN=