Welcome to the BDPA Hackathon project! This guide will help you get started contributing to the codebase.

• Project Overview
• Prerequisites
• Quick Start
• Project Structure
• Environment Setup
• Running the Application
• Development Workflow
• Contributing Guidelines
• Troubleshooting
• Additional Resources

This is a career development platform that helps users:

• Analyze resumes and extract skills automatically
• Track target positions and identify skill gaps
• Get personalized learning recommendations from edX
• Connect LinkedIn profiles for enhanced profile data
• Visualize skill trees and career progression paths

Backend:

• FastAPI (Python) - REST API server
• Firebase Admin SDK - Backend database operations
• Google Gemini API - AI-powered skill extraction
• Vosk - Offline speech recognition
• FFmpeg - Audio processing

Frontend:

• Next.js 16 - React framework
• TypeScript - Type safety
• Firebase Client SDK - Authentication & Firestore
• Tailwind CSS - Styling
• React Flow - Skill tree visualization

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher) - Download
• Python (v3.8 or higher) - Download
• Git - Download
• FFmpeg - Required for audio processing
  • macOS: brew install ffmpeg
  • Linux: sudo apt-get install ffmpeg or sudo yum install ffmpeg
  • Windows: Download from FFmpeg.org

• VS Code or your preferred IDE
• Postman or curl for API testing
• Firebase CLI (optional) - npm install -g firebase-tools

git clone <repository-url>
cd BDPA-Hackathon

# Navigate to backend directory
cd backend

# Create a virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download Vosk model (if not already present)
# The model will be downloaded automatically on first use, or run:
bash download_vosk_model.sh

# Navigate to frontend directory (from project root)
cd frontend

# Install dependencies
npm install

See the Environment Setup section below for detailed instructions.

Quick setup:

• Backend: Create backend/.env with required variables
• Frontend: Create frontend/.env.local with Firebase config

BDPA-Hackathon/
├── backend/                 # FastAPI backend server
│   ├── main.py             # Main API application
│   ├── resume_analyzer.py  # Resume text extraction
│   ├── requirements.txt    # Python dependencies
│   ├── recordings/         # Audio recordings storage
│   ├── resumes/            # Uploaded resumes storage
│   └── vosk-model/         # Speech recognition model
│
├── frontend/               # Next.js frontend application
│   ├── app/               # Next.js app directory
│   │   ├── api/           # API routes
│   │   ├── dashboard/     # Dashboard page
│   │   ├── skills-setup/  # Skills setup page
│   │   └── ...
│   ├── components/        # React components
│   ├── contexts/          # React contexts
│   ├── lib/               # Utility functions
│   └── package.json       # Node dependencies
│
├── firestore.rules        # Firestore security rules
└── README.md              # This file

Create a backend/.env file with the following variables:

# Gemini API (for skill extraction)
GEMINI_API_KEY=your-gemini-api-key-here

