refactor: migrate database layer from SQLite to TypeORM with PostgreSQL support

Author: joaltoroc

.agents/AGENTS.md

@@ -15,19 +15,20 @@ This file documents workspace-specific rules, patterns, and guidelines that all
 * **Metrics Security**: The metrics endpoints under `/api/metrics` must always require a valid `METRICS_KEY`. If `METRICS_KEY` is not set in the environment, the endpoints must respond with `403 Forbidden` rather than falling back to public access.
 * **Rate Limiting**: Rate limiting is configured at `/api/` using `express-rate-limit`. Do not bypass or remove this unless instructed. If adding new endpoints, ensure they are protected by the rate limiter.
 * **Security Headers**: `helmet` is used to enforce secure headers. Keep `contentSecurityPolicy: false` to allow inline CSS inside the generated SVG cards.
+* **Environment Secrets**: Do NOT attempt to read, write, or modify the `.env` file (or any other local environment files containing secrets/configurations) directly. Always output or present the required environment key templates to the user so they can configure them manually.
 
 ## Docker Guidelines
 * **Non-Root Execution**: The runner stage must run as the non-privileged `node` user (`USER node`).
 * **Precise COPY**: Avoid using trailing wildcards/globs in `COPY` commands (e.g. `COPY package.json pnpm-lock.yaml* ...`) if the files are known to exist. List them explicitly to avoid matching unintended files.
-* **Volume Mounts**: The persistent SQLite database is stored in `/usr/src/app/data`. Ensure this directory is declared as a `VOLUME` and has its owner set to `node` (`chown -R node:node /usr/src/app`).
 
 ## Codebase Patterns
-* **SQLite Database**: We use the native `sqlite3` driver in WAL mode for high concurrency. Run database modifications inside `db.serialize()` to ensure proper ordering.
+* **PostgreSQL Database**: We use PostgreSQL managed through TypeORM for security and concurrency. Avoid using raw SQL queries; instead, use the Active Record / Data Mapper repositories or QueryBuilder parameterized bindings to prevent SQL Injection.
 * **SVG Cards**: Cards are rendered directly as SVG strings in server code and cached for 2 hours. If returning an error on a card endpoint, always send the response as `Content-Type: image/svg+xml` containing an SVG representation of the error card (e.g., using `renderErrorCard(message)`), so it renders correctly inside `<img>` tags on GitHub.
 * **Package Manager**: Use `pnpm` exclusively. Never run `npm install` or `yarn` inside this workspace. Run test suite using `pnpm test`.
 
 ## Release & Version Management
 * **release-it**: The repository uses `release-it` to manage semantic versioning and automate changelog generation.
 * **Commands**: Run `pnpm release` from the `main` branch to trigger a new release.
 * **Conventional Commits**: Commit messages must follow the Conventional Commits specification (e.g. `feat: ...`, `fix: ...`, `chore: ...`) to enable automatic changelog generation.
+* **Documentation Synchronization**: AI coding agents MUST update all relevant markdown files (`README.md`, `CHANGELOG.md`, etc.) on every modification that changes architecture, configuration keys, or deployment steps to ensure documentation is always synchronized.
 

.env.example

@@ -4,3 +4,17 @@ PORT=3000
 GITHUB_TOKEN=
 # Key to protect access to the /api/metrics and /api/metrics/users endpoints
 METRICS_KEY=
+
+DB_HOST=
+DB_PORT=
+DB_DATABASE=
+DB_USERNAME=
+DB_PASSWORD=
+DB_SSL=
+DB_SYNCHRONIZE=
+
+# Private statistics configuration status (set to false to enable/activate the feature, defaults to true)
+PRIVATE_STATS_COMING_SOON=true
+
+# Frecuencia en horas para guardar instantáneas del historial de estadísticas del usuario
+STATS_HISTORY_FREQUENCY_HOURS=12

.gitignore

@@ -37,8 +37,8 @@ Thumbs.db
 # Testing
 coverage/
 .nyc_output/
-data/metrics.sqlite-shm
-data/metrics.sqlite-wal
 
 # Agents Customization Skills
 .agents/skills/
