Este proyecto es un microservicio y cliente web desarrollado en Node.js con TypeScript que permite consultar las estadísticas y los lenguajes de programación más utilizados por cualquier usuario de GitHub en tiempo real, devolviendo imágenes en formato SVG listas para ser incrustadas directamente en el archivo README.md de tus proyectos.
Desarrollado y mantenido por CreativeCode.com.co.
- Clean Architecture (Arquitectura Limpia): Estructurado en capas desacopladas (Dominio, Casos de Uso, Adaptadores e Infraestructura) para garantizar mantenibilidad, testabilidad y escalabilidad.
- API en Vivo (Hot Rendering): Generación de tarjetas SVG al vuelo a través de endpoints con cabeceras
Content-Type: image/svg+xml. - Caché en Memoria (2 horas): Minimiza las llamadas a la API de GitHub para evitar bloqueos por límite de tasa (Rate Limits) mediante el patrón Decorador.
- Imágenes Autocontenidas (Base64 Bypass): Las fotos de perfil se descargan y se convierten a Base64 en el servidor, garantizando que el proxy de imágenes de GitHub (
camo.githubusercontent.com) las muestre sin problemas. - Métricas Clave de Visibilidad:
- Estadísticas Generales: Commits totales, estrellas obtenidas, pull requests, issues y seguidores.
- Lenguajes más Usados: Gráfica de distribución de lenguajes (calculada por peso de bytes) con leyenda estructurada.
- Múltiples Temas Estéticos: Dark, Light, Neon, Solarized, Radical, Tokyonight y Glassmorphism.
- Panel Web Premium (Glassmorphism): Una interfaz web elegante construida en CSS puro con vista previa en tiempo real y copiador de enlaces Markdown automático.
- Pruebas Unitarias Integradas: Implementadas utilizando Vitest con inyección de dependencias.
- Listo para Docker y Coolify: Dockerfile de construcción en múltiples etapas (multi-stage) optimizado para producción.
El código fuente está organizado siguiendo los principios de Clean Architecture:
src/
├── domain/ # Lógica de negocio pura (Entidades y Contratos de Repositorios)
│ ├── entities/ # UserStats, LanguageStat, Metrics, UserToken, Validation
│ └── repositories/ # IGitHubRepository, ITokenRepository, IMetricsRepository
├── use-cases/ # Casos de uso (Orquestadores de la lógica de negocio)
│ ├── cards/ # GetUserStatsCardUseCase, GetUserLanguagesCardUseCase, etc.
│ └── tokens/ # RegisterUserTokenUseCase, RevokeUserTokenUseCase
├── adapters/ # Adaptadores de Interfaz (Controladores, Repositorios y Presentadores)
│ ├── controllers/ # CardController, TokenController, MetricsController
│ ├── presenters/ # statsCard, languagesCard, theme (Renderizadores de SVGs)
│ └── repositories/ # SQLiteTokenRepository, SQLiteMetricsRepository, ApiGitHubRepository, CachedGitHubRepository
└── infrastructure/ # Detalles técnicos concretos (Base de datos, Servidor Express, Criptografía)
├── database/ # Inicialización de SQLite y migraciones
├── express/ # Enrutamiento, middlewares y arranque de servidor Express
├── security/ # Criptografía AES-256-GCM y validación de scopes
└── server.ts # Entrypoint principal (Wrapper de importación limpio y relativo)
El proyecto utiliza alias @/ apuntando al directorio src/. Esto previene la existencia de rutas relativas complejas como ../../.
- En desarrollo: Se resuelve en tiempo de ejecución utilizando
tsconfig-paths/register. - En producción:
tsc-aliasreescribe los imports a rutas relativas nativas durante la compilación en el directoriodist/.
- Node.js v18 o superior.
- (Opcional) Un token de acceso personal (PAT) de GitHub para aumentar el límite de peticiones de la API.
- Clona e ingresa al repositorio.
- Instala las dependencias estables usando
pnpm:pnpm install
- Copia el archivo de configuración de entorno:
cp .env.example .env
- Abre el archivo
.envy configura las siguientes variables clave:GITHUB_TOKEN: Tu token de acceso personal de GitHub para evitar límites de tasa.METRICS_KEY: Clave secreta obligatoria para poder acceder a los endpoints de analíticas (/api/metrics).TRUST_PROXY: Número de saltos del proxy (por defecto1), útil para que el rate limit identifique correctamente las IPs detrás de Cloudflare, Nginx, etc.
- Modo Desarrollo (auto-reload y resolución de paths):
pnpm dev
- Ejecutar Pruebas Unitarias (Vitest):
pnpm test - Compilar para Producción (compila archivos TS y reescribe alias):
pnpm build
- Iniciar Servidor Compilado:
pnpm start
- Gestionar Versiones y Releases (release-it):
pnpm release
Una vez ejecutado, el panel de configuración estará disponible en:
👉 http://localhost:3000
Este proyecto utiliza release-it junto con la especificación de Conventional Commits para automatizar los lanzamientos de versión.
Cuando ejecutas pnpm release:
- Analiza el historial de commits desde la última versión.
- Calcula el incremento de versión correspondiente (Major, Minor, Patch).
- Actualiza la versión en
package.jsony genera/actualiza el archivoCHANGELOG.md. - Realiza un commit con los cambios, crea la etiqueta (git tag) y sube todo a GitHub.
- Crea un Release oficial en GitHub con el log de cambios automático.
Las tarjetas se pueden incrustar en cualquier archivo Markdown usando la siguiente sintaxis:
- Parámetros:
username(Obligatorio): Nombre de usuario en GitHub. Valida con regex/^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i.theme(Opcional):dark(por defecto),light,neon,glassmorphism,solarized,radical,tokyonight.
- Parámetros:
username(Obligatorio): Nombre de usuario en GitHub.theme(Opcional): Mismos temas que la tarjeta de estadísticas.
Este microservicio implementa las siguientes medidas de seguridad para entornos de producción:
- Cabeceras Seguras (Helmet): Configurado con políticas de recursos de origen cruzado (
cross-origin) para permitir incrustar de forma segura las tarjetas en READMEs externos. - Rate Limiting: Límite de 100 peticiones cada 15 minutos por dirección IP. En caso de bloqueo, responde con un SVG legible para evitar errores de renderizado de imágenes.
- Validación de Parámetros por Expresión Regular:
- Validado a nivel de Controller y en la capa de negocio de Use Cases.
- Username:
/^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i - Repo:
/^[a-z\d-_.]{1,100}$/i
- Estadísticas Privadas (Coming Soon - Doble Defensa):
- Las características de almacenamiento cifrado de PATs personales de GitHub están marcadas en la interfaz frontend como deshabilitadas e inactivas.
- Como doble defensa contra manipulaciones del DOM en el navegador, los casos de uso del backend (
RegisterUserTokenUseCaseyRevokeUserTokenUseCase) lanzan un error explícito de indisponibilidad si son llamados directamente en el API.
- Secure by Default: Los endpoints de métricas se bloquean por defecto con error
403si no se configura la variableMETRICS_KEY.
Este proyecto incluye un Dockerfile optimizado con builds en multi-etapa y configuración para correr bajo el usuario no root node.
Para evitar perder el histórico de métricas (base de datos SQLite) cuando se recrea o actualiza el contenedor, debes montar un volumen persistente apuntando al directorio /usr/src/app/data:
- Construir la imagen:
docker build -t github-helpers . - Ejecutar el contenedor con volumen persistente:
docker run -d -p 3000:3000 --name github-helpers-app -v github-helpers-db:/usr/src/app/data --env-file .env github-helpers
- Crea un nuevo recurso de tipo Application en tu panel de Coolify.
- Selecciona GitHub Repository como fuente y apunta a este repositorio.
- En la configuración de construcción, selecciona Dockerfile.
- Configura el puerto de exposición en el puerto
3000. - Persistencia: En la pestaña Storages, crea un volumen para montar en la ruta
/usr/src/app/data(ej.db-data:/usr/src/app/data). Esto asegurará que tu base de datos SQLite no se pierda en cada despliegue. - Agrega las variables de entorno en la pestaña
Environment Variables(ej.GITHUB_TOKEN,METRICS_KEY). - Haz clic en Deploy. Coolify leerá el
Dockerfile, construirá el contenedor seguro de producción y lo pondrá en marcha con SSL automático.