Painel de Vagas

Plataforma de captura, agregação e consulta de vagas com arquitetura monorepo, composta por frontend web, backend Node.js e aplicação desktop com Electron.

O produto evoluiu para um modelo orientado a serviços (API + scraper Go + cache/índices), com autenticação, preferências de usuário e integração com banco de dados.

Links oficiais

• Gestão de produto (Linear): https://linear.app/tatame/team/PAV/all
• Design system oficial (Figma): https://www.figma.com/design/gollJBtK8PGkffNN4zk9t9/Painel-Dev---releitura?node-id=0-1&p=f&t=zU8zrFzPsNPxZ3qU-0
• Documentação backend detalhada: BACKEND.md
• Documentação scraper Go: SCRAPER.md
• Guia de testes: TESTING.md
• Documentação inicial do MVP (Visão PO) ESCOPO.md

Sumário

• Visão geral
• Arquitetura do monorepo
• Stack real do projeto
• Quickstart local
• Comandos verificados
• API backend (estado atual)
• Docker (infra + aplicação)
• Desktop com Electron
• Variáveis de ambiente
• Testes e qualidade
• Fluxo de desenvolvimento e branching
• Git Hooks e qualidade local
• Inconsistências atuais mapeadas
• Roadmap técnico sugerido
• Contribuição

Visão geral

Este repositório centraliza três frentes:

• Frontend React para visualização e operação da plataforma.
• Backend Node.js/Express (TypeScript) com autenticação, preferências e rotas de domínio.
• Scraper em Go para coleta de vagas em múltiplas fontes.

Objetivo de produto: fornecer uma base robusta para busca, filtragem e gestão de vagas com foco em qualidade de dados, escalabilidade e operação contínua.

Arquitetura do monorepo

.
├─ frontend/                # Dashboard web (React + Vite)
├─ backend/                 # API Node.js (Express + TS + Drizzle)
├─ scraper-go/              # Serviço Go de scraping multi-fonte
├─ electron/                # Shell desktop
├─ docker-compose.yml       # App stack (frontend + backend + scraper-go)
├─ docker-compose.infra.yml # Infra stack (Postgres + Valkey)
└─ .github/workflows/ci.yml # CI

Stack real do projeto

• Frontend: React 19, TypeScript, Vite 8, Tailwind CSS, Vitest.
• Backend: Node.js 22+, Express 5, TypeScript, Drizzle ORM, Zod, Iron Session, Redis/Valkey.
• Scraping: Go (serviço dedicado em scraper-go).
• Desktop: Electron + Electron Builder.
• Qualidade: Vitest (frontend/backend), cobertura v8, ESLint (frontend), GitHub Actions CI.
• Dados: Postgres (persistência) + Valkey/Redis (cache e índice).

Quickstart local

Pré-requisitos

• Node.js >= 22
• npm
• Docker e Docker Compose (opcional, recomendado para ambiente completo)

Instalação

npm install

Execução web (frontend + backend)

npm run dev

Execução separada:

npm run dev:frontend
npm run dev:backend

Execução de testes

npm run test:coverage

Comandos verificados

Os comandos abaixo existem hoje no repositório e foram conferidos nos package.json de raiz, frontend e backend.

Raiz

• npm run dev
• npm run dev:frontend
• npm run dev:backend
• npm run scraper
• npm run scraper:watch
• npm run test
• npm run test:coverage
• npm run build
• npm run build:frontend
• npm run validate
• npm run electron
• npm run electron:dev
• npm run dist
• npm run db:generate
• npm run db:migrate
• npm run db:push

Backend

• npm run start
• npm run dev
• npm run api
• npm run test
• npm run test:coverage
• npm run test:watch
• npm run validate
• npm run db:generate
• npm run db:migrate
• npm run db:push

Frontend

• npm run dev
• npm run build
• npm run lint
• npm run preview
• npm run test
• npm run test:coverage
• npm run test:watch

API backend (estado atual)

Base: /api

Sistema:

• GET /api/health

Autenticação:

• GET /api/auth/:provider/url
• GET /api/auth/:provider/callback
• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/me

Usuários:

• GET /api/users/profile
• PATCH /api/users/profile
• GET /api/users/preferences
• POST /api/users/preferences
• PATCH /api/users/preferences

Jobs:

• GET /api/jobs/search

Keywords:

• GET /api/keywords
• POST /api/keywords

Saved jobs:

• GET /api/saved-jobs
• GET /api/saved-jobs/:id
• POST /api/saved-jobs
• PATCH /api/saved-jobs/:id
• DELETE /api/saved-jobs/:id

Swagger:

• GET /docs

Docker (infra + aplicação)

Este projeto separa infraestrutura de aplicação em dois arquivos compose.

1. Criar rede compartilhada (necessário uma vez):

docker network create vagas-net

2. Subir infra (Postgres + Valkey):

