JobScouter

Visao Geral

O JobScouter resolve um problema pratico: buscar vagas em multiplas fontes, reduzir ruido de dados e transformar volume em decisao.

Em vez de apenas baixar anuncios, o sistema:

• centraliza a coleta de vagas;
• aplica filtros de negocio para remover ruido cedo;
• enriquece o resultado com analise de compatibilidade por IA;
• disponibiliza dados estruturados via API e dashboard web.

Arquitetura do Ecossistema

Jornada do dado de ponta a ponta:

Ingestao (Legacy Core)
  -> coleta e deduplica vagas por fonte/URL

Analise (Legacy Core)
  -> aplica filtros estaticos e, quando elegivel, score por IA

API Service (FastAPI)
  -> expoe consulta e gatilhos de sincronizacao de forma estruturada

Dashboard (Next.js)
  -> interface para visualizar e gerenciar oportunidades

Componentes principais:

• BaseScraper: contrato comum para novas fontes.
• RemoteOKScraper e RemotarScraper: conectores de ingestao.
• JobIngestionService: persistencia idempotente.
• JobFilterService: filtros estaticos por palavras-chave.
• ProfileEnricher: expande os search_terms configurados via Gemini antes da busca.
• AIAnalyzerService: compatibilidade por Gemini.

Expansao de termos de busca

Antes de iniciar a ingestao, os search_terms do FilterConfig sao expandidos automaticamente via Gemini:

• Frameworks/bibliotecas: adiciona alternativas do mesmo tipo (ex: Django → Flask, FastAPI).
• Linguagens: adiciona os principais frameworks associados (ex: Python → Django, Flask, FastAPI).
• Conceitos genericos (fullstack, backend, etc.): sem expansao.

O scraper e chamado uma vez por termo efetivo (originais + adicionados pela IA). A validacao de assertividade continua usando filter_config.include_keywords diretamente — nao os termos de busca expandidos.

Sem GEMINI_API_KEY, ou em caso de falha na chamada, o sistema usa os termos originais sem interrupcao.

Quick Start

Modo recomendado (Deploy unificado com Docker Compose + NGINX)

cp .env.example .env
docker compose up -d --build

Servicos disponiveis apos subir:

• Entrada unica (NGINX): http://localhost
• Frontend via proxy: http://localhost/
• API via proxy: http://localhost/api/v1
• Swagger via proxy: http://localhost/docs

Alternativas rapidas

Modo local (sem stack completa de containers):

make run-back   # apenas backend (inclui bootstrap + API)
make run-front  # apenas frontend
make run-dev    # backend + frontend locais (db via compose)
make down       # derruba os servicos do compose

Operacoes uteis no modo containerizado:

docker compose logs -f
docker compose down

Configuracao de Ambiente

O projeto usa .env na raiz (backend e frontend).

Variaveis essenciais:

Variavel	Obrigatoria	Default	Uso
APP_ENV	Nao	development	Ambiente de execucao; em production a API desabilita /docs e /openapi.json
DATABASE_URL	Sim	postgresql+psycopg://postgres:postgres@localhost:5432/jobscouter	Persistencia da API/CLI
LOG_LEVEL	Nao	INFO	Nivel de log
REQUEST_TIMEOUT	Nao	20	Timeout de requisicao HTTP
REMOTEOK_API_URL	Nao	https://remoteok.com/api	Fonte RemoteOK
REMOTAR_BASE_URL	Nao	https://remotar.com.br	Fonte Remotar
REMOTAR_API_URL	Nao	https://api.remotar.com.br	Fonte Remotar
GEMINI_API_KEY	Sim (analise IA e expansao de termos)	-	Chave Gemini; sem ela, analise IA e expansao de termos sao desativadas
GEMINI_MODEL	Nao	models/gemini-2.5-flash-lite	Modelo preferencial; deve ser da familia gemini-2.5-flash-lite ou gemini-2.5-flash — modelos fora dessa allowlist sao ignorados com aviso no log
GEMINI_RETRY_DELAY_SECONDS	Nao	1.5	Retry em rate limit
DATABASE_URL_DOCKER	Nao	postgresql+psycopg://postgres:postgres@db:5432/jobscouter	URL do banco usada no servico backend do Compose
POSTGRES_DB	Nao	jobscouter	Nome do banco no servico db
POSTGRES_USER	Nao	postgres	Usuario do banco no servico db
POSTGRES_PASSWORD	Sim	-	Senha do banco no servico db (defina valor forte)
NEXT_PUBLIC_API_BASE_PATH	Nao	/api/v1	Base relativa da API no frontend
NEXT_PUBLIC_API_BASE_URL	Nao	vazio	URL do backend para rewrite no modo local sem NGINX