# Firebase Admin SDK (for backend database operations)
FIREBASE_CREDENTIALS={"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}

# LinkedIn OAuth (optional)
LINKEDIN_CLIENT_ID=your-linkedin-client-id
LINKEDIN_CLIENT_SECRET=your-linkedin-client-secret
LINKEDIN_REDIRECT_URI=http://localhost:8000/api/linkedin/callback

Getting API Keys:

1. Gemini API Key:

   • Visit Google AI Studio
   • Sign in and create an API key
   • Copy the key to GEMINI_API_KEY

2. Firebase Credentials:

   • Go to Firebase Console
   • Project Settings → Service Accounts
   • Generate new private key
   • Copy JSON content to FIREBASE_CREDENTIALS (as a single-line JSON string)

3. LinkedIn OAuth (optional):

   • See LINKEDIN_OAUTH_SETUP.md for detailed instructions

Note: See ENVIRONMENT_SETUP.md for more detailed instructions.

Create a frontend/.env.local file:

NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-messaging-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id

Getting Firebase Config:

• See frontend/FIREBASE_SETUP.md for detailed instructions
• Firebase Console → Project Settings → Your apps → Web app config

cd backend

# Activate virtual environment (if not already active)
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Run the server
python main.py
# OR
uvicorn main:app --reload

Backend will be available at: http://localhost:8000

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

cd frontend

# Run development server
npm run dev

Frontend will be available at: http://localhost:3000

1. Backend Health Check:

   curl http://localhost:8000/health

   Should return: {"status":"healthy"}

2. Frontend:

   • Open http://localhost:3000 in your browser
   • You should see the application homepage

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes:

   • Follow existing code style
   • Add comments for complex logic
   • Update documentation if needed

3. Test your changes:

   • Test backend endpoints using /docs or Postman
   • Test frontend in browser
   • Check for console errors

4. Commit your changes:

   git add .
   git commit -m "Description of your changes"

5. Push and create PR:

   git push origin feature/your-feature-name

   Then create a Pull Request on GitHub.

Python (Backend):

• Follow PEP 8 style guide
• Use type hints where possible
• Add docstrings for functions and classes
• Maximum line length: 100 characters

TypeScript/React (Frontend):

• Use TypeScript for type safety
• Follow React best practices
• Use functional components with hooks
• Prefer named exports over default exports

Backend API Testing:

• Use the interactive docs at http://localhost:8000/docs
• Or use curl/Postman to test endpoints

Frontend Testing:

• Test in browser with React DevTools
• Check browser console for errors
• Test on different screen sizes

1. Check existing issues - See if your feature/bug is already reported
2. Create an issue - For major changes, create an issue first
3. Follow the code style - Match existing patterns
4. Write clear commit messages - Use descriptive commit messages

1. Update documentation - Update README if needed
2. Add tests - If applicable, add tests for your changes
3. Ensure builds pass - Make sure backend and frontend start without errors
4. Request review - Request review from maintainers

• 🐛 Bug fixes - Fix reported issues
• ✨ New features - Add new functionality
• 📝 Documentation - Improve docs and comments
• 🎨 UI/UX improvements - Enhance user interface
• ⚡ Performance - Optimize code and queries
• 🧪 Testing - Add tests and improve coverage

Issue: Module not found

# Ensure virtual environment is activated
source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

Issue: FFmpeg not found

# macOS
brew install ffmpeg

# Linux
sudo apt-get install ffmpeg

# Verify installation
ffmpeg -version

Issue: Vosk model not found

• The model should download automatically
• Or run: bash backend/download_vosk_model.sh
• Or manually download from Vosk Models

Issue: Firebase Admin SDK error

• Verify FIREBASE_CREDENTIALS is set correctly
• Ensure JSON is properly formatted (single line)
• Check service account has Firestore permissions

Issue: Gemini API error

• Verify GEMINI_API_KEY is set
• Check API quota/limits
• System will fallback to manual extraction if Gemini fails

Issue: Firebase not initialized

• Check .env.local exists in frontend/ directory
• Verify all NEXT_PUBLIC_* variables are set
• Restart dev server after changing .env.local

Issue: Module not found

cd frontend
rm -rf node_modules package-lock.json
npm install

Issue: Port already in use

# Kill process on port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

# Kill process on port 8000 (backend)
lsof -ti:8000 | xargs kill -9

Issue: CORS errors

• Ensure backend CORS is configured (already set to allow all origins in dev)
• Check backend is running on port 8000
• Verify frontend is calling correct backend URL

"Firebase is not initialized"

• Missing or incorrect environment variables
• Check browser console for specific missing variables

"Gemini API not configured"

• Backend will use fallback skill extraction
• Set GEMINI_API_KEY for AI-powered extraction

"ffmpeg not found"

• Install FFmpeg (see Prerequisites)
• Required for audio transcription feature

• ENVIRONMENT_SETUP.md - Detailed environment variable setup
• backend/FastAPI-README.md - Backend API documentation
• frontend/FIREBASE_SETUP.md - Firebase configuration guide
• LINKEDIN_OAUTH_SETUP.md - LinkedIn OAuth setup
• FIRESTORE_RULES_SETUP.md - Firestore security rules
• README.md (root) - Database navigation guide

• FastAPI Documentation
• Next.js Documentation
• Firebase Documentation
• Vosk Documentation
• Google Gemini API

Backend API (http://localhost:8000):

• GET / - API info
• GET /health - Health check
• GET /docs - Interactive API documentation
• POST /api/recordings - Upload audio recording
• POST /api/resumes - Upload resume
• POST /api/skills/process - Extract skills from text
• POST /api/skills - Save user skills
• GET /api/skills/{user_id} - Get user skills
• GET /api/linkedin/authorize - LinkedIn OAuth authorization

If you encounter issues:

1. Check existing issues on GitHub
2. Review documentation files in the repo
3. Check browser console (frontend) or server logs (backend)
4. Create an issue with:
   • Description of the problem
   • Steps to reproduce
   • Error messages/logs
   • Your environment (OS, Node/Python versions)

You should now be able to:

• ✅ Set up the development environment
• ✅ Run both backend and frontend servers
• ✅ Make changes and test them
• ✅ Contribute to the project

Happy coding! 🚀