docker compose -f docker-compose.infra.yml up -d

3. Subir aplicação (scraper-go + backend + frontend):

docker compose up --build -d

4. Logs:

docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f scraper-go

5. Encerrar:

docker compose down
docker compose -f docker-compose.infra.yml down

Serviços padrão:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001
• Scraper Go: http://localhost:8081

Desktop com Electron

O app desktop empacota frontend + backend e inicia a aplicação com Electron.

Comandos:

npm run build:frontend
npm run electron

Distribuição (Windows):

npm run dist

Saída esperada do instalador:

• dist-electron/Vagas Full Setup X.X.X.exe

Variáveis de ambiente

Arquivo base:

• backend/.env.example

Arquivo local:

• backend/.env

Variáveis centrais de operação:

• DATABASE_URL
• VALKEY_URL
• GO_SCRAPER_URL
• SESSION_SECRET
• CORS_ALLOWED_ORIGINS
• SEARCH_LOCATION
• SEARCH_GEO_ID
• SEARCH_LANGUAGE
• REMOTE_ONLY
• JOB_TYPES
• TIME_FILTER
• WAIT_BETWEEN_SEARCHES_MS
• PAGE_TIMEOUT_MS
• MAX_PAGES_PER_KEYWORD
• CACHE_TTL_MS

Segurança operacional:

• Nunca versionar segredos reais no Git.
• Preferir acesso interno para banco/cache em VPS.
• Em ambiente externo, usar TLS para conexões de dados sempre que possível.

Testes e qualidade

Estrutura:

• backend/tests/unit
• backend/tests/integration
• frontend/tests/unit
• frontend/tests/integration

Threshold mínimo:

• lines >= 80%
• statements >= 80%
• functions >= 80%
• branches >= 80%

Comandos:

npm run test:coverage
npm --workspace frontend run test:coverage
npm --workspace backend run test:coverage

Observação importante: o backend já está configurado para coletar cobertura apenas em src/*/.ts, evitando contagem de artefatos gerados.

CI/CD

Workflow atual: .github/workflows/ci.yml

Executa em push para master/develop e em pull_request:

• Instalação de dependências
• Coverage frontend
• Coverage backend
• Lint frontend
• Build frontend

Fluxo de desenvolvimento e branching

Padrão oficial:

1. Abrir card no Linear: https://linear.app/tatame/team/PAV/all
2. Criar branch de feature a partir de master
3. Desenvolver e testar localmente
4. Abrir PR da feature para develop
5. Após aprovação e validação, merge em develop
6. Abrir PR de develop para master
7. Merge em master para release

Convenção recomendada de branch:

• feature/-

Git Hooks e qualidade local

O repositório usa Husky na raiz do monorepo para padronizar validações locais em qualquer branch.

Hooks configurados:

• pre-commit: executa lint-staged para validar arquivos staged do frontend.
• commit-msg: valida mensagem de commit com commitlint (Conventional Commits).
• pre-push: executa validação do monorepo (test backend + lint/build frontend).

Bootstrap recomendado para novos ambientes:

npm run setup:dev

Checklist quando hooks não disparam:

1. Validar se o diretório Git foi detectado: git rev-parse --git-dir.
2. Validar hooksPath local: git config --get core.hooksPath.
3. Confirmar arquivos versionados em .husky (pre-commit, commit-msg, pre-push).
4. Reinstalar hooks: npm run prepare.
5. Em Windows, preferir Git Bash para depuração de scripts shell.

Observação importante:

• CI continua obrigatório e independente de hooks locais. Mesmo com bypass local, o pipeline valida cobertura/lint/build antes de merge.

Roadmap técnico sugerido

DX e onboarding

• Adicionar script único de bootstrap (exemplo: npm run setup:dev) para criar .env e validar pré-requisitos.
• Adicionar verificação automática de scripts quebrados no CI.
• Padronizar comandos cross-platform (evitar dependência de sintaxe de variável de ambiente Unix em scripts críticos).

Segurança

• Aplicar política de rotação de SESSION_SECRET e credenciais OAuth.
• Adicionar checklist de segurança para PRs (cookies, CORS, secrets, headers).

Performance

• Definir estratégia de paginação e filtros em camada de API com métricas por endpoint.
• Revisar TTL e cardinalidade dos índices no Valkey para reduzir consumo de memória.

Observabilidade

• Padronizar correlação de logs por request id.
• Publicar guia mínimo de troubleshooting com sinais de saúde dos serviços frontend/backend/scraper-go.

Contribuição

1. Abra um card no Linear.
2. Crie branch a partir de master.
3. Implemente com testes.
4. Execute validações locais:

npm run validate
npm run test:coverage

5. Abra PR para develop com contexto técnico objetivo.

Se você vai trabalhar em backend, scraper ou testes, use também:

• BACKEND.md
• SCRAPER.md
• TESTING.md