🛒 StackStore - Fullstack E-commerce Engine

Sistema integral de comercio electrónico desarrollado con Next.js 14 y arquitectura de Diseño Atómico.

🛠️ Stack Tecnológico

• Frontend: Next.js 14 (App Router), Tailwind CSS, Zustand
• Backend: Node.js, Express, Prisma ORM
• Database: SQLite con multi-tenancy
• Architecture: Atomic Design Pattern

🏗️ Arquitectura Atomic Design

src/
├── app/                    # Pages (solo llaman templates, máx 10 líneas)
│   ├── page.tsx           # Solo: <Template data={data} />
│   ├── admin/page.tsx     # Solo: <AdminTemplate data={adminData} />
│   └── product/[id]/page.tsx # Solo: <ProductTemplate data={productData} />
├── components/
│   ├── templates/          # Templates (solo estructura UI)
│   │   ├── MainLayout.tsx    # Layout principal
│   │   ├── AdminTemplate.tsx # Template admin
│   │   └── ProductTemplate.tsx # Template producto
│   ├── organisms/          # Componentes complejos
│   │   ├── Navbar.tsx         # Navbar con navegación
│   │   ├── ProductGrid.tsx    # Grid de productos
│   │   └── CheckoutForm.tsx   # Formulario checkout
│   ├── molecules/         # Componentes medios
│   │   ├── ProductCard.tsx    # Card de producto
│   │   ├── CartItem.tsx       # Item del carrito
│   │   └── UserMenu.tsx       # Menú usuario
│   └── atoms/               # Componentes simples
│       ├── Button.tsx          # Botón
│       ├── Input.tsx           # Input
│       └── Typography.tsx      # Textos
├── hooks/                  # Data y lógica
│   ├── useAuth.ts           # Lógica autenticación
│   ├── useProducts.ts       # Data productos
│   ├── useOrders.ts         # Data pedidos
│   └── useCart.ts           # Data carrito
└── store/                  # Estado global
    ├── authStore.ts         # Store Zustand auth
    ├── productsStore.ts     # Store Zustand productos
    └── cartStore.ts         # Store Zustand carrito

📋 Principios del Proyecto

🎯 Pages (Máx 10 líneas)

// app/page.tsx
export default function HomePage() {
  const data = useHomePageData();
  return <HomeTemplate data={data} />;
}

🏗️ Templates (Solo estructura UI)

// templates/HomeTemplate.tsx
export default function HomeTemplate({ data }) {
  return (
    <MainLayout>
      <Hero data={data.hero} />
      <ProductGrid products={data.products} />
      <Features data={data.features} />
    </MainLayout>
  );
}

🪝 Hooks (Toda la lógica y datos)

// hooks/useHomePageData.ts
export function useHomePageData() {
  const { products, loading } = useProducts();
  const { user } = useAuth();
  
  return {
    hero: { title: "StackStore", subtitle: "Tu tienda online" },
    products,
    features: [],
    loading
  };
}

🚀 Instalación

Backend

cd backend
npm install
npx prisma migrate dev
npx prisma generate
npm run dev

Frontend

cd frontend
npm install
npm run dev

🎯 Características Principales

🛍️ E-commerce Completo

• ✅ Catálogo de productos con multi-tenancy
• ✅ Carrito persistente por usuario
• ✅ Checkout completo con pagos
• ✅ Gestión de inventario
• ✅ Sistema de reviews y ratings
• ✅ Búsqueda avanzada de productos
• ✅ Lista de favoritos (wishlist)
• ✅ Sistema de categorías con filtros

👥 Gestión de Usuarios

• ✅ Autenticación JWT con modo desarrollo
• ✅ Roles y permisos (admin, customer)
• ✅ Perfiles de usuario
• ✅ Historial de pedidos
• ✅ Registro y login de usuarios

📊 Panel Administrativo

• ✅ Dashboard con estadísticas reales
• ✅ Gestión de productos (CRUD)
• ✅ Gestión de usuarios y pedidos
• ✅ Análisis de ventas
• ✅ Sistema de tabs organizado
• ✅ Modo desarrollo con datos locales

🎨 Atomic Design

