GitPulse

English version: README.en.md

Dashboard de produtividade para GitHub com autenticação OAuth, métricas de atividade dos últimos 30 dias e geração de relatório detalhado com exportação em PDF.

Visão Geral

O GitPulse permite que desenvolvedores visualizem rapidamente o próprio ritmo de contribuição no GitHub, com foco em:

• volume de commits no período;
• consistência diária e variação semanal;
• distribuição por linguagens;
• repositórios mais ativos;
• recomendações objetivas de melhoria.

Principais Funcionalidades

• Login com GitHub via NextAuth.
• Dashboard com métricas agregadas dos últimos 30 dias.
• Gráfico de frequência de commits e heatmap diário.
• Breakdown de linguagens por participação.
• Lista de repositórios recentes com estrela e visibilidade.
• Geração de relatório textual completo com plano de evolução.
• Exportação do relatório em PDF (via print flow do navegador).

Stack Tecnológica

• Next.js 15 (App Router)
• React 18
• TypeScript
• Tailwind CSS
• NextAuth.js v4 (GitHub Provider)
• GitHub REST API

Arquitetura e Estrutura

.
├── app/
│   ├── api/auth/[...nextauth]/route.ts   # Handler HTTP do NextAuth
│   ├── dashboard/page.tsx                 # Página server-side protegida
│   ├── globals.css                        # Estilos globais
│   ├── layout.tsx                         # Layout raiz
│   ├── page.tsx                           # Landing e login
│   └── providers.tsx                      # SessionProvider
├── components/
│   ├── CommitChart.tsx                    # Barras + heatmap
│   ├── DashboardClient.tsx                # UI principal + relatório/PDF
│   └── LanguageBar.tsx                    # Distribuição de linguagens
├── lib/
│   ├── auth.ts                            # Configuração do NextAuth
│   └── github.ts                          # Coleta e agregação de dados GitHub
├── public/
│   └── back.png                           # Background da landing/login
├── types/
│   └── index.ts                           # Tipos de domínio e augmentations
├── .env.local.example
├── package.json
└── README.md

Fluxo Funcional

1. Usuário autentica com GitHub.
2. Sessão recebe access token OAuth.
3. Backend consulta API do GitHub e agrega dados de produtividade.
4. Dashboard exibe métricas e visualizações.
5. Usuário pode gerar relatório completo e exportar para PDF.

Requisitos

• Node.js 18+
• npm 9+
• Conta GitHub com OAuth App configurado

Configuração Local

1) Criar OAuth App no GitHub

No GitHub Developers Settings:

• Application name: GitPulse (ou equivalente)
• Homepage URL: http://localhost:3000
• Authorization callback URL: http://localhost:3000/api/auth/callback/github

2) Configurar variáveis de ambiente

Crie o arquivo local a partir do template:

cp .env.local.example .env.local

Preencha o .env.local:

GITHUB_CLIENT_ID=seu_client_id
GITHUB_CLIENT_SECRET=seu_client_secret
NEXTAUTH_SECRET=gere_uma_chave_forte
NEXTAUTH_URL=http://localhost:3000

Gerar NEXTAUTH_SECRET (exemplo):

openssl rand -base64 32

3) Instalar dependências e executar

npm install
npm run dev

Aplicação local: http://localhost:3000

Scripts

npm run dev     # desenvolvimento
npm run build   # build de produção
npm run start   # iniciar build local
npm run lint    # lint

Deploy na Vercel

Variáveis de ambiente (Production)

No projeto da Vercel, configure:

Variável	Descrição
GITHUB_CLIENT_ID	Client ID do OAuth App
GITHUB_CLIENT_SECRET	Client Secret do OAuth App
NEXTAUTH_SECRET	Segredo forte para sessão/jwt
NEXTAUTH_URL	URL canônica da aplicação (ex.: https://seu-projeto.vercel.app)

OAuth em produção

No GitHub OAuth App:

• Homepage URL: https://seu-projeto.vercel.app
• Authorization callback URL: https://seu-projeto.vercel.app/api/auth/callback/github

Publicação

npx vercel --prod

Segurança

• Nunca versionar .env e .env.local.
• O projeto usa .gitignore para proteger variáveis locais.
• Utilize secrets diferentes para local e produção.
• Rotacione GITHUB_CLIENT_SECRET e NEXTAUTH_SECRET em caso de exposição.

Troubleshooting

404: NOT_FOUND na Vercel

Causas comuns:

• deploy não publicado corretamente;
• projeto/domínio/alias apontando para outro escopo;
• token da Vercel inválido na CLI;
• URL acessada diferente de NEXTAUTH_URL.

Checklist rápido:

1. npx vercel ls e confirmar deploy Ready.
2. Validar domínio alias ativo.
3. Confirmar NEXTAUTH_URL em Production.
4. Confirmar callback URL no OAuth App.
5. Reexecutar npx vercel --prod após ajustes.

Erro de login OAuth

• Verifique NEXTAUTH_URL.
• Verifique callback URL no GitHub.
• Confirme que GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET estão no ambiente correto.

Limitações Conhecidas

• A API do GitHub possui rate limits.
• Commits de forks e cenários específicos podem ter variação de contagem.
• A exportação em PDF utiliza diálogo de impressão do navegador.

Roadmap

• Exportação em PDF com template visual avançado.
• Histórico de relatórios por usuário.
• Filtros por período customizado.
• Métricas adicionais por pull requests e review.