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

```bash
# 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

```bash
# 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`:
   ```bash
   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.