Planificación y arquitectura del proyecto e-commerce

¿Por qué es fundamental planificar antes de programar?

Muchos desarrolladores novatos cometen el error de lanzarse directamente al código sin una planificación adecuada. En proyectos e-commerce, esta approach suele resultar en deuda técnica acumulada, dificultades para escalar, y problemas de integración que son extremadamente costosos de resolver posteriormente. Un e-commerce bien planificado puede manejar miles de transacciones simultáneas, mientras que uno mal planificado colapsará con apenas unas decenas de usuarios concurrentes.

La fase de planificación te permite identificar requisitos funcionales críticos como: gestión de inventario en tiempo real, procesamiento de pagos seguros, catálogo de productos con búsqueda avanzada, sistema de recomendaciones personalizado, gestión de usuarios con múltiples roles (admin, vendedor, cliente), carrito de compras persistente, seguimiento de pedidos, y sistema de notificaciones. Cada uno de estos módulos requiere una arquitectura específica que debe comunicarse eficientemente con los demás.

Además, una planificación sólida facilita la colaboración en equipo. Cuando tienes documentación clara de la arquitectura, nuevos desarrolladores pueden incorporarse rápidamente al proyecto, y las pruebas automatizadas pueden diseñarse desde el inicio, garantizando la calidad del código a largo plazo.

Arquitectura general del proyecto e-commerce

Para un e-commerce full stack con Next.js, recomendamos una arquitectura de aplicación web moderna que combine lo mejor del rendering del lado del servidor (SSR) con la interactividad del cliente. La estructura básica que utilizaremos es la siguiente:

• Frontend: Next.js 14+ con App Router, React Server Components, y Tailwind CSS para estilos
• Backend: API Routes de Next.js o un backend separado con Node.js/Express
• Base de datos: PostgreSQL con Prisma ORM para datos relacionales
• Autenticación: NextAuth.js o Clerk para autenticación segura
• Estado global: Zustand o React Context para estado del cliente
• Pagos: Stripe para procesamiento de pagos
• Almacenamiento: AWS S3 o Vercel Blob para imágenes y archivos
• Deployment: Vercel para hosting optimizado de Next.js

Esta combinación proporciona un balance óptimo entre rendimiento, developer experience, y escalabilidad. Los React Server Components permiten reducir el JavaScript enviado al cliente, mejorando significativamente los Core Web Vitals y el SEO de tu e-commerce.

Diseño de la base de datos

El diseño de la base de datos es quizás la decisión más crítica en la arquitectura de tu e-commerce. Una estructura mal diseñada generará consultas inefficientas, datos duplicados, y dificultades para implementar nuevas funcionalidades. Para un e-commerce completo, necesitarás las siguientes entidades principales:

La normalización adecuada es esencial. Por ejemplo, los datos del producto deben estar separados de las imágenes (relación uno a muchos), y las categorías deben soportar jerarquías (categoría padre e hija) para permitir una navegación intuitiva del catálogo.

Estructura del proyecto Next.js

Una estructura de carpetas bien organizada es fundamental para la mantenibilidad del proyecto. Recomendamos la siguiente estructura basada en el App Router de Next.js 14:

my-ecommerce/
├── app/
│   ├── (auth)/              # Rutas de autenticación
│   │   ├── login/
│   │   ├── register/
│   │   └── layout.tsx
│   ├── (shop)/              # Rutas públicas del tienda
│   │   ├── page.tsx         # Página principal
│   │   ├── products/
│   │   │   ├── page.tsx     # Listado de productos
│   │   │   └── [slug]/
│   │   │       └── page.tsx # Detalle de producto
│   │   ├── categories/
│   │   │   └── [slug]/
│   │   │       └── page.tsx
│   │   └── cart/
│   │       └── page.tsx
│   ├── (dashboard)/         # Panel de administración
│   │   ├── admin/
│   │   │   ├── products/
│   │   │   ├── orders/
│   │   │   ├── users/
│   │   │   └── analytics/
│   │   └── layout.tsx
│   ├── api/                 # API Routes
│   │   ├── products/
│   │   ├── orders/
│   │   ├── auth/
│   │   └── webhooks/
│   ├── layout.tsx
│   └── globals.css
├── components/
│   ├── ui/                  # Componentes UI genéricos
│   ├── products/            # Componentes específicos de productos
│   ├── cart/                # Componentes del carrito
│   ├── checkout/            # Componentes del checkout
│   └── layout/              # Header, Footer, Sidebar
├── lib/
│   ├── db.ts                # Cliente de Prisma
│   ├── auth.ts              # Configuración de NextAuth
│   ├── stripe.ts             # Cliente de Stripe
│   └── utils.ts             # Funciones utilitarias
├── prisma/
│   └── schema.prisma        # Schema de la base de datos
└── types/                   # Definiciones de TypeScript

Los Route Groups (carpetas entre paréntesis) permiten organizar rutas lógicamente sin afectar la URL. Esto nos permite tener diferentes layouts para la sección pública, autenticación, y dashboard administrativo.

Flujo de autenticación y autorización