Observacao: para ambiente de producao, defina APP_ENV=production para desabilitar publicamente os endpoints de documentacao da API (/docs, /openapi.json e /redoc). Observacao: no build do backend via Compose, APP_ENV=production instala o pacote em modo nao-editavel; em outros ambientes, usa install editavel para favorecer hot reload de desenvolvimento. Observacao: para frontend em modo dev no container (next dev), alterar NEXT_PUBLIC_* exige reiniciar o container frontend para recarregar o ambiente. Em fluxo de build/producao (next build), essas variaveis sao build-time e exigem rebuild da imagem.

Legado Funcional (Power User)

Embora o JobScouter ofereca experiencia completa via API + Dashboard, os modulos de ingestao e analise podem rodar de forma independente para pipelines customizados.

CLI de ingestao

jobscouter-ingest --source all --limit 20
jobscouter-ingest --source remoteok --keyword django --limit 10

CLI de analise

jobscouter-analyze --limit 20

Regras de status utilizadas no fluxo:

• pending: sem match de include/exclude.
• ready_for_ai: passou no filtro e segue para IA.
• discarded: vetada por palavra excluida.
• analyzed: analise concluida.

API Service

Endpoints principais:

• GET /api/v1/jobs
• POST /api/v1/control/sync/ingest
• POST /api/v1/control/sync/analyze
• GET /api/v1/config
• PATCH /api/v1/config

Listagem de vagas com paginacao

Query params suportados em GET /api/v1/jobs:

• page (opcional, default: 1, minimo: 1)
• size (opcional, default: 50, minimo: 1, maximo: 100)
• status (opcional: pending, ready_for_ai, discarded, analyzed)
• min_score (opcional)

Exemplo de requisicao:

curl "http://127.0.0.1:8000/api/v1/jobs?page=2&size=20&status=analyzed&min_score=1"

Exemplo de resposta:

{
  "items": [
    {
      "id": 101,
      "title": "Python Developer",
      "company": "Acme",
      "url": "https://example.com/jobs/101",
      "description_raw": "...",
      "status": "analyzed",
      "ai_score": 8,
      "ai_summary": "Boa aderencia para backend Python.",
      "ai_analysis_at": "2026-03-28T18:20:31Z"
    }
  ],
  "total": 240,
  "page": 2,
  "size": 20
}

Frontend Web

Detalhes de desenvolvimento do dashboard Next.js (variaveis, scripts e comportamento de paginacao por URL) estao em web/README.md.

Qualidade

make lint
make test
make lint-front
make test-front

Obs.: no estado atual, make test-front roda um placeholder definido em web/package.json.

Roadmap e Extensibilidade

• Multi-nicho: estrutura pronta para expansao alem de vagas de tech.
• Novas fontes: onboarding de provedores adicionais com BaseScraper.
• IA de matching: evoluir para comparacao curriculo vs vaga.
• Maturidade de produto: ampliar observabilidade, testes frontend e deploy automatizado.

Contribuicao

Fluxo de colaboracao e padroes de commit estao em CONTRIBUTING.md.

Ao abrir contribuicoes, use os templates:

• Issue de bug: Bug Report
• Issue de feature: Feature Request
• Pull request: PR Template

Licenca

Este projeto esta sob a licenca MIT. Veja LICENSE.