| # 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) |
|
|