• ✅ Componentes reutilizables
• ✅ Escalabilidad 100%
• ✅ Mantenimiento simplificado
• ✅ Consistencia visual
• ✅ Navbar consistente en todas las páginas

� Modo Desarrollo

• ✅ Datos locales sin necesidad de backend
• ✅ Autenticación de desarrollo
• ✅ Productos de ejemplo pre-cargados
• ✅ Switch automático desarrollo/producción

�🔄 Flujo de Datos

1. Page → Hook (data) → Template (UI)
2. Template → Organisms → Molecules → Atoms
3. Store → Hook → Component → UI

📱 Estructura de Datos

Productos

interface Product {
  id: string;
  title: string;
  slug: string;
  price: number;
  categoryName: string;
  images: string[];
  isActive: boolean;
  isNew: boolean;
  isFeatured: boolean;
  stock: number;
  createdAt: string;
}

Usuarios

interface User {
  id: string;
  name: string;
  email: string;
  globalRole: 'superadmin' | 'admin' | 'customer';
  tenantRole: string;
  phone?: string;
  address?: string;
  createdAt: string;
}

Pedidos

interface Order {
  id: string;
  orderNumber: string;
  status: 'pending' | 'processing' | 'shipped' | 'delivered';
  total: number;
  items: OrderItem[];
  customerName: string;
  customerEmail: string;
  createdAt: string;
}

🚀 Despliegue

Desarrollo

• Frontend: http://localhost:3000
• Backend: http://localhost:4000

Producción

# Build frontend
cd frontend && npm run build

# Start backend
cd backend && npm start

🔐 Credenciales de Acceso

Administrador (Modo Desarrollo)

• Email: admin@stackstore.com
• Password: admin123
• Acceso: Panel administrativo completo

Usuario de Ejemplo

• Email: test@stackstore.com
• Password: user123
• Acceso: Tienda y perfil de usuario

📁 Estructura del Proyecto

ecommerce-pro-stack/
├── frontend/                 # Aplicación Next.js
│   ├── src/
│   │   ├── app/             # Páginas y rutas
│   │   ├── components/      # Componentes Atomic Design
│   │   ├── hooks/           # Lógica y datos
│   │   ├── store/           # Estado global Zustand
│   │   └── styles/          # Estilos globales
│   ├── public/              # Assets estáticos
│   └── package.json
├── backend/                 # API Node.js
│   ├── src/
│   │   ├── controllers/     # Controladores API
│   │   ├── prisma/          # Base de datos y migraciones
│   │   └── index.ts         # Servidor Express
│   ├── package.json
│   └── prisma.schema.prisma
└── README.md               # Este archivo

🎨 Características Implementadas

✅ Frontend Completo

• Home: Hero, productos destacados, categorías
• Productos: Grid detallado con filtros y búsqueda
• Carrito: Gestión completa con persistencia
• Checkout: Flujo completo de compra
• Perfil: Información de usuario y pedidos
• Admin: Panel con tabs y estadísticas
• Auth: Login/registro con modo desarrollo

✅ Backend Funcional

• API REST: Endpoints completos para CRUD
• Autenticación: JWT con roles y permisos
• Base de Datos: Prisma con SQLite
• Multi-tenancy: Soporte para múltiples tiendas
• Seed Script: Datos iniciales para desarrollo

✅ Experiencia de Usuario

• Responsive: Mobile-first design
• Navbar: Navegación consistente en todas las páginas
• Loading States: Skeletons y estados de carga
• Error Handling: Manejo elegante de errores
• SEO Friendly: Meta tags y estructura semántica

🛠️ Comandos Útiles

Desarrollo

# Iniciar frontend
npm run dev

# Iniciar backend
cd backend && npm run dev

# Generar Prisma client
cd backend && npx prisma generate

# Correr seed script
cd backend && npm run seed

Producción

# Build frontend
npm run build

# Start production
npm start

📄 Licencia

MIT License - Libre para uso comercial y personal

---

👥 Autores

Jesus Melville - GitHub Marlon Levano - GitHub

📞 Contacto Para soporte o preguntas, contacta a [jesusmelvillemm@gmail.com]

---

🎯 StackStore: Ecommerce Fullstack con Atomic Design - Listo para Producción!