srbhr · PR-HARIHARAN · Oct 3, 2025
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -51,121 +51,139 @@ Follow these steps to set up the environment and run the application.
    cd Resume-Matcher
    ```
 
-3. Create a Python Virtual Environment:
+3. **Install Dependencies (Quick Setup):**
 
-   - Using [virtualenv](https://learnpython.com/blog/how-to-use-virtualenv-python/):
+   ```bash
+   # Install all dependencies (frontend + backend)
+   npm install
+   ```
+
+   This will automatically:
+   - Install frontend dependencies via npm
+   - Install backend Python dependencies via uv (creates virtual environment automatically)
 
-     _Note_: Check how to install virtualenv on your system here [link](https://learnpython.com/blog/how-to-use-virtualenv-python/).
+4. **Set up Environment Files:**
 
-     ```bash
-     virtualenv env
-     ```
+   **Backend (.env):**
+   ```bash
+   # Create backend environment file
+   echo 'SYNC_DATABASE_URL=sqlite:///./resume_matcher.db' > apps/backend/.env
+   echo 'ASYNC_DATABASE_URL=sqlite+aiosqlite:///./resume_matcher.db' >> apps/backend/.env
+   echo 'SESSION_SECRET_KEY=your-secret-key-here-change-in-production' >> apps/backend/.env
+   echo 'LLM_PROVIDER=ollama' >> apps/backend/.env
+   echo 'LLM_BASE_URL=http://localhost:11434' >> apps/backend/.env
+   echo 'LL_MODEL=gemma3:4b' >> apps/backend/.env
+   ```
 
-   **OR**
+   **Frontend (.env.local):**
+   ```bash
+   # Create frontend environment file
+   echo 'NEXT_PUBLIC_API_URL=http://localhost:8000' > apps/frontend/.env.local
+   ```
 
-   - Create a Python Virtual Environment:
+5. **Start Development:**
 
-     ```bash
-     python -m venv env
-     ```
+   ```bash
+   # Start both frontend and backend
+   npm run dev
+
+   # OR start individually:
+   npm run dev:frontend  # Next.js frontend on http://localhost:3000
+   npm run dev:backend   # FastAPI backend on http://localhost:8000
+   ```
 
-4. Activate the Virtual Environment.
+6. **Alternative Setup Methods:**
 
-   - On Windows.
+   **Quick Setup (Recommended for first-time setup):**
+
+   **Windows (PowerShell):**
+   ```powershell
+   .\setup.ps1
+   ```
+
+   **Linux/macOS (Bash):**
+   ```bash
+   chmod +x setup.sh
+   ./setup.sh
+   ```
 
+   **Manual Setup (For advanced users):**
+
+   - Install frontend dependencies:
      ```bash
-     env\Scripts\activate
+     cd apps/frontend
+     npm ci
      ```
-
-   - On macOS and Linux.
-
+
+   - Install backend dependencies:
      ```bash
-     source env/bin/activate
-     ```
-
-    **OPTIONAL (For pyenv users)**
-
-   Run the application with pyenv (Refer to this [article](https://realpython.com/intro-to-pyenv/#installing-pyenv))
-
-   - Build dependencies (on ubuntu)
-      ```
-      sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev python openssl
-      ```
-      ```
-
-      sudo apt-get install build-essential zlib1g-dev libffi-dev libssl-dev libbz2-dev libreadline-dev libsqlite3-dev liblzma-dev libncurses-dev
-
-      sudo apt-get install python-tk python3-tk tk-dev
-
-      sudo apt-get install build-essential zlib1g-dev libffi-dev libssl-dev libbz2-dev libreadline-dev libsqlite3-dev liblzma-dev
-
-      ```
-
-        - pyenv installer
-     ```
-        curl https://pyenv.run | bash
-     ```
-   - Install desired python version
-     ```
-       pyenv install -v 3.11.0
-     ```
-
-   - pyenv with virtual enviroment
-     ```
-        pyenv virtualenv 3.11.0 venv
-     ```
-
-   - Activate virtualenv with pyenv
-     ```
-        pyenv activate venv
+     cd apps/backend
+     uv sync
      ```
 
-     5. Install Dependencies:
-
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-6. Prepare Data:
+7. **Prerequisites:**
 
-   - Resumes: Place your resumes in PDF format in the `Data/Resumes` folder. Remove any existing contents in this folder.
-   - Job Descriptions: Place your job descriptions in PDF format in the `Data/JobDescription` folder. Remove any existing contents in this folder.
+   Make sure you have these installed:
+   - **Node.js** ≥ v18 (includes npm)
+   - **Python** ≥ 3.12 
+   - **uv** ≥ 0.6.0 (Python package manager) - will be auto-installed by setup scripts
+   - **Ollama** (for AI model serving) - install from [ollama.com](https://ollama.com)
 
-7. Parse Resumes to JSON:
+8. **Troubleshooting:**
 
-   ```python
-   python run_first.py
-   ```
-
-   8. Run the Application:
+   If you encounter issues:
+
+   - **Missing dependencies**: Run `npm install` to ensure all packages are installed
+   - **Backend won't start**: Check that `.env` files are created in both `apps/backend/` and `apps/frontend/`
+   - **Database errors**: Ensure `SYNC_DATABASE_URL` and `ASYNC_DATABASE_URL` are set in `apps/backend/.env`
+   - **API 404 errors**: Verify `NEXT_PUBLIC_API_URL=http://localhost:8000` in `apps/frontend/.env.local`
 
-   ```python
-   streamlit run streamlit_app.py
-   ```
+## 🚀 Development Workflow (uv + npm)
 