+design-system/
+skills-lock.json

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Todos los cambios notables en este proyecto serán documentados en este archivo.
 
+## [Unreleased]
+
+### 🏗️ Base de Datos
+- **Migración a PostgreSQL con TypeORM**: Reemplazo completo de la base de datos SQLite y su controlador de bajo nivel `sqlite3` por una arquitectura basada en TypeORM con PostgreSQL para mejorar la seguridad (prevención de inyección SQL), concurrencia y flexibilidad de despliegue.
+- **Entidades de Dominio e Infraestructura**: Mapeo completo de las tablas `global_metrics`, `user_metrics`, `request_log` y `user_tokens` mediante decoradores TypeORM.
+
+### 🐳 Docker & Despliegue
+- **Simplificación del Contenedor**: Eliminación del entrypoint script `docker-entrypoint.sh` y la dependencia de volumen persistente local. El contenedor ahora se inicia directamente con el usuario no privilegiado `node`.
+
+### 🔒 Seguridad
+- **Políticas de Secretos**: Modificación de las directrices en `AGENTS.md` prohibiendo la lectura/escritura del archivo `.env` por parte de agentes de IA para salvaguardar secretos locales de producción.
+
 ## [1.1.0] - 2026-07-17
 
 ### ✨ Características

Dockerfile

@@ -22,9 +22,8 @@ RUN pnpm run build
 # Stage 2: Runtime (Production)
 FROM node:24-alpine AS runner
 
-# Install pnpm and su-exec (lightweight privilege-drop tool for Alpine)
-# su-exec is used in docker-entrypoint.sh to drop from root → node user at startup
-RUN npm install -g pnpm && apk add --no-cache su-exec
+# Install pnpm
+RUN npm install -g pnpm
 
 WORKDIR /usr/src/app
 
@@ -40,25 +39,16 @@ RUN pnpm install --prod --frozen-lockfile
 COPY --from=builder /usr/src/app/dist ./dist
 COPY public ./public
 
-# Copy the entrypoint script that fixes volume ownership at startup
-COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
-# Pre-create the data directory so the volume mount point exists
-RUN mkdir -p /usr/src/app/data && chown -R node:node /usr/src/app
-
-# Declare the persistent volume directory for SQLite metrics database
-VOLUME /usr/src/app/data
+# Ensure the app files are owned by the node user
+RUN chown -R node:node /usr/src/app
 
-# NOTE: We intentionally do NOT set USER node here.
-# The entrypoint script runs as root to fix mounted-volume permissions,
-# then drops privileges to 'node' via su-exec before starting the app.
+# Drop privileges to non-root 'node' user
+USER node
 
 # Health check — uses wget (built into Alpine) to probe the /health endpoint.
-# --start-period gives the app time to initialize SQLite before probes begin.
 HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
   CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
 
 EXPOSE 3000
 
-ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+CMD ["node", "dist/server.js"]

README.md

@@ -37,9 +37,10 @@ src/
 ├── adapters/                # Adaptadores de Interfaz (Controladores, Repositorios y Presentadores)
 │   ├── controllers/         # CardController, TokenController, MetricsController
 │   ├── presenters/          # statsCard, languagesCard, theme (Renderizadores de SVGs)
-│   └── repositories/        # SQLiteTokenRepository, SQLiteMetricsRepository, ApiGitHubRepository, CachedGitHubRepository
+│   └── repositories/        # TypeORMTokenRepository, TypeORMMetricsRepository, ApiGitHubRepository, CachedGitHubRepository
 └── infrastructure/          # Detalles técnicos concretos (Base de datos, Servidor Express, Criptografía)
-    ├── database/            # Inicialización de SQLite y migraciones
+    ├── database/            # Configuración de TypeORM con PostgreSQL y Entidades
+    │   └── entities/        # Entidades de base de datos (GlobalMetric, UserMetric, etc.)
     ├── 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)
@@ -73,6 +74,8 @@ El proyecto utiliza alias `@/` apuntando al directorio `src/`. Esto previene la
    - `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 defecto `1`), útil para que el rate limit identifique correctamente las IPs detrás de Cloudflare, Nginx, etc.
+   - `PRIVATE_STATS_COMING_SOON`: Estado de configuración de estadísticas privadas. Establécelo en `false` para habilitar y activar completamente la funcionalidad de registro/revocación de tokens (por defecto `true`).
+   - `STATS_HISTORY_FREQUENCY_HOURS`: Frecuencia mínima en horas entre tomas de instantáneas del historial de estadísticas del usuario (por defecto `12`).
 
 ### Scripts de Desarrollo
 
@@ -152,25 +155,32 @@ Este microservicio implementa las siguientes medidas de seguridad para entornos
 
 ## 🐳 Despliegue en Docker y Coolify
 
-Este proyecto incluye un `Dockerfile` optimizado con builds en multi-etapa y configuración para correr bajo el usuario no root `node`.
+Este proyecto incluye un `Dockerfile` optimizado con builds en multi-etapa y configuración segura que se ejecuta bajo el usuario no root `node`.
 
 ### Pruebas Locales con Docker
-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`:
+
+Dado que la base de datos se ha migrado a PostgreSQL, el contenedor de la aplicación no requiere almacenamiento persistente en disco. Puedes enlazarlo a tu servidor de PostgreSQL local:
 
 1. Construir la imagen:
    ```bash
    docker build -t github-helpers .
    ```
-2. Ejecutar el contenedor con volumen persistente:
+2. Ejecutar el contenedor pasando las credenciales de la base de datos en las variables de entorno:
    ```bash
-   docker run -d -p 3000:3000 --name github-helpers-app -v github-helpers-db:/usr/src/app/data --env-file .env github-helpers
+   docker run -d -p 3000:3000 --name github-helpers-app --env-file .env github-helpers
    ```
 
 ### Despliegue en Coolify
 1. Crea un nuevo recurso de tipo **Application** en tu panel de Coolify.
 2. Selecciona **GitHub Repository** como fuente y apunta a este repositorio.
 3. En la configuración de construcción, selecciona **Dockerfile**.
 4. Configura el puerto de exposición en el puerto `3000`.
-5. **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.
-6. Agrega las variables de entorno en la pestaña `Environment Variables` (ej. `GITHUB_TOKEN`, `METRICS_KEY`).
-7. Haz clic en **Deploy**. Coolify leerá el `Dockerfile`, construirá el contenedor seguro de producción y lo pondrá en marcha con SSL automático.
+5. **Base de Datos**: Añade un servicio de base de datos **PostgreSQL** en Coolify.
+6. **Variables de Entorno**: Agrega en la pestaña `Environment Variables` los datos de acceso de la base de datos y tus tokens de seguridad:
+   * `DB_HOST`: Host de tu base de datos PostgreSQL de Coolify.
+   * `DB_PORT`: `5432`
+   * `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`: Datos de tu base de datos PostgreSQL.
+   * `DB_SSL`: `'true'` (si la base de datos requiere SSL).
+   * `DB_SYNCHRONIZE`: `'true'` (si deseas que cree las tablas al iniciar la primera vez).
+   * `GITHUB_TOKEN`, `METRICS_KEY`, `TRUST_PROXY`.
+7. Haz clic en **Deploy**. Coolify construirá el contenedor seguro de producción y lo pondrá en marcha con SSL automático.

data/metrics.sqlite

@@ -22,15 +22,18 @@
     "express": "5.2.1",
     "express-rate-limit": "8.6.0",
     "helmet": "8.3.0",
-    "sqlite3": "6.0.1"
+    "pg": "^8.22.0",
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "^1.1.0"
   },
   "devDependencies": {
     "@release-it/conventional-changelog": "11.0.1",
     "@types/cors": "2.8.19",
     "@types/express": "5.0.6",
     "@types/node": "26.1.1",
-    "@typescript-eslint/eslint-plugin": "8.64.0",
-    "@typescript-eslint/parser": "8.64.0",
+    "@types/pg": "^8.20.0",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
     "eslint": "10.7.0",
     "eslint-config-prettier": "10.1.8",
     "prettier": "3.9.5",