docs(root): initialize project documentation and technical blueprint

devsebastian44 · devsebastian44 · commit f42ba9935d11 · 2026-04-01T14:43:08.000-05:00
diff --git a/README.md b/README.md
@@ -1,96 +1,278 @@
-# CollabData - Plataforma Colaborativa de Ingeniería de Datos
+# 📊 CollabData
 
-Esta es una aplicación Next.js construida con Firebase Studio. Es una plataforma diseñada para que equipos de datos colaboren en ingeniería y análisis de datos.
+![Next.js](https://img.shields.io/badge/Next.js-15+-black?style=flat&logo=nextdotjs&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat&logo=typescript&logoColor=white)
+![Firebase](https://img.shields.io/badge/Firebase-App%20Hosting-FFCA28?style=flat&logo=firebase&logoColor=black)
+![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-3.x-06B6D4?style=flat&logo=tailwindcss&logoColor=white)
+![Genkit](https://img.shields.io/badge/Google%20Genkit-AI%20Flows-4285F4?style=flat&logo=google&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-green?style=flat&logo=opensourceinitiative&logoColor=white)
 
-## 📝 Descripción del Proyecto
+> 🌐 **Live Demo:** [collabdata.vercel.app](https://collabdata.vercel.app)
 
-CollabData es una plataforma web que permite a los usuarios gestionar proyectos de análisis de datos, cargar conjuntos de datos (datasets), ejecutar análisis automatizados y visualizar los resultados. La aplicación está diseñada con un enfoque en la colaboración en tiempo real y la eficiencia del flujo de trabajo.
+---
 
-## 🔑 Características Principales
+## 🧠 Overview
 
-- **🔐 Autenticación de Usuarios:** Sistema completo de inicio de sesión, registro y autenticación social usando Google y GitHub.
-- **📊 Panel de Control (Dashboard):** Un panel central para ver, buscar, filtrar y gestionar todos los proyectos de análisis.
-- **✨ Creación de Nuevos Análisis:** Un flujo guiado para crear nuevos proyectos de análisis, configurar herramientas y cargar conjuntos de datos.
-- **📈 Visualización de Resultados:** Paneles de resultados dinámicos con KPIs, gráficos, tablas de estadísticas descriptivas e insights generados por IA.
-- **💻 Espacio de Trabajo Interactivo:** Un entorno similar a un IDE para explorar archivos de datos.
-- **👤 Gestión de Perfil:** Página de ajustes para que los usuarios actualicen su información personal y gestionen su cuenta.
-- **🤖 Integración de IA:** Utiliza Genkit para proporcionar sugerencias de análisis inteligentes basadas en las descripciones de los datasets.
+**CollabData** es una plataforma web full-stack orientada a equipos de ingeniería y análisis de datos. Construida sobre el ecosistema **Next.js 15 con App Router** y respaldada por **Firebase** como infraestructura de backend, la aplicación permite a múltiples usuarios gestionar proyectos de análisis de datos, cargar conjuntos de datos, obtener visualizaciones de resultados y recibir sugerencias inteligentes generadas por modelos de IA a través de **Google Genkit**.
 
-## 🛠️ Stack Tecnológico
+El proyecto combina una arquitectura moderna de frontend orientada a componentes (React + ShadCN UI + Tailwind CSS) con un backend serverless basado en Firebase Authentication y Firestore, y se despliega mediante **Firebase App Hosting** con integración de CI/CD a través de **GitHub Actions**. El entorno de desarrollo está configurado para trabajar con **Firebase Studio (Project IDX)**.
 
-- **Framework:** [Next.js](https://nextjs.org/)
-- **Biblioteca UI:** [React](https://react.dev/)
-- **Lenguaje:** [TypeScript](https://www.typescriptlang.org/)
-- **Estilos:** [Tailwind CSS](https://tailwindcss.com/)
-- **Componentes UI:** [ShadCN UI](https://ui.shadcn.com/)
-- **Backend y Autenticación:** [Firebase](https://firebase.google.com/) (Authentication, Firestore)
-- **IA Generativa:** [Genkit](https://firebase.google.com/docs/genkit) (Google AI)
+---
 
-## 🚀 Cómo Empezar
+## ⚙️ Features
 
-Sigue estos pasos para poner en marcha el entorno de desarrollo.
+- **Autenticación social completa** mediante Firebase Authentication, con soporte para inicio de sesión con Google y GitHub, además de registro por email y contraseña.
+- **Dashboard centralizado de proyectos** con capacidades de búsqueda, filtrado y gestión visual de todos los análisis del usuario.
+- **Flujo guiado de creación de análisis** que permite definir configuración, seleccionar herramientas de procesamiento y cargar datasets paso a paso.
+- **Espacio de trabajo interactivo por proyecto** con una interfaz similar a un IDE para explorar la estructura de archivos de datos cargados.
+- **Visualización dinámica de resultados** que incluye paneles de KPIs, gráficos de análisis, tablas de estadísticas descriptivas y resúmenes ejecutivos.
+- **Sugerencias de análisis impulsadas por IA** mediante flujos de Genkit (Google AI) que interpretan las descripciones de los datasets y proponen estrategias de análisis.
+- **Gestión de perfil de usuario** con página de ajustes para actualizar información personal y preferencias de cuenta.
+- **Sistema de hooks de estado** para gestión reactiva del estado de los proyectos a lo largo de la sesión del usuario.
+- **CI/CD integrado** mediante GitHub Actions para automatizar el pipeline de validación y despliegue.
+- **Soporte nativo para RSC** (React Server Components) con tipado estricto a través de TypeScript en toda la codebase.
+
+---
+
+## 🛠️ Tech Stack
+
+| Categoría | Tecnología |
+|---|---|
+| Framework web | Next.js 15+ (App Router) |
+| Lenguaje | TypeScript 5.x |
+| Biblioteca UI | React + ShadCN UI |
+| Estilos | Tailwind CSS 3.x |
+| Iconografía | Lucide React |
+| Backend & Auth | Firebase Authentication + Firestore |
+| Hosting | Firebase App Hosting + Vercel |
+| IA Generativa | Google Genkit (AI Flows) |
+| Linting | ESLint + Prettier |
+| CI/CD | GitHub Actions |
+| Dev Environment | Firebase Studio / Project IDX |
+| Package Manager | npm |
+| Node versioning | `.nvmrc` (Node 18+) |
+
+---
+
+## 📦 Installation
 
 ### Prerrequisitos
 
-- Node.js (v18 o superior)
-- npm
+- **Node.js** v18 o superior (gestionado via `.nvmrc`)
+- **npm** v9+
+- Una cuenta en **Firebase** con un proyecto creado
+- Acceso a **Google AI / Genkit** (para los flujos de IA)
+
+### 1. Clonar el repositorio
+```bash
+git clone https://github.com/devsebastian44/CollabData.git
+cd CollabData
+```
+
+### 2. Usar la versión correcta de Node
+```bash
+nvm use
+```
+
+### 3. Instalar dependencias
+```bash
+npm install
+```
+
+### 4. Configurar variables de entorno
+
+Crea un archivo `.env.local` en la raíz del proyecto con tus credenciales de Firebase y Genkit:
+```env
+# Firebase
+NEXT_PUBLIC_FIREBASE_API_KEY=
+NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
+NEXT_PUBLIC_FIREBASE_PROJECT_ID=
+NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
+NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
+NEXT_PUBLIC_FIREBASE_APP_ID=
+
+# Google AI / Genkit
+GOOGLE_GENAI_API_KEY=
+```
 
-### Instalación y Ejecución
+### 5. Configurar Firebase
 
-1.  Instala las dependencias del proyecto:
-    ```sh
-    npm install
-    ```
-2.  Inicia el servidor de desarrollo:
-    ```sh
-    npm run dev
-    ```
-3.  Abre [http://localhost:9002](http://localhost:9002) en tu navegador para ver la aplicación.
+Asegúrate de que tu proyecto Firebase esté correctamente referenciado en `.firebaserc`:
+```json
+{
+  "projects": {
+    "default": "tu-proyecto-firebase-id"
+  }
+}
+```
+
+---
+
+## ▶️ Usage
+
+### Servidor de desarrollo
+```bash
+npm run dev
+```
+
+Abre [http://localhost:9002](http://localhost:9002) en tu navegador.
+
+> El servidor Next.js corre en el puerto **9002** por configuración del proyecto.
+
+### Build de producción
+```bash
+npm run build
+npm run start
+```
+
+### Lint del código
+```bash
+npm run lint
+```
+
+### Despliegue en Firebase App Hosting
+
+El despliegue se gestiona automáticamente a través de **GitHub Actions** al hacer push a la rama principal. De forma manual:
+```bash
+firebase deploy
+```
 
-## 📁 Estructura del Proyecto
+> La configuración en `apphosting.yaml` establece `maxInstances: 1` por defecto. Ajústalo según el tráfico esperado.
 
-Aquí tienes una descripción general de los archivos y directorios más importantes del proyecto:
+---
 
+## 📁 Project Structure
 ```
-/
+CollabData/
+│
+├── .github/
+│   └── workflows/               # Pipelines de CI/CD con GitHub Actions
+│
+├── .idx/                        # Configuración de Firebase Studio / Project IDX
+│
+├── docs/                        # Documentación técnica adicional del proyecto
+│
 ├── src/
-│   ├── app/
-│   │   ├── layout.tsx            # Layout raíz de la aplicación
-│   │   ├── page.tsx              # Landing Page
-│   │   ├── login/page.tsx        # Página de autenticación
-│   │   ├── dashboard/            # Rutas del panel de control
-│   │   │   ├── page.tsx          # Vista principal del dashboard
-│   │   │   ├── layout.tsx        # Layout para las páginas del dashboard
-│   │   │   ├── new-analysis/page.tsx # Página para crear un nuevo análisis
-│   │   │   └── ...
-│   │   └── projects/[id]/        # Rutas para proyectos individuales
-│   │       ├── page.tsx          # Espacio de trabajo del proyecto
-│   │       └── results/page.tsx  # Página de resultados del análisis
+│   ├── app/                     # Next.js App Router — páginas y layouts
+│   │   ├── layout.tsx           # Layout raíz global de la aplicación
+│   │   ├── page.tsx             # Landing page pública
+│   │   ├── login/
+│   │   │   └── page.tsx         # Página de autenticación (login / registro)
+│   │   ├── dashboard/
+│   │   │   ├── layout.tsx       # Layout compartido del área privada
+│   │   │   ├── page.tsx         # Vista principal del dashboard de proyectos
+│   │   │   └── new-analysis/
+│   │   │       └── page.tsx     # Flujo de creación de nuevo análisis
+│   │   └── projects/
+│   │       └── [id]/
+│   │           ├── page.tsx     # Espacio de trabajo interactivo del proyecto
+│   │           └── results/
+│   │               └── page.tsx # Panel de resultados y visualizaciones
 │   │
 │   ├── components/
-│   │   ├── layout/               # Componentes de layout (header, footer)
-│   │   ├── pages/                # Componentes específicos de cada página
-│   │   └── ui/                   # Componentes UI reutilizables (ShadCN)
+│   │   ├── layout/              # Componentes estructurales (header, footer, nav)
+│   │   ├── pages/               # Componentes específicos de cada vista
+│   │   └── ui/                  # Biblioteca de componentes ShadCN UI reutilizables
 │   │
 │   ├── firebase/
-│   │   ├── config.ts             # Configuración de Firebase
-│   │   ├── index.ts              # Inicialización y exportación de servicios Firebase
-│   │   ├── provider.tsx          # Proveedor de contexto Firebase
-│   │   └── auth/use-user.tsx     # Hook para obtener el usuario autenticado
+│   │   ├── config.ts            # Inicialización y configuración del SDK de Firebase
+│   │   ├── index.ts             # Exportación centralizada de servicios Firebase
+│   │   ├── provider.tsx         # Context Provider de Firebase para toda la app
+│   │   └── auth/
+│   │       └── use-user.tsx     # Hook personalizado para obtener el usuario autenticado
 │   │
 │   ├── ai/
-│   │   ├── genkit.ts             # Inicialización de Genkit
-│   │   └── flows/                # Flujos de IA con Genkit
+│   │   ├── genkit.ts            # Inicialización de la instancia de Genkit
+│   │   └── flows/               # Definición de flujos de IA (análisis de datasets)
 │   │
 │   ├── hooks/
-│   │   └── use-project-store.ts  # Hook para la gestión del estado del proyecto
+│   │   └── use-project-store.ts # Hook de gestión de estado global de proyectos
 │   │
 │   └── lib/
-│       ├── utils.ts              # Funciones de utilidad
-│       ├── mock-data.ts          # Datos de ejemplo para la aplicación
-│       └── types.ts              # Definiciones de tipos TypeScript
+│       ├── utils.ts             # Funciones de utilidad generales (cn, formatters, etc.)
+│       ├── mock-data.ts         # Datos de ejemplo para desarrollo y prototipado
+│       └── types.ts             # Definiciones de tipos e interfaces TypeScript globales
 │
-├── public/                     # Archivos estáticos
-├── package.json                # Dependencias y scripts del proyecto
-└── tailwind.config.ts          # Configuración de Tailwind CSS
+├── public/                      # Archivos estáticos (imágenes, iconos, fonts)
+│
+├── .firebaserc                  # Referencia al proyecto Firebase activo
+├── .gitignore                   # Exclusiones de Git (node_modules, .env.local, etc.)
+├── .nvmrc                       # Versión de Node.js fijada para el proyecto
+├── apphosting.yaml              # Configuración de Firebase App Hosting
+├── components.json              # Configuración de ShadCN UI (estilo, aliases, iconos)
+├── eslint.config.js             # Configuración de ESLint
+├── next.config.ts               # Configuración de Next.js (remote images, etc.)
+├── package.json                 # Dependencias y scripts del proyecto
+├── postcss.config.mjs           # Configuración de PostCSS (requerido por Tailwind)
+├── prettier.config.js           # Reglas de formateo de código
+├── tailwind.config.ts           # Configuración de Tailwind CSS
+└── tsconfig.json                # Configuración del compilador TypeScript
 ```
+
+---
+
+## 🔐 Security
+
+### Autenticación y autorización
+
+La autenticación está completamente delegada a **Firebase Authentication**, lo que garantiza el manejo seguro de credenciales, tokens JWT y sesiones. Las rutas del dashboard son accesibles únicamente por usuarios autenticados, verificados mediante el hook `use-user.tsx` en el lado del cliente.
+
+### Variables de entorno
+
+Todas las claves de API y configuraciones sensibles se gestionan a través de variables de entorno definidas en `.env.local`, el cual está incluido en `.gitignore` y nunca se expone en el repositorio. Las variables prefijadas con `NEXT_PUBLIC_` se exponen al cliente de forma controlada; las variables del lado servidor (como `GOOGLE_GENAI_API_KEY`) permanecen exclusivamente en el entorno de ejecución de Next.js.
+
+### Imágenes externas controladas
+
+El archivo `next.config.ts` define una lista blanca explícita de dominios permitidos para carga de imágenes remotas (`placehold.co`, `images.unsplash.com`, `picsum.photos`), previniendo el abuso del componente `<Image>` de Next.js para cargar contenido de dominios no autorizados.
+
+### Firestore Security Rules
+
+Se recomienda definir **Firestore Security Rules** granulares en la consola de Firebase para garantizar que cada usuario solo pueda leer y escribir sus propios documentos de proyecto, evitando acceso cruzado entre cuentas.
+
+---
+
+## 🚀 Roadmap
+
+Mejoras técnicas sugeridas a partir del análisis de la arquitectura actual del código:
+
+- **Reemplazar `mock-data.ts` por Firestore real en todas las vistas:** La presencia de `mock-data.ts` sugiere que algunas rutas podrían estar funcionando aún con datos estáticos; migrar completamente a Firestore para producción es una mejora prioritaria.
+- **Implementar Firestore Security Rules** con validación por UID de usuario para proteger el acceso a documentos de proyectos y datasets.
+- **Añadir carga real de archivos a Firebase Storage:** Incorporar el SDK de Storage para persistir los datasets subidos por los usuarios más allá de la sesión.
+- **Ampliar los flujos de Genkit** con soporte para múltiples modelos (Gemini Pro, Gemini Flash) y prompts configurables por tipo de dataset.
+- **Tests de integración con Playwright o Cypress:** Automatizar pruebas E2E para los flujos críticos (login, creación de análisis, visualización de resultados).
+- **Escalar `maxInstances` en `apphosting.yaml`** para soportar tráfico concurrente real en producción.
+- **Modo colaborativo en tiempo real** mediante Firestore `onSnapshot` para que múltiples usuarios vean actualizaciones en tiempo real dentro del mismo proyecto.
+- **Exportación de resultados** en formatos PDF, CSV o JSON desde el panel de visualización.
+- **Internacionalización (i18n)** con `next-intl` dado el origen multicultural del proyecto.
+
+---
+
+## 📄 License
+
+Este proyecto está distribuido bajo la licencia **MIT**.
+
+Esto significa que puedes usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del software de forma libre, siempre que se incluya el aviso de copyright original.
+
+Copyright © 2025 **Sebastián Zhunaula** (devsebastian44)
+
+---
+
+## 👨‍💻 Author
+
+<table>
+  <tr>
+    <td align="center">
+      <b>Sebastián Zhunaula</b><br/>
+      <sub>Full-Stack Developer · Frontend Specialist · Data & AI Enthusiast</sub><br/><br/>
+      <a href="https://github.com/devsebastian44">
+        <img src="https://img.shields.io/badge/GitHub-devsebastian44-black?style=flat&logo=github" />
+      </a>
+      <br/><br/>
+      <a href="https://collabdata.vercel.app">
+        <img src="https://img.shields.io/badge/Live%20Demo-CollabData-blue?style=flat&logo=vercel" />
+      </a>
+    </td>
+  </tr>
+</table>
+
+> Este proyecto forma parte de un portafolio de desarrollo web full-stack, demostrando integración moderna de Next.js 15, Firebase, ShadCN UI y Google Genkit en una plataforma de análisis de datos colaborativa lista para producción.
