🛠️ 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


├── Dockerfile                 # Imagen Docker para despliegue (producción)
├── package.json               # Dependencias y scripts de Node
├── yarn.lock                  # Versionado exacto de dependencias
├── nest-cli.json              # Configuración del CLI de NestJS
├── prisma/                    # Capa de acceso a datos (Prisma ORM)
│   ├── prisma.module.ts
│   ├── prisma.service.ts
│   └── schema/                # Esquema de base de datos y migraciones
│       ├── schema.prisma
│       ├── brand.prisma
│       ├── project.prisma
│       ├── user.prisma
│       └── migrations/
│           ├── 2025.../       # Migraciones versionadas
│           └── ...
├── src/                       # Código fuente del backend (NestJS)
│   ├── main.ts                # Punto de entrada de la aplicación
│   ├── app.module.ts          # Módulo raíz
│   ├── app.controller.ts
│   ├── app.service.ts
│   ├── auth/                  # Autenticación (JWT, API keys, Supabase)
│   ├── config/                # Configuración (CORS, Swagger, Twilio, email)
│   ├── data/                  # Endpoints de métricas, stats, descargas
│   ├── db/                    # Módulos de dominio sobre la base de datos
│   ├── lib/                   # Librería compartida y utilidades
│   │   ├── constants/         # Constantes y mapeos de estados/tipos
│   │   ├── decorators/        # Decoradores personalizados (roles, permisos)
│   │   ├── guards/            # Guards de autorización y autenticación
│   │   ├── policies/          # Políticas de acceso por dominio
│   │   ├── prisma/            # Helpers de construcción de queries
│   │   ├── utils/             # Utilidades genéricas (fechas, strings, ficheros)
│   │   ├── ...                # Otros archivos / carpetas de funciones/helpers
│   ├── services/              # Servicios transversales
│   ├── types/                 # Tipos y definiciones globales (DTOs, dominios)
│   └── uploads/               # Gestión de uploads y URLs firmadas
├── supabase/                  # Configuración y assets específicos de Supabase
├── test/                      # Tests

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


├── Dockerfile                 # Imagen Docker para despliegue (producción)
├── next.config.ts             # Configuración de Next.js
├── middleware.ts              # Middleware (auth, redirecciones)
├── package.json
├── yarn.lock
├── components.json            # Configuración de shadcn/ui (librería de componentes)
├── playwright.config.ts       # Configuración de tests
├── public/                    # Assets estáticos servidos en raíz
├── src/
│   ├── app/                   # App Router (Url se construyen dinámicamente según estructura de carpetas)
│   │   ├── layout.tsx         # Layout raíz
│   │   ├── page.tsx           # Página de inicio
│   │   ├── globals.css
│   │   ├── providers.tsx
│   │   ├── not-found.tsx
│   │   ├── (auth)/            # Rutas de autenticación (login, etc.)
│   │   ├── (private)/         # Área privada (páginas de los clientes, requiere sesión)
│   │   ├── (public)/          # Páginas públicas
│   │   └── admin/             # Panel de administración
│   ├── assets/                # Imágenes y recursos
│   ├── components/
│   │   ├── ui/                # Componentes básicos/principales/atómicos (button, card, dialog, inputs, etc.)
│   │   ├── layout/            # Componente que format parte de la estructura de la página (header, footer, ..)
│   │   ├── common/            # Componentes utilizados en varias partes del código
│   │   ├── animations/        # Componentes que aplican animaciones
│   │   └── KPI/               # Componentes que muestran data/estadísticas/valores
│   ├── contexts/              # Llamados disponibles para que cualquier componente hijo pueda llamarlo (autentificación, datos compartidos)
│   ├── hooks/                 # Lógica reutilizable con estados, efectos o contextos
│   ├── lib/                   # Utilidades y configuración
│   │   ├── constants/         # Constantes y mapeos de estados/tipos
│   │   ├── validations/
│   │   └── utils
│   ├── services/              # Llamadas al backend
│   │   ├── api.service.ts     # Archivo de convenciones y funciones para llamadas al backend
│   │   ├── db/                # Llamadas a endpoints en función a modelos de la base de datos
│   └── types/                 # Tipos TypeScript
├── stories/                   # Storybook (librería de componentes UI)
├── supabase/                  # Configuración y assets específicos de Supabase
├── tests/                     # Tests E2E con Playwright

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

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 y rial-frontend
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:

Esta se define en el archivo ./src/uploads/urls/uploads-urls.service.ts dentro del repositorio de rial-backend

Existen tres buckets para cada ambiente:

rial_prod: para producción
rial_test: para testeo local
rial_staging: 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

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

Esto ocurre en cada push a la rama production tanto para el backend como para el frontend.

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

Trigger: cuando hay un push a la rama production o develop.

Lógica general del workflow:

Autenticación y configuración con GCP
Build de la imagen Docker
Push de la imagen a Artifact Registry
Deploy a Cloud Run:
- Servicio: rial-backend
- Variables de entorno que se definen en github

Pipeline del Frontend

Trigger: cuando hay un push a la rama production o develop.

Lógica general del workflow:

Autenticación y configuración con GCP
Build de la imagen Docker:
Push de la imagen a Artifact Registry
Deploy a Cloud Run:
- Servicio: rial-frontend
- Variables de entorno que se definen en github

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!