DevTrack | Michaell Alavedra

Construí o DevTrack para resolver uma necessidade pessoal e técnica: medir o tempo de programação, analisar minhas métricas de hábitos e calcular ganhos financeiros, sem depender de cronômetros manuais, sem interfaces poluídas e sem enviar meus dados para servidores de terceiros.

Este documento detalha a arquitetura, modelos e funcionamento interno do projeto. Projetei-o dividindo a solução em duas partes principais: um “motor” que vive diretamente dentro do Visual Studio Code (vscode-extension), e um portal de apresentação ou site promocional (landing-page).

A seguir, explico como a ferramenta funciona internamente e as decisões técnicas que tomei para construí-la.

1. O Problema e a Abordagem

A maioria das ferramentas de registro de tempo exige ações manuais (iniciar/pausar) e apresenta interfaces recarregadas de cores que competem pela atenção visual dentro do editor.

Decidi resolver isso baseando-me em três pilares técnicos:

Automação de Eventos: Utilizar a API nativa do VS Code para inferir a atividade do usuário de maneira silenciosa.
Privacidade Local: Aproveitar o globalState do VS Code para que todos os dados residam exclusivamente na máquina do usuário.
Estética Integrada: Utilizar variáveis CSS monocromáticas (--vscode-descriptionForeground) para que o painel de controle se mescle com o tema do editor, evitando poluição visual.

2. Arquitetura da Extensão (VS Code)

Para garantir um código sustentável e escalável, estruturei o diretório vscode-extension sob os princípios de Domain-Driven Design (DDD) utilizando Vertical Slicing.

Modelos e Serviços Core (`src/core/`)

Os serviços compartilhados gerenciam a infraestrutura transversal da extensão:

StorageManager: É a camada de persistência. Em vez de depender de bancos de dados locais pesados, encapsula o acesso ao globalState do VS Code, garantindo escritas eficientes e o isolamento dos dados.
FormattingManager: Centraliza a formatação de datas e moedas. Como o acompanhamento temporal depende estritamente dos reinícios à meia-noite, utilizei a API Intl nativa com o locale en-CA para gerar datas consistentes (YYYY-MM-DD) que respeitem o fuso horário dinâmico do usuário.
SoundPlayer: Para os marcos de receita em tempo real, implementei notificações de áudio (como o som de uma moeda) delegando comandos ao sistema operacional (afplay no macOS, powershell no Windows, aplay no Linux). Se falhar, utiliza a UI nativa do editor como fallback.
DashboardManager: Renderiza a visualização principal utilizando um WebviewPanel. Protegi a visualização mediante políticas restritivas de Content Security Policy (CSP) que permitem apenas scripts de CDN específicos e fontes do Google (Space Grotesk, Geist).

Motor de Rastreamento: O Orchestrator (`src/features/tracker/`)

O coração técnico do DevTrack é o padrão “Observer” implementado através do TrackingOrchestrator.

Em vez de ter múltiplos ciclos escutando eventos independentes de forma caótica, o orquestrador:

Subscreve-se aos eventos fundamentais da API (ex: onDidChangeActiveTextEditor, onDidChangeTextDocument, onDidChangeWindowState).
Mantém um ciclo interno (“tick”) de 1 segundo.
Calcula a inatividade. Se o usuário parar de interagir, interrompe o ciclo de maneira autônoma.
Retransmite este “tick” a um conjunto de Trackers independentes que implementam uma interface comum.

Módulos Analíticos (Hábitos e Tempo)

Implementei módulos especializados (Trackers) que processam a retransmissão do orquestrador de maneira desacoplada:

TimeActivityTracker: Contabiliza a sessão com base em uma tarifa (devTrack.hourlyRate) e despacha os eventos financeiros.
FlowStateTracker: Calcula os períodos ininterruptos de atividade pura.
ContextSwitchTracker: Conta quantas vezes a janela do editor é alterada para medir a perda de foco.
AIAssistanceTracker: Quantifica qual porcentagem do código finalizado provém de digitação manual vs inserções automáticas (como as geradas por assistentes de IA).
CommitTracker e LintTracker: Monitoram operações externas lendo os registros de .git/logs/HEAD e consumindo eventos de diagnóstico (onDidChangeDiagnostics), respectivamente.

3. Visualização de Dados (O Dashboard)

Para o lado do cliente (dentro do WebviewPanel), evitei empacotar grandes frameworks como React ou Vue. Optei por renderização nativa em TypeScript que injeta HTML pré-computado.

Para as métricas:

Utilizei Chart.js focado quase exclusivamente em doughnut charts em escala de cinza.
Implementei um heatmap anual (similar ao GitHub) utilizando um sistema de CSS Grid puro em vez de bibliotecas de gráficos pesadas.
Adicionei suporte para geração de relatórios em PDF/Imagem combinando html2canvas e jspdf, processando os nós do DOM no lado do cliente e retornando um Blob baixável ao usuário através do protocolo do Webview.

4. Stack da Landing Page Promocional

Para apresentar o projeto, desenvolvi um site de apresentação rápida (localizado em landing-page/). O foco principal aqui foi o desempenho e o SEO:

Astro + React: Astro atua como o motor de “Zero-JS” por padrão, gerando HTML estático, enquanto encapsulei a interatividade complexa em ilhas de React.
Tailwind CSS v4: Utilizei a nova sintaxe via @tailwindcss/postcss. A configuração completa de temas (incluindo suporte ao Dark Mode via variante @custom-variant dark) reside diretamente no CSS global sem necessidade de um arquivo tailwind.config.js.
Iconografia Moderna: Implementou-se lucide-react para manter uma estética consistente, profissional e minimalista em todos os ícones do site, em vez de usar SVGs planos codificados diretamente no código.
Otimização e PWA: A landing page conta com configurações de SEO (incluindo tags OpenGraph e imagens) e um manifest.json inicial para habilitar capacidades de PWA.
Ferramentas de Controle: Tanto o projeto web quanto o da extensão utilizam o Biome como linter e formatador oficial para padronizar a convenção de código baseada em tabulações.