SQLite Spreadsheet Sync

Una aplicación web interactiva que centraliza datos relacionales en una base de datos SQLite, ofreciendo una interfaz de usuario similar a Excel / Google Sheets para reducir la fricción en equipos de trabajo no técnicos.

Esto previene la desincronización y pérdida de información provocada por el uso de múltiples archivos de Excel locales dispersos.

🚀 Características

• Pestañas por Tabla: Navegación inmediata entre las tablas de la base de datos central.

• Edición tipo Excel: Edición directa de celdas con doble clic, navegación con teclado (Tab, Enter, Flechas) y autoguardado en base de datos.

• Importación y Consolidación: Sube archivos Excel .xlsx o .csv sueltos para crear tablas automáticamente o añadir registros en lote.

• Exportación Directa: Descarga cualquier tabla activa de la base de datos de vuelta a formato Excel en un clic.

• Validación en Tiempo Real: Evita la corrupción de datos alertando al usuario si ingresa tipos incompatibles (ej. texto en campos numéricos).

• Gestión de Estructura: Crea tablas nuevas y añade columnas directamente desde la interfaz gráfica.

Related MCP server: instant-db

📚 Documentación

• Especificación de la API REST — endpoints, autenticación, validación y errores.

• Servidor MCP — integración con asistentes (Claude, etc.) vía Model Context Protocol.

• Modelo de Seguridad — defensas implementadas y hardening de despliegue.

• Guía de Contribución — puesta en marcha, smoke test y convenciones.

• .env.example — variables de entorno de configuración.

🛠️ Requisitos

• Node.js (Versión 18 o superior recomendada).

💻 Instalación y Configuración

Sigue estos pasos sencillos para poner en marcha el proyecto localmente o en un servidor de red:

1. Instalar todas las dependencias (servidor y cliente en un solo comando):

   npm run install-all

2. Iniciar en modo desarrollo (corre tanto la API Express como el cliente Vite en paralelo):

   npm run dev

3. Acceder a la aplicación:

   • Abre tu navegador en http://localhost:3000

Nota: La API del backend se ejecuta en el puerto 3001 y el frontend se comunica de manera transparente mediante un Proxy.

🔒 Despliegue en Producción

Recomendamos usar Docker Compose para despliegues de producción, ya que incluye persistencia automática de volumen y una imagen multi-stage optimizada.

1. Levantar el servicio:

   docker compose up -d --build

2. Variables de entorno (.env):

Si vas a exponer el sistema en una red local o en internet, debes activar la seguridad usando el archivo .env:

API_KEY=tu_contraseña_secreta_super_segura
ALLOWED_ORIGIN=https://tu-dominio-frontend.com
DB_PATH=/data/data.db
UPLOADS_DIR=/data/uploads/

• API_KEY: Activa la autenticación en todos los endpoints de la API.

• ALLOWED_ORIGIN: Restringe el acceso CORS. Por defecto es http://localhost:3000.

• DB_PATH y UPLOADS_DIR: Configuradas por defecto en el Dockerfile para apuntar al volumen montado /data, asegurando que la base de datos y archivos temporales sobrevivan a reinicios del contenedor.

📁 Estructura del Proyecto

sqlite-spreadsheet-sync/
├── package.json          # Dependencias y scripts globales de ejecución
├── server.js             # API REST en Express para operaciones SQLite e Import/Export
├── database.js           # Módulo de base de datos SQLite y helpers relacionales
├── data.db               # Archivo físico de la base de datos SQLite (se genera auto)
└── frontend/             # Código fuente de la interfaz React + Vite
    ├── package.json      # Dependencias del cliente
    ├── vite.config.js    # Proxy de comunicación configurado
    ├── index.html        # Plantilla principal HTML
    └── src/
        ├── main.jsx      # Entrada de ejecución React
        ├── App.jsx       # Componentes de UI, modales y lógica de comunicación
        └── App.css       # Estilos premium, animaciones y temas oscuros

📝 Comandos Útiles

• Instalar backend: npm install

• Instalar frontend: npm run install-frontend

• Iniciar backend solo: npm run server (http://localhost:3001)

• Iniciar frontend solo: npm run client (http://localhost:3000)

• Ejecutar todo junto (Recomendado): npm run dev

• Servidor MCP (stdio): npm run mcp (ver docs/MCP.md)