CONTRIBUTING.md

Contributing to JobPortal

Thank you for your interest in contributing! This guide will help you get started.

Development Setup

Prerequisites

• Python 3.12+
• Node.js 20+ with pnpm
• Docker & Docker Compose
• Git

First Time Setup

# Clone the repo
git clone https://huggingface.co/anky2002/best
cd best

# Copy environment
cp .env.example .env

# Install dependencies and start services
make setup

# Start development
make dev
# Then in separate terminals:
make backend   # FastAPI on :8000
make frontend  # Next.js on :3000

Running Tests

# Backend unit tests
cd backend && pytest -v

# Frontend type check
cd frontend && pnpm tsc --noEmit

# E2E tests (requires running app)
cd frontend && pytest e2e/

Project Structure

best/
├── backend/          # FastAPI Python backend
├── frontend/         # Next.js 15 TypeScript frontend
├── extension/        # Chrome MV3 extension
├── nginx/            # Production reverse proxy config
├── deploy/           # Deployment scripts
├── docs/             # API docs, Postman collection
└── .github/          # CI/CD workflows

Development Workflow

1. Create a branch from main:

   git checkout -b feature/my-feature
   

2. Make changes following the code style:

   • Backend: Run ruff check . && ruff format .
   • Frontend: Run pnpm lint

3. Write tests for new features

4. Commit with conventional commits:

   feat: Add salary comparison chart
   fix: Correct JWT refresh token expiry
   docs: Update API documentation
   

5. Push and open a Pull Request

Code Style

Backend (Python)

• Use type hints everywhere
• Pydantic models for request/response validation
• Async SQLAlchemy for all DB operations
• Docstrings for public functions
• Ruff for linting and formatting

Frontend (TypeScript)

• Strict TypeScript (no any unless unavoidable)
• React Server Components where possible
• TanStack Query for server state
• Zod for form validation
• Tailwind for styling (no inline styles)

Architecture Decisions

Why these choices?

Choice	Reason
FastAPI + SQLAlchemy async	High performance, type safety, great DX
Next.js App Router	RSC, streaming, optimal UX
PostgreSQL + pgvector	Relational + vector search in one DB
Celery + Redis	Battle-tested async task processing
LiteLLM	Single abstraction for 8+ LLM providers
Cloudflare R2	S3-compatible, cheap, fast

Adding a New Feature

1. Backend: Create model → migration → CRUD → API route → tests
2. Frontend: Create type → API client function → hook → page/component
3. Update docs: API collection, README if user-facing

Adding a New Scraper Source

1. Add connector in backend/app/scraper/sources/
2. Register in ScraperEngine._scrape_ats() dispatch
3. Add seed source in backend/app/scripts/seed.py
4. Test with POST /api/v1/admin/sources/{id}/scrape

Adding a New LLM Provider

1. Add config in backend/app/core/config.py
2. Add to provider list in backend/app/services/llm_gateway.py
3. Add to task model preferences
4. Add frontend provider option in settings page

Security

• Never commit .env files or API keys
• Use parameterized queries (SQLAlchemy handles this)
• Validate all user input with Pydantic
• Rate limit AI endpoints
• Encrypt API keys at rest
• Use short-lived presigned URLs for file access

Getting Help

• Open an issue for bugs or feature requests
• Check existing issues before creating new ones
• Tag issues with appropriate labels

License

By contributing, you agree that your contributions will be licensed under the MIT License.