# JobPortal AI — Open Source Job Search OS

An open-source, local-first job search platform with AI career tools, multi-source scraping, and application tracking.

> **Status: Early Beta.** Core tracker and scraping work. AI features require Ollama or cloud API key. Not production-hardened yet.

## What Works Today

### ✅ Stable
- **User auth** — register, login, JWT refresh, OAuth (Google/GitHub)
- **Application tracker** — kanban board, status tracking, interviews, reminders
- **Job scraping** — Greenhouse, Lever, Ashby public APIs + universal URL scraper
- **Job search** — filter by remote/salary/seniority/location/type
- **Profile editor** — experience, education, skills, preferences
- **Resume CRUD** — create versions, PDF/DOCX export, upload & parse
- **Cover letters** — create, edit, AI generate
- **Alerts** — saved searches with email/webhook/in-app notifications
- **Admin** — source management, health dashboard, bulk import
- **Chrome extension** — detect jobs, one-click save (prototype)
- **Dark/light theme** — neo-brutalism UI with working toggle

### ⚠️ Beta (works but needs evaluation)
- **AI resume review** — ATS scoring, keyword gaps (requires LLM)
- **AI job matching** — compare resume vs JD
- **Interview prep** — question generation, STAR coaching
- **Cover letter generation** — AI-written, tone selection
- **Resume tailoring** — optimize bullets for specific job
- **Networking messages** — LinkedIn/email drafts
- **Salary insights** — aggregate from scraped data
- **Skill gap analysis** — identifies missing skills + learning plan

### 🧪 Experimental
- **Career path explorer** — AI trajectory mapping
- **Culture match** — work style assessment
- **Salary negotiation coach** — offer analysis + scripts
- **Elevator pitch generator**
- **Job comparison tool**
- **Market trends** — skill demand tracking
- **Gamification** — streaks, achievements
- **Semantic search** — pgvector embeddings (infrastructure ready, indexing TODO)

### 🚫 Not Implemented Yet
- Chrome Web Store distribution
- Email/Gmail sync
- Mobile native app
- Billing/quotas
- Workday/iCIMS/BambooHR connectors
- Hosted public demo

## Architecture

```
Frontend:  Next.js 15 · React 19 · Tailwind v4 · Framer Motion
Backend:   FastAPI · SQLAlchemy 2.0 async · Pydantic v2 · LiteLLM
Database:  PostgreSQL 17 (pgvector) · Redis 7
Workers:   Celery · Scheduled scraping + alerts
Storage:   Cloudflare R2 (production) · Local (development)
AI:        Ollama (default, free) · OpenAI · Anthropic · Gemini · Mistral · DeepSeek · Grok · HF
```

## Supported Job Sources

| Source | Type | Status |
|--------|------|--------|
| Greenhouse (30+ boards) | Public API | ✅ Working |
| Lever (15+ boards) | Public API | ✅ Working |
| Ashby | Public API | ✅ Working |
| RemoteOK | Free API | ✅ Working |
| Arbeitnow | Free API | ✅ Working |
| HN Who's Hiring | Algolia API | ✅ Working |
| WeWorkRemotely | RSS | ✅ Working |
| Remotive | RSS | ✅ Working |
| Any URL (universal) | HTML/JSON-LD/LLM | ✅ Working |
| Workday | Planned | ❌ |
| SmartRecruiters | Planned | ❌ |
| iCIMS | Planned | ❌ |

## Quick Start

```bash
git clone https://github.com/anky2002/best
cd best
make setup    # Installs deps, starts DB/Redis, runs migrations, seeds demo data
make dev      # Starts DB + Redis
make backend  # Terminal 1: API on :8000
make frontend # Terminal 2: Web on :3000

# Optional: Local AI (free, no API key needed)
ollama pull llama3.2
```

**Demo login:** `demo@jobportal.dev` / `demo123`
**Admin:** `admin@jobportal.dev` / `admin123`
**API docs:** http://localhost:8000/api/v1/docs

## LLM Providers

Default is **Ollama (free, local, private)**. Add cloud keys in Settings for better quality:

| Provider | Env Var | Best For |
|----------|---------|----------|
| Ollama | (none needed) | Privacy, free, offline |
| OpenAI | `OPENAI_API_KEY` | Best quality overall |
| Anthropic | `ANTHROPIC_API_KEY` | Cover letters, long-form |
| DeepSeek | `DEEPSEEK_API_KEY` | Cheapest cloud option |
| Google | `GOOGLE_API_KEY` | Fast, good value |
| Mistral | `MISTRAL_API_KEY` | European hosting |
| xAI | `XAI_API_KEY` | Grok models |
| HuggingFace | `HUGGINGFACE_API_KEY` | Open models |

## Security

- Passwords: Argon2 hashing
- API keys: Fernet AES encryption at rest (PBKDF2 key derivation)
- Tokens: JWT with enforced secret in production
- See [SECURITY.md](SECURITY.md) and [PRIVACY.md](PRIVACY.md)

## Known Limitations

- Tokens stored in localStorage (XSS risk — HttpOnly cookies planned)
- No token revocation on logout (blacklist planned)
- Rate limiter fails open if Redis down
- AI features not evaluated for accuracy yet
- No hosted demo available

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

MIT — see [LICENSE](LICENSE)