🛠️ Stack Tecnológico

Rial AI está construido con tecnologías modernas y escalables que nos permiten ofrecer un servicio robusto y de alta calidad. Nuestro stack está diseñado para manejar grandes volúmenes de procesamiento de imágenes con IA mientras mantiene una experiencia de usuario fluida.

📋 Resumen del Stack

Componente	Tecnología	Versión	Propósito
Backend	NestJS	~10.x	API REST y lógica de negocio
Frontend	Next.js	~14.x	Aplicación web y dashboard
Base de Datos	PostgreSQL (Supabase)	15.x	Almacenamiento de datos
ORM	Prisma	~5.x	Mapeo objeto-relacional
Cloud	Google Cloud Platform	-	Infraestructura y servicios
CI/CD	GitHub Actions	-	Integración y despliegue continuo

🔧 Backend: NestJS

¿Qué es NestJS?

NestJS es un framework de Node.js para construir aplicaciones del lado del servidor eficientes y escalables. Está construido con TypeScript y combina elementos de programación orientada a objetos (OOP), programación funcional (FP) y programación reactiva funcional (FRP).

¿Por qué elegimos NestJS?

Ventajas Principales

🏗️ Arquitectura Modular: Organización clara del código en módulos
🔒 TypeScript Nativo: Type safety completo desde el inicio
🎯 Decoradores: Sintaxis limpia y expresiva
🔌 Dependency Injection: Gestión automática de dependencias
📚 Documentación Automática: Integración con Swagger/OpenAPI
🧪 Testing Integrado: Herramientas de testing incluidas
⚡ Performance: Optimizado para aplicaciones de alto rendimiento

Estructura del Proyecto


src/
├── modules/           # Módulos de la aplicación
│   ├── auth/         # Autenticación y autorización
│   ├── users/        # Gestión de usuarios
│   ├── brands/       # Gestión de marcas
│   ├── projects/     # Proyectos de generación
│   └── images/       # Procesamiento de imágenes
├── common/           # Utilidades compartidas
├── config/           # Configuración de la aplicación
└── main.ts          # Punto de entrada

Documentación y Recursos

Repositorio: github.com/tu-org/rial-backend
Documentación Oficial: nestjs.com
Guías: NestJS Fundamentals

🗄️ ORM: Prisma

¿Qué es Prisma?

Prisma es un ORM (Object-Relational Mapping) de nueva generación que hace que trabajar con bases de datos sea más fácil con un enfoque type-safe para Node.js y TypeScript.

Características Principales

🔍 Type Safety: Tipos automáticos de TypeScript generados desde el esquema
💡 IntelliSense: Auto-completado completo en el IDE
🔄 Migraciones: Gestión de cambios en el esquema de BD
🎯 Query Builder: Constructor de consultas intuitivo
📊 Database Introspection: Generación automática del esquema desde BD existente

Flujo de Trabajo con Prisma

1. Definir el Esquema


// schema.prisma
model User {
  id        Int      @id @default(autoincrement())
  publicId  String   @unique @default(uuid())
  email     String   @unique
  role      UserRole
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  
  company   Company? @relation(fields: [companyId], references: [id])
  companyId Int?
}

2. Generar el Cliente


yarn prisma generate

3. Usar en el Código


// Ejemplo de uso type-safe
const user = await prisma.user.create({
  data: {
    email: 'usuario@ejemplo.com',
    role: 'BRAND_ADMIN',
    company: {
      connect: { id: companyId }
    }
  },
  include: {
    company: true
  }
});

Migraciones

Las migraciones son fundamentales para mantener la consistencia de la base de datos:

¿Qué son las Migraciones?

Las migraciones son scripts SQL que modifican el esquema de la base de datos de forma incremental y controlada.

Comandos Esenciales


# Crear nueva migración en desarrollo
yarn prisma migrate dev --name add_user_table
 
# Aplicar migraciones en producción
yarn prisma migrate deploy
 
# Ver estado de migraciones
yarn prisma migrate status
 
# Resetear BD (solo desarrollo)
yarn prisma migrate reset

Flujo de Migraciones

Desarrollo: Modificas schema.prisma
Migración: Ejecutas prisma migrate dev
Revisión: Prisma genera el SQL automáticamente
Commit: Incluyes la migración en tu commit
Deploy: En producción se ejecuta prisma migrate deploy

Documentación

Documentación Oficial: prisma.io/docs
Schema Reference: Prisma Schema Reference

🌐 Frontend: Next.js

¿Qué es Next.js?

Next.js es un framework de React para producción que proporciona todas las características necesarias para crear aplicaciones web modernas: renderizado híbrido estático y del servidor, soporte para TypeScript, bundling inteligente, prefetching de rutas, y más.

¿Por qué Next.js?

Ventajas Principales

⚡ Performance: Optimizaciones automáticas de rendimiento
🔍 SEO Friendly: Server-Side Rendering (SSR) y Static Site Generation (SSG)
📱 Responsive: Optimización automática de imágenes
🛣️ Routing: Sistema de rutas basado en archivos
🎯 API Routes: Backend integrado para APIs simples
🔧 Zero Config: Configuración mínima requerida
📦 Bundle Optimization: Code splitting automático

Estructura del Proyecto Frontend


src/
├── app/              # App Router (Next.js 13+)
│   ├── dashboard/    # Dashboard de usuario
│   ├── projects/     # Gestión de proyectos
│   ├── api/         # API routes
│   └── layout.tsx   # Layout principal
├── components/       # Componentes reutilizables
├── lib/             # Utilidades y configuración
├── styles/          # Estilos globales
└── types/           # Definiciones de TypeScript

Librerías Importantes del Frontend

Tailwind CSS

¿Qué es? Framework de CSS utility-first que permite crear diseños personalizados rápidamente sin salir del HTML.

Ventajas:

🎨 Utility-First: Clases pequeñas y composables
📱 Responsive: Diseño responsive integrado
🎯 Customizable: Configuración completamente personalizable
⚡ Performance: CSS optimizado automáticamente
🔧 Developer Experience: IntelliSense y auto-completado

Ejemplo de uso:


<div className="bg-white shadow-lg rounded-lg p-6 hover:shadow-xl transition-shadow">
  <h2 className="text-2xl font-bold text-gray-800 mb-4">Título</h2>
  <p className="text-gray-600 leading-relaxed">Contenido...</p>
</div>

Documentación: tailwindcss.com

shadcn/ui

¿Qué es? Colección de componentes de UI reutilizables construidos con Radix UI y Tailwind CSS.

Ventajas:

🧩 Componentes Listos: Biblioteca completa de componentes
♿ Accesibilidad: Componentes accesibles por defecto
🎨 Customizable: Fácil personalización con Tailwind
📱 Responsive: Diseño adaptativo incluido
🔧 Copy & Paste: No es una dependencia, copias el código

Componentes Principales:

Buttons: Botones con variantes y estados
Forms: Inputs, selects, checkboxes
Navigation: Menús, breadcrumbs, tabs
Feedback: Alerts, toasts, modals
Data Display: Tables, cards, badges

Documentación: ui.shadcn.com

Phosphor Icons

¿Qué es? Familia de iconos flexible y minimalista para interfaces web.

Ventajas:

🎯 Consistencia: Estilo visual coherente
⚖️ Múltiples Pesos: Regular, thin, light, bold, fill, duotone
📦 Tree Shaking: Solo importa los iconos que usas
⚡ Performance: Iconos SVG optimizados
🔧 React Ready: Componentes React nativos

Ejemplo de uso:


import { Heart, Star, ShoppingCart } from 'phosphor-react';
 
<Heart size={24} weight="fill" color="#e74c3c" />
<Star size={20} weight="bold" />
<ShoppingCart size={18} />

Documentación: phosphoricons.com

Documentación y Recursos

Repositorio: github.com/tu-org/rial-frontend
Documentación Oficial: nextjs.org
Guías: Next.js Learn

🗄️ Base de Datos: Supabase

¿Qué es Supabase?

Supabase es una alternativa open-source a Firebase que proporciona todas las herramientas backend necesarias para construir un producto: base de datos, autenticación, APIs instantáneas, Edge Functions, Real-time subscriptions, y Storage.

Características Principales

🐘 PostgreSQL: Base de datos relacional completa
⚡ Real-time: Actualizaciones en tiempo real
🔐 Authentication: Sistema de auth completo
📁 Storage: Almacenamiento de archivos
🔧 Edge Functions: Funciones serverless
📊 Dashboard: Panel de administración integrado

¿Por qué Supabase?

Ventajas para Rial AI

📈 Escalabilidad: Maneja el crecimiento automáticamente
🔄 Backup Automático: Copias de seguridad regulares
📊 Monitoring: Métricas y alertas integradas
🌍 Multi-ambiente: Gestión fácil de staging y producción
💰 Costo-efectivo: Pricing transparente y competitivo
🛠️ Developer Experience: Herramientas de desarrollo excelentes

Configuración de Ambientes


# Ambiente de Desarrollo
SUPABASE_URL=https://dev-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
 
# Ambiente de Staging
SUPABASE_URL=https://staging-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
 
# Ambiente de Producción
SUPABASE_URL=https://prod-project.supabase.co
SUPABASE_ANON_KEY=eyJ...

Documentación

Documentación Oficial: supabase.com/docs
PostgreSQL Guide: Supabase PostgreSQL

☁️ Cloud: Google Cloud Platform (GCP)

¿Qué es Google Cloud Platform?

Google Cloud Platform (GCP) es una suite de servicios de computación en la nube que ofrece Google. Proporciona una serie de servicios modulares de nube que incluyen computación, almacenamiento de datos, análisis de datos y machine learning.

Servicios que Utilizamos

Google Cloud Run

¿Qué es? Plataforma de computación serverless que ejecuta contenedores de forma escalable.

Ventajas:

🔄 Auto-scaling: Escala automáticamente según la demanda
💰 Pay-per-use: Solo pagas por el tiempo de ejecución
🐳 Container-based: Ejecuta cualquier lenguaje o framework
⚡ Cold Start Rápido: Arranque rápido de instancias
🌍 Global: Disponible en múltiples regiones

Configuración de Ambientes:

Production: rial-backend-prod y rial-frontend-prod
Staging: rial-backend-staging y rial-frontend-staging

Google Cloud Storage (Buckets)

¿Qué son los Buckets? Contenedores para almacenar archivos en la nube de forma segura y escalable.

¿Por qué los usamos?

📁 Almacenamiento de Imágenes: Todas las imágenes generadas y originales
🔒 Seguridad: Control de acceso granular
🌍 CDN: Distribución global de contenido
💾 Durabilidad: 99.999999999% (11 9’s) de durabilidad
📊 Versionado: Historial de versiones de archivos

Estructura de Buckets:


rial-images-production/
├── garments/          # Imágenes originales de prendas
├── generated/         # Imágenes generadas por IA
├── models/           # Imágenes de modelos virtuales
└── temp/             # Archivos temporales

rial-images-staging/   # Mismo estructura para staging

Artifact Registry

¿Qué es? Servicio para almacenar y gestionar artefactos de software, incluyendo imágenes Docker.

Uso en Rial AI:

🐳 Docker Images: Almacena las imágenes Docker del backend
🏷️ Versionado: Gestión de versiones de las imágenes
🔒 Seguridad: Escaneo de vulnerabilidades automático
🔄 CI/CD Integration: Integración con GitHub Actions

Arquitectura de Despliegue

Backend (NestJS)

GitHub Actions construye la imagen Docker
Imagen se pushea a Artifact Registry
Cloud Run despliega automáticamente la nueva versión

Frontend (Next.js)

GitHub Actions ejecuta el build
Cloud Build construye la aplicación
Cloud Run sirve la aplicación estática

Documentación

Documentación Oficial: cloud.google.com/docs
Cloud Run: Cloud Run Documentation
Cloud Storage: Cloud Storage Documentation

🔄 CI/CD: GitHub Actions

¿Qué es CI/CD?

CI/CD significa Continuous Integration (Integración Continua) y Continuous Deployment (Despliegue Continuo). Es una práctica de desarrollo que permite integrar cambios de código frecuentemente y desplegarlos automáticamente.

¿Por qué es importante?

🐛 Detección Temprana de Errores: Los problemas se detectan rápidamente
🚀 Despliegues Rápidos: Automatización del proceso de deploy
🔒 Consistencia: Mismo proceso en todos los ambientes
👥 Colaboración: Facilita el trabajo en equipo
📊 Feedback Rápido: Los desarrolladores reciben feedback inmediato

Pipeline del Backend

Workflow de GitHub Actions


name: Backend CI/CD
 
on:
  push:
    branches: [develop, production]
  pull_request:
    branches: [develop]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      # Linting
      - name: Run ESLint
        run: yarn lint
      
      # Type checking
      - name: TypeScript Check
        run: yarn type-check
      
      # Tests
      - name: Run Tests
        run: yarn test
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/production'
    steps:
      # Build Docker image
      - name: Build Docker Image
        run: docker build -t rial-backend .
      
      # Push to Artifact Registry
      - name: Push to Registry
        run: docker push gcr.io/rial-ai/backend:latest
      
      # Deploy to Cloud Run
      - name: Deploy to Cloud Run
        run: gcloud run deploy rial-backend --image gcr.io/rial-ai/backend:latest

Pasos del Pipeline

🔍 Linting: ESLint revisa el código
📝 TypeScript: Verificación de tipos
🧪 Testing: Ejecución de tests unitarios
🐳 Docker Build: Construcción de la imagen
📦 Push: Subida a Artifact Registry
🚀 Deploy: Despliegue automático en Cloud Run

Pipeline del Frontend

Características

🔍 Linting: ESLint para calidad de código
📝 TypeScript: Verificación de tipos
🏗️ Build: Construcción de la aplicación
🚀 Deploy: Despliegue directo a Cloud Run

Integración con Cloud Build

El frontend está conectado directamente a Cloud Run mediante Cloud Build, que:

Detecta cambios en las ramas develop y production
Ejecuta el build automáticamente
Despliega la nueva versión

Documentación

GitHub Actions: docs.github.com/actions
Cloud Build: cloud.google.com/build/docs

📚 Documentación de APIs

Swagger/OpenAPI

Utilizamos SwaggerModule y RedocModule en NestJS para generar documentación automática de nuestras APIs.

¿Qué es Swagger?

Swagger (ahora OpenAPI) es una especificación para describir APIs REST. Permite:

📖 Documentación Automática: Genera docs desde el código
🧪 Testing Interactivo: Prueba endpoints directamente
📋 Especificación Estándar: Formato reconocido mundialmente
🔄 Sincronización: Docs siempre actualizadas con el código

Configuración en NestJS


// main.ts
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 
const config = new DocumentBuilder()
  .setTitle('Rial AI API')
  .setDescription('API para la plataforma de generación de imágenes con IA')
  .setVersion('1.0')
  .addBearerAuth()
  .build();
 
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api/docs', app, document);

Decoradores Útiles


@ApiTags('projects')
@ApiOperation({ summary: 'Crear nuevo proyecto' })
@ApiResponse({ status: 201, description: 'Proyecto creado exitosamente' })
@ApiResponse({ status: 400, description: 'Datos inválidos' })
export class ProjectController {
  @Post()
  async create(@Body() createProjectDto: CreateProjectDto) {
    // ...
  }
}

Acceso a la Documentación

Swagger UI: https://api.rial-ai.com/api/docs
ReDoc: https://api.rial-ai.com/api/redoc

Documentación

Swagger: swagger.io
NestJS OpenAPI: docs.nestjs.com/openapi

🧪 Testing

Backend: Jest

Jest es nuestro framework de testing para el backend, proporcionando una solución completa para testing unitario e integración.

¿Qué es Jest?

Jest es un framework de testing de JavaScript que se enfoca en la simplicidad. Funciona con la mayoría de proyectos de JavaScript.

Características Principales

📸 Snapshot Testing: Captura y compara salidas
🔍 Mocking: Sistema de mocks integrado
📊 Coverage: Reportes de cobertura automáticos
⚡ Parallel Testing: Ejecución paralela de tests
🎯 Watch Mode: Re-ejecución automática al cambiar código

Tipos de Tests


// Test Unitario
describe('UserService', () => {
  it('should create a user', async () => {
    const userData = { email: 'test@example.com', role: 'BRAND_ADMIN' };
    const result = await userService.create(userData);
    expect(result).toHaveProperty('id');
  });
});
 
// Test de Integración
describe('ProjectController (e2e)', () => {
  it('/projects (POST)', () => {
    return request(app.getHttpServer())
      .post('/projects')
      .send(createProjectDto)
      .expect(201);
  });
});

Frontend: Playwright

Playwright es nuestra herramienta para testing end-to-end del frontend.

¿Qué es Playwright?

Playwright es un framework para testing de aplicaciones web que permite automatizar navegadores (Chromium, Firefox, Safari).

Características Principales

🌐 Multi-browser: Soporte para múltiples navegadores
📱 Mobile Testing: Testing en dispositivos móviles
📸 Screenshots: Capturas automáticas en fallos
🎥 Video Recording: Grabación de sesiones de test
⚡ Fast & Reliable: Tests rápidos y confiables

Ejemplo de Test


// tests/project-creation.spec.ts
import { test, expect } from '@playwright/test';
 
test('should create a new project', async ({ page }) => {
  await page.goto('/dashboard');
  await page.click('[data-testid="create-project-btn"]');
  await page.fill('[data-testid="project-name"]', 'Test Project');
  await page.selectOption('[data-testid="project-type"]', 'LIFESTYLE');
  await page.click('[data-testid="submit-btn"]');
  
  await expect(page.locator('[data-testid="success-message"]')).toBeVisible();
});

Documentación

Jest: jestjs.io
Playwright: playwright.dev

🌐 Dominios y DNS

Gestión de Dominios

Registrar: Squarespace - Donde está registrado el dominio rial-ai.com
DNS: Google Cloud DNS - Gestión de registros DNS
SSL: Automático mediante Cloud Run

Configuración de Ambientes

Producción: rial-ai.com
Staging: staging.rial-ai.com

🔧 Variables de Entorno

¿Qué son las Variables de Entorno?

Las variables de entorno son valores dinámicos que afectan el comportamiento de los procesos en un sistema operativo. En desarrollo web, se usan para configurar aplicaciones sin hardcodear valores sensibles.

¿Por qué son importantes?

🔒 Seguridad: API keys y secretos no están en el código
🌍 Configuración por Ambiente: Diferentes valores para dev/staging/prod
👥 Colaboración: Cada desarrollador puede tener su configuración
🔄 Flexibilidad: Cambios sin redeployar código

Gestión con Doppler

Utilizamos Doppler para gestionar nuestras variables de entorno de forma segura.

Ventajas de Doppler

🔐 Encriptación: Variables encriptadas en tránsito y reposo
👥 Control de Acceso: Permisos granulares por equipo
📊 Auditoría: Log de todos los cambios
🔄 Sincronización: Sync automático con servicios cloud
🌍 Multi-ambiente: Gestión fácil de múltiples ambientes

📦 Librerías y Dependencias

¿Qué son las Librerías/Dependencias?

Las librerías (o dependencias) son paquetes de código reutilizable que proporcionan funcionalidades específicas a nuestras aplicaciones.

Gestión de Dependencias

Package Manager: Yarn (más rápido y confiable que npm)
Lock Files: yarn.lock asegura versiones consistentes
Versionado: Seguimos Semantic Versioning (SemVer)

Dependencias Principales del Backend


{
  "@nestjs/core": "^10.0.0",
  "@nestjs/common": "^10.0.0",
  "@prisma/client": "^5.0.0",
  "prisma": "^5.0.0",
  "class-validator": "^0.14.0",
  "class-transformer": "^0.5.1"
}

Dependencias Principales del Frontend


{
  "next": "^14.0.0",
  "react": "^18.0.0",
  "tailwindcss": "^3.0.0",
  "@radix-ui/react-dialog": "^1.0.0",
  "phosphor-react": "^1.4.0"
}

🚀 Próximos Pasos

¿Quieres profundizar en alguna tecnología específica?

Configuración del Entorno - Aprende a configurar todo el stack
Base de Datos - Explora el esquema completo
Flujo de Trabajo - Entiende nuestro proceso de desarrollo
Testing - Guías detalladas de testing

¿Tienes preguntas sobre alguna tecnología? ¡Consulta nuestro diccionario técnico o contacta al equipo de desarrollo!