-**Note**: For local versions, you do not need to run "streamlit_second.py" as it is specifically for deploying to Streamlit servers.
+Resume Matcher now uses **uv** for fast Python dependency management alongside npm for frontend dependencies.
 
-**Additional Note**: The Vector Similarity part is precomputed to optimize performance due to the resource-intensive nature of sentence encoders that require significant GPU and RAM resources. If you are interested in leveraging this feature in a Google Colab environment for free, refer to the upcoming blog (link to be provided) for further guidance.
+### Common Development Commands:
 
-<br/>
+```bash
+# Install all dependencies
+npm install
 
-### Docker
+# Start development servers (both frontend + backend)
+npm run dev
 
-1. Build the image and start application
+# Start individual services
+npm run dev:frontend    # Frontend only (port 3000)
+npm run dev:backend     # Backend only (port 8000)
 
-   ```bash
-       docker-compose up
-   ```
+# Add new Python dependency
+cd apps/backend
+uv add package-name
 
-2. Open `localhost:80` on your browser
+# Add development dependency
+cd apps/backend
+uv add --dev package-name
 
-<br/>
+# Install frontend package
+cd apps/frontend
+npm install package-name
+```
 
-### Running the Web Application
+### Environment Variables:
 
-The full stack Next.js (React and FastAPI) web application allows users to interact with the Resume Matcher tool interactively via a web browser.
+**Required for backend** (`apps/backend/.env`):
+```env
+SYNC_DATABASE_URL=sqlite:///./resume_matcher.db
+ASYNC_DATABASE_URL=sqlite+aiosqlite:///./resume_matcher.db
+SESSION_SECRET_KEY=your-secret-key-here
+LLM_PROVIDER=ollama
+LLM_BASE_URL=http://localhost:11434
+LL_MODEL=gemma3:4b
+```
 
-To run the full stack web application (frontend client and backend api servers), follow the instructions over on the [webapp README](/webapp/README.md) file.
+**Required for frontend** (`apps/frontend/.env.local`):
+```env
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
 
 ## Code Formatting
 
@@ -184,7 +202,11 @@ We also use [pre-commit](https://pre-commit.com/) to automatically check for com
 If you haven't already, please install the pre-commit hooks by running the following command in your terminal:
 
 ```sh
+# Install pre-commit using uv
+uv tool install pre-commit
+# OR if you prefer system-wide installation
 pip install pre-commit
+
 pre-commit install
 ```
 

diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}
diff --git a/README.md b/README.md
@@ -71,6 +71,10 @@ If you have any suggestions or feature requests, please feel free to open an iss
 
 ![Installation](assets/how_to_install_resumematcher.png)
 
+> **🚀 Now using uv for fast Python dependency management!**
+> 
+> Resume Matcher has migrated from pip to [uv](https://docs.astral.sh/uv/) for faster, more reliable Python package management. The setup scripts will automatically install uv if it's not present.
+
 Follow the instructions in the [SETUP.md](SETUP.md) file to set up the project locally. The setup script will install all the necessary dependencies and configure your environment.
 
 The project is built using:
@@ -80,12 +84,14 @@ The project is built using:
 - Ollama for local AI model serving.
 - Tailwind CSS for styling.
 - SQLite for the database.
+- uv for Python dependency management.
 
 | Technology   | Info/Version                               |
 |--------------|---------------------------------------|
-| Python      | 3.12+                   |
+| Python      | 3.12+ (with uv package manager)                   |
 | Next.js      | 15+                   |
 | Ollama       |        0.6.7        |
+| uv          | 0.6.0+ (Python package manager)        |
 
 
 ## Join Us and Contribute

diff --git a/SETUP.md b/SETUP.md
@@ -1,6 +1,9 @@
 # Local Setup Guide for Resume-Matcher
 
-![installing_resume_matcher](assets/how_to_install_resumematcher.png)
+![insta- **Python** ≥ 3.12 (`python3`, `pip3` for uv bootstrap only)
+- **uv** ≥ 0.6.0 (fast Python package manager) 
+- **curl** (for installing uv & Ollama)
+- **make** (for Makefile integration)g_resume_matcher](assets/how_to_install_resumematcher.png)
 
 This document provides cross-platform instructions to get the project up and running locally.
 
@@ -41,14 +44,15 @@ make run-dev
 ### Windows
 - **PowerShell** 5.1 or later
 - **Node.js** ≥ v18 (includes `npm`)
-- **Python** ≥ 3.8 (`python3`, `pip3`)
+- **Python** ≥ 3.12 (`python3`, `pip3` for uv bootstrap only)
+- **uv** ≥ 0.6.0 (will be auto-installed by setup.ps1 if missing)
 - **winget** (recommended for Ollama installation)
-- **uv** (will be auto-installed by setup.ps1 if missing)
 
 ### Linux/macOS
 - **Bash** 4.4 or higher
 - **Node.js** ≥ v18 (includes `npm`)
-- **Python** ≥ 3.8 (`python3`, `pip3`)
+- **Python** ≥ 3.12 (`python3`, `pip3` for uv bootstrap only)
+- **uv** ≥ 0.6.0 (fast Python package manager)
 - **curl** (for installing uv & Ollama)
 - **make** (for Makefile integration)
 
@@ -143,7 +147,7 @@ You can customize any variables in these files before or after bootstrapping.
    - Pull the `gemma3:4b` model via Ollama
    - Bootstrap root & backend `.env` files
    - Install Node.js deps (`npm ci`) at root and frontend
-   - Sync Python deps in `apps/backend` via `uv sync`
+   - Create Python virtual environment and sync deps via `uv sync`
 
 3. **(Optional) Start development**