DevTrack | Michaell Alavedra

Construí DevTrack para resolver una necesidad personal y técnica: medir el tiempo de programación, analizar mis métricas de hábitos y calcular ganancias financieras, pero sin depender de cronómetros manuales, sin interfaces llenas de ruido y sin enviar mis datos a servidores de terceros.

Este documento detalla la arquitectura, modelos y funcionamiento interno del proyecto. Lo he diseñado dividiendo la solución en dos partes principales: un “motor” que vive directamente dentro de Visual Studio Code (vscode-extension), y un portal de presentación o sitio web promocional (landing-page).

A continuación, explico cómo funciona la herramienta por dentro y las decisiones técnicas que tomé para su construcción.

1. El Problema y el Enfoque

La mayoría de herramientas de registro de tiempo exigen acciones manuales (iniciar/pausar) y presentan interfaces recargadas de colores que compiten por la atención visual dentro del editor.

Decidí resolver esto basándome en tres pilares técnicos:

Automatización de Eventos: Utilizar la API nativa de VS Code para inferir la actividad del usuario de manera silenciosa.
Privacidad Local: Aprovechar el globalState de VS Code para que todos los datos residan exclusivamente en la máquina del usuario.
Estética Integrada: Utilizar variables CSS monocromáticas (--vscode-descriptionForeground) para que el panel de control se difumine con el tema del editor, evitando un “notification-hell”.

2. Arquitectura de la Extensión (VS Code)

Para garantizar un código mantenible y escalable, estructuré el directorio vscode-extension bajo los principios de Domain-Driven Design (DDD) utilizando Vertical Slicing.

Modelos y Servicios Core (`src/core/`)

Los servicios compartidos manejan la infraestructura transversal de la extensión:

StorageManager: Es la capa de persistencia. En lugar de depender de bases de datos locales pesadas, encapsula el acceso al globalState de VS Code, garantizando escrituras eficientes y el aislamiento de los datos.
FormattingManager: Centraliza el formato de fechas y moneda. Dado que el seguimiento temporal depende estrictamente de los reinicios a la medianoche, utilicé la API Intl nativa con el locale en-CA para generar fechas consistentes (YYYY-MM-DD) que respeten la zona horaria dinámica del usuario.
SoundPlayer: Para los hitos de ganancias en tiempo real, implementé notificaciones de audio (como el sonido de una moneda) delegando a comandos del sistema operativo (afplay en macOS, powershell en Windows, aplay en Linux). Si falla, utiliza la UI nativa del editor como fallback.
DashboardManager: Renderiza la vista principal utilizando un WebviewPanel. Aseguré la vista mediante políticas restrictivas de Content Security Policy (CSP) que solo permiten scripts de CDN específicos y fuentes de Google (Space Grotesk, Geist).

Motor de Seguimiento: El Orchestrator (`src/features/tracker/`)

El corazón técnico de DevTrack es el patrón “Observer” implementado a través del TrackingOrchestrator.

En lugar de tener múltiples ciclos escuchando eventos independientes de forma caótica, el orquestador:

Se suscribe a los eventos fundamentales de la API (ej: onDidChangeActiveTextEditor, onDidChangeTextDocument, onDidChangeWindowState).
Mantiene un ciclo interno (“tick”) de 1 segundo.
Calcula la inactividad. Si el usuario deja de interactuar, detiene el ciclo de manera autónoma.
Retransmite este “tick” a un conjunto de Trackers independientes que implementan una interfaz común.

Módulos Analíticos (Hábitos y Tiempo)

Implementé módulos especializados (Trackers) que procesan la retransmisión del orquestador de manera desacoplada:

TimeActivityTracker: Contabiliza la sesión en base a una tarifa (devTrack.hourlyRate) y despacha los eventos financieros.
FlowStateTracker: Calcula los períodos ininterrumpidos de actividad pura.
ContextSwitchTracker: Cuenta cuántas veces se cambia la ventana del editor para medir la pérdida de foco.
AIAssistanceTracker: Cuantifica qué porcentaje del código finalizado proviene del tecleo manual vs inserciones automáticas (como las generadas por asistentes de IA).
CommitTracker y LintTracker: Monitorean operaciones externas leyendo los registros de .git/logs/HEAD y consumiendo eventos de diagnóstico (onDidChangeDiagnostics), respectivamente.

3. Visualización de Datos (El Dashboard)

Para el lado del cliente (dentro del WebviewPanel), evité empaquetar grandes frameworks como React o Vue. Opté por renderizado nativo en TypeScript que inyecta HTML pre-computado.

Para las métricas:

Utilicé Chart.js enfocado casi exclusivamente en doughnut charts en escala de grises.
Implementé un heatmap anual (similar a GitHub) utilizando un sistema de CSS Grid puro en lugar de librerías de gráficos pesadas.
Añadí soporte para generación de reportes en PDF/Imagen combinando html2canvas y jspdf, procesando los nodos del DOM en el lado del cliente y devolviendo un Blob descargable al usuario a través del protocolo del Webview.

4. Stack de la Landing Page Promocional

Para presentar el proyecto, desarrollé un sitio de presentación rápida (ubicado en landing-page/). El enfoque principal aquí fue el rendimiento y el SEO:

Astro + React: Astro actúa como el motor de “Zero-JS” por defecto, generando HTML estático, mientras que encapsulé la interactividad compleja en islas de React.
Tailwind CSS v4: Utilicé la nueva sintaxis vía @tailwindcss/postcss. La configuración completa de temas (incluyendo el soporte a Dark Mode vía la variante @custom-variant dark) reside directamente en el CSS global sin necesidad de un archivo tailwind.config.js.
Iconografía Moderna: Se implementó lucide-react para mantener una estética consistente, profesional y minimalista en todos los iconos del sitio en lugar de usar SVGs planos quemados en el código.
Optimización y PWA: La landing page cuenta con configuraciones SEO (incluyendo OpenGraph tags e imágenes) y un manifest.json inicial para habilitar capacidades de PWA.
Herramientas de Control: Ambos proyectos, web y extensión, utilizan Biome como linter y formateador oficial para estandarizar la convención de código con tabs.