La autenticación en un e-commerce debe manejar múltiples escenarios: registro de nuevos usuarios, login tradicional, login con proveedores sociales (Google, GitHub), recuperación de contraseñas, y verificación de email. Además, necesitas un sistema de roles y permisos para distinguir entre clientes, vendedores, y administradores.

Implementa los siguientes roles:

• Cliente: Puede navegar, agregar al carrito, realizar pedidos, ver su historial, y gestionar sus direcciones.
• Vendedor: Tiene permisos de cliente más la capacidad de gestionar su propio catálogo de productos (si es un marketplace).
• Administrador: Acceso completo al sistema, incluyendo gestión de usuarios, pedidos, productos, categorías, y visualización de analytics.

Gestión del estado del carrito

El carrito de compras es el corazón de cualquier e-commerce. Existen múltiples estrategias para implementarlo, cada una con sus ventajas:

Recomendamos la estrategia híbrida: almacena el carrito en LocalStorage para usuarios anónimos (recuperable si cierran el navegador), y sincroniza con la base de datos cuando el usuario inicia sesión. Esto proporciona la mejor experiencia de usuario posible.

Integración de pagos con Stripe

Stripe es el estándar de la industria para procesamiento de pagos en e-commerce. Su integración con Next.js se realiza principalmente mediante:

1. Stripe Checkout: Redirige al usuario a una página de Stripe para completar el pago. Es la opción más simple y segura, pero ofrece menos personalización.
2. Stripe Elements: Embeds los campos de pago directamente en tu sitio. Requiere más configuración pero proporciona mayor control sobre la UI.
3. Stripe Webhooks: Endpoint que escucha eventos de Stripe (pago exitoso, fallido, reembolsos) para actualizar tu base de datos automáticamente.

// app/api/checkout/route.ts
import Stripe from 'stripe';
import { NextResponse } from 'next/server';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(request: Request) {
  const { items, customerEmail, userId } = await request.json();
  
  const session = await stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: items.map((item: any) => ({
      price_data: {
        currency: 'usd',
        product_data: {
          name: item.name,
          images: [item.image],
        },
        unit_amount: item.price * 100, // Stripe usa centavos
      },
      quantity: item.quantity,
    })),
    mode: 'payment',
    success_url: `${process.env.NEXT_PUBLIC_URL}/order-success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/cart`,
    customer_email: customerEmail,
    metadata: {
      userId: userId,
    },
  });

  return NextResponse.json({ url: session.url });
}

Optimización de rendimiento y SEO

Un e-commerce lento pierde ventas. Los estudios demuestran que cada segundo adicional de carga puede reducir la conversión hasta en un 7%. Para optimizar tu e-commerce Next.js:

• React Server Components: Renderiza componentes en el servidor para reducir el JavaScript enviado al cliente.
• Image Optimization: Usa el componente next/image con lazy loading y formatos modernos (WebP, AVIF).
• Caching estratégico: Implementa caching para páginas de productos y categorías usando generateStaticParams y revalidación.
• Code splitting: Next.js lo hace automáticamente, pero evita importar bibliotecas pesadas innecesariamente.
• Base de datos: Usa cursor-based pagination en lugar de offset para mejor rendimiento en listados grandes.

// Optimización de producto con Server Components
// app/(shop)/products/[slug]/page.tsx
import { db } from '@/lib/db';
import { notFound } from 'next/navigation';
import ProductGallery from '@/components/products/ProductGallery';
import AddToCartButton from '@/components/cart/AddToCartButton';

export async function generateStaticParams() {
  const products = await db.product.findMany({
    select: { slug: true },
  });
  
  return products.map((product) => ({
    slug: product.slug,
  }));
}

export default async function ProductPage({ params }: { params: { slug: string } }) {
  const product = await db.product.findUnique({
    where: { slug: params.slug },
    include: { 
      images: true,
      category: true,
      reviews: { include: { user: true } },
    },
  });

  if (!product) notFound();

  return (
    <div className="grid md:grid-cols-2 gap-8">
      <ProductGallery images={product.images} />
      <div>
        <h1>{product.name}</h1>
        <p>{product.description}</p>
        <AddToCartButton productId={product.id} />
      </div>
    </div>
  );
}

Seguridad del e-commerce

La seguridad es crítica en e-commerce donde se procesan datos financieros y personales sensibles. Implementa estas medidas esenciales:

1. HTTPS obligatorio: Todos los datos deben transmitirse cifrados. Configura HSTS en tu hosting.
2. Validación de inputs: Usa Zod o Yup para validar todos los datos de entrada, tanto del cliente como de APIs.
3. Protección CSRF: Next.js incluye protección CSRF automática en API Routes.
4. Rate limiting: Implementa limitación de requests para prevenir ataques de fuerza bruta.
5. Datos sensibles: Nunca almacenes números de tarjeta. Usa tokens de Stripe.
6. Logs de auditoría: Registra todas las acciones sensibles (cambios de precio, estados de pedido).

# vercel.json
{
  "buildCommand": "prisma generate && next build",
  "installCommand": "npm install && npx prisma generate",
  "framework": "nextjs",
  "regions": ["iad1"],
  "env": {
    "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY": "@stripe_publishable_key"
  }
}