PROJECT WAI_WAI

This Application naming Wevolve AI. A modern recruiting / jobs utility combining a FastAPI backend with a React + Vite frontend. The project provides job generation, resume parsing, candidate-job relevancy scoring, and analytics dashboards backed by AI services and Supabase.

Highlights

• Job description generator powered by AI
• Resume parsing and relevancy scoring
• Analytics dashboard with mock data for pipeline and source effectiveness
• Supabase integration for persistence

This repository contains two main parts:

• backend/ — FastAPI backend (AI integrations, resume parsing, analytics endpoints)
• Frontend/wai-wai/ — React + Vite frontend (UI, dashboard, job generator)

Quick links

• Backend entry: backend/main.py
• Frontend entry: Frontend/wai-wai/src/main.jsx
• Architecture diagram: ARCHITECTURE.md

---

Table of contents

• Project Overview
• Tech Stack
• Prerequisites
• Environment variables
• Backend — Install & Run
• Frontend — Install & Run
• API Endpoints (examples)
• Project structure
• Troubleshooting
• Contributing

---

Project Overview

project-wai-wai is an experimental toolkit for recruiting workflows. The backend exposes endpoints for analytics, job generation, resume parsing, and candidate profiling. The frontend is a React app built with Vite that consumes those endpoints and provides interactive dashboards and tools.

Tech Stack

• Backend: Python, FastAPI, Uvicorn
• AI / Integrations: Google Generative AI (Gemini), Hugging Face, Groq, Supabase
• Document parsing: pdfplumber, python-docx, reportlab
• Frontend: React, Vite

Prerequisites

• Node.js (recommended Node 16+ or Node 18+)
• npm or yarn
• Python 3.10+ and pip
• (Optional) virtualenv or venv for isolating Python deps

---

Environment variables

Create a .env file in backend/ and a .env file in Frontend/wai-wai/ as needed.

Important backend env vars (backend/.env):

• SUPABASE_URL — your Supabase project URL
• SUPABASE_KEY — Supabase service or anon key used by the backend
• GEMINI_API_KEY — (optional) Google Generative AI key used for resume analysis and generation
• HF_API_TOKEN — (optional) Hugging Face API token (used by some inference clients)
• GROQ_API_KEY — (optional) Groq API key

Frontend env vars (Frontend/wai-wai/.env):

• VITE_SUPABASE_URL — Supabase URL used by the frontend
• VITE_SUPABASE_ANON_KEY — Supabase anon/public key

Notes:

• If GEMINI_API_KEY is missing, resume analysis features will be limited (the backend prints a warning). See backend/main.py for how missing keys are handled.

---

Backend — Install & Run

1. Create and activate a virtual environment (recommended):

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# or cmd
.\.venv\Scripts\activate.bat

2. Install dependencies:

pip install -r backend/requirements.txt

3. Add your backend/.env file with the variables listed above.

4. Run the FastAPI server (development):

uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

The backend exposes a health check at /health (e.g., http://localhost:8000/health).

---

Frontend — Install & Run

1. Change to the frontend directory:

cd Frontend/wai-wai

2. Install dependencies:

# using npm
npm install
# or using yarn
yarn

3. Create or update Frontend/wai-wai/.env with the Vite environment variables mentioned earlier.

4. Run the development server:

npm run dev

Open the URL printed by Vite (usually http://localhost:5173).

---

API Endpoints (examples)

The backend implements multiple endpoints. A few useful ones:

• GET /health — basic health check
• GET /analytics/overview — returns mock analytics overview data
• GET /analytics/pipeline — funnel/pipeline counts
• GET /analytics/time-to-hire — time-to-hire series
• POST /api/generate-job — job generation endpoint (see backend/main.py for request model)

There are additional endpoints for resume upload/analysis, profile save, gap analysis, and job-specific analytics. See backend/main.py for the full list and request/response shapes.

---

Project structure (detailed)

• backend/ — FastAPI service and AI integrations

  • main.py — server entry, route definitions, AI clients, and helpers
  • requirements.txt — Python dependencies to install
  • .env — (not checked in) environment variables for keys and config
  • data/ — static data used by the backend
    • skill_taxonomy.json — skill taxonomy used for normalization & scoring

• Frontend/wai-wai/ — React + Vite application

  • .env — (not checked in) Vite / Supabase env vars (VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY)
  • package.json — scripts and frontend dependencies
  • index.html — Vite HTML entry
  • src/ — React source files
    • main.jsx — frontend app bootstrap / routing
    • App.jsx, App.css — top-level app component and styles
    • supabaseClient.js — Supabase client wrapper used across the app
    • components/ — reusable UI components
      • Navbar.jsx, Footer.jsx, JobCard.jsx, FilterPanel.jsx, ProtectedRoute.jsx
    • pages/ — route pages and main views
      • Home.jsx, JobGenerator.jsx, JobDashboard.jsx, ResumeParser.jsx, Analytics.jsx, Auth.jsx
    • styles/ — CSS modules and global styles
    • data/mockJobs.json — sample job data used in the UI for demos
  • public/ — static assets served by Vite
    • vanta/ — Vanta.js visual assets used on the landing page

Troubleshooting / Notes

• Missing or invalid API keys: the backend prints warnings when keys are absent; some features degrade gracefully (e.g., a regex fallback for resume parsing).
• If you hit CORS issues in development, the backend already enables permissive CORS for convenience. Lock this down for production.
• If the frontend cannot connect to Supabase, verify VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in Frontend/wai-wai/.env.

Quick dev checklist

• Backend: install deps, set backend/.env, run uvicorn backend.main:app --reload
• Frontend: cd Frontend/wai-wai, set .env, npm install, npm run dev

---

Contributing

1. Fork the repo and create a feature branch
2. Follow existing code style (Python: PEP8 / project formatting; JS: follow React project conventions)
3. Open a pull request with a clear description of changes