Repositorio privado del ecommerce de Black Pulse — café de especialidad de origen único, tostado de precisión. Envío en España y UE.
Plataforma construida con Next.js 16, React 19 y TypeScript: marketing, tienda, cuenta de cliente, panel admin, pagos Stripe y sincronización con Supabase / Clerk / Pinecone / Resend / PostHog.
🔒 Privado. Este repo contiene la lógica completa del negocio. No publicar capturas, fragmentos de código ni claves.
- Estado del proyecto
- Stack
- Setup local
- Variables de entorno
- Scripts
- Estructura
- Diseño y motion
- Seguridad
- Despliegue en Vercel
- Servicios externos
- Operación día a día
Última auditoría: mayo 2026 — auditoría de seguridad completa + eliminación de valores hardcoded.
| Área | Estado |
|---|---|
| Marketing | Hero coreografiado (split-text + magnetic CTA), brand story, reviews carousel (Embla), 3D-tilt collections, newsletter, exit-intent. |
| Tienda | Listado, PDP, carrito, sticky ATC, búsqueda híbrida (FTS + Pinecone integrated inference), Roast Bloom hover en cards, view-transition-name listo. |
| Checkout | Stripe hosted, precios solo desde servidor, validación Zod, idempotencia por stripe_session_id. |
| Cuenta | Pedidos, preferencias, suscripciones. |
| Admin | Dashboard, productos (con DeleteProductButton cliente), pedidos, usuarios, configuración con audit log, jobs (Pinecone sync + Low Stock Notifier), security overview. |
| Auth | Clerk con webhooks (svix), rol admin en metadata pública. |
| APIs | REST en src/app/api/* con rate limiting Upstash, validación Zod, errores genéricos en producción. |
| SEO | Sitemap dinámico, robots, OG image dinámica (opengraph-image.tsx), hreflang es/en, JSON-LD Organization + WebSite. |
| Motion | motion (framer-motion v12), lenis smooth scroll, embla-carousel-react. Primitives en src/components/motion/. |
- Comprar
blackpulse.coffee(disponible $23.99/año) y apuntar DNS a Vercel. - Verificar dominio en Resend para que los emails transaccionales no caigan en spam.
- Cambiar Stripe a
pk_live_/sk_live_y configurar webhook endpoint en producción. - Configurar webhooks de Clerk en el dashboard de production (
user.created/updated/deleted). - (Opcional) Instalar
@sentry/nextjspara error monitoring — variables comentadas en el archivo de ejemplo de entorno. NEXT_PUBLIC_GOOGLE_SITE_VERIFICATIONpara Search Console.- Reemplazar favicon (
src/app/favicon.icoes el de Next.js por defecto). - Crear cupón
BP10en Stripe (o cambiarEXIT_PROMO_CODEensrc/config/products.ts) — se muestra en el exit-intent modal al suscribirse a la newsletter. - Configurar variables de entorno nuevas (
CONTACT_EMAIL,ADMIN_EMAIL,NEXT_PUBLIC_INSTAGRAM_URL,NEXT_PUBLIC_TWITTER_HANDLE) — ver sección Variables de entorno.
| Categoría | Tecnología | Versión |
|---|---|---|
| Framework | Next.js (App Router, Turbopack en build) | 16.2.x |
| UI | React 19, Tailwind CSS 4 | — |
| Lenguaje | TypeScript | ^5 |
| Componentes | shadcn/ui + Base UI | — |
| Auth | Clerk | ^7 |
| DB + Storage | Supabase (PostgreSQL) | ^2.98 |
| Vector search | Pinecone (integrated inference) | ^7.1 |
| Caché + rate limit | Upstash Redis | — |
| Pagos | Stripe + @stripe/react-stripe-js |
^20 / ^5 |
| Resend | ^6 | |
| Webhooks | Svix | ^1.86 |
| Analytics | PostHog (EU/GDPR) | ^1.359 |
| Forms + validación | React Hook Form + Zod | ^7 / ^4 |
| Estado | Zustand | ^5 |
| i18n | next-intl | ^4.8 |
| Motion | motion (framer-motion v12), lenis, embla-carousel-react |
^12 / ^1 / ^8 |
git clone git@github.com:Davmunrey/BlackPulse.git
cd BlackPulse
npm install
cp .env.example .env.local
# Editar .env.local con las claves
npm run devAbrir http://localhost:3000 (redirige a /es).
Requisitos: Node.js >= 20.9 y < 23 (ver engines en package.json).
Ver .env.example para la lista completa. Las críticas son:
NEXT_PUBLIC_APP_URL=https://blackpulse.coffee # producción
# Supabase, Clerk, Stripe, Resend, Upstash, Pinecone, PostHog…Las variables
NEXT_PUBLIC_*se incluyen en el bundle del cliente. No metas secretos ahí.
Estas variables no están en el archivo de ejemplo original — añadirlas al entorno:
| Variable | Obligatoria | Descripción | Fallback |
|---|---|---|---|
CONTACT_EMAIL |
No | Email de soporte visible en emails transaccionales | hola@blackpulse.coffee |
ADMIN_EMAIL |
No | Email receptor de alertas internas (stock bajo, etc.) | admin@blackpulse.coffee |
NEXT_PUBLIC_INSTAGRAM_URL |
No | URL completa del perfil de Instagram | https://instagram.com/blackpulsecoffee |
NEXT_PUBLIC_TWITTER_HANDLE |
No | Handle de Twitter/X (con @) para metadatos OG |
@blackpulsecoffee |
Todas tienen fallback funcional; sin embargo en producción deben configurarse correctamente para que los emails de soporte y las redes sociales apunten a las cuentas reales.
| Comando | Qué hace |
|---|---|
npm run dev |
Dev server (Webpack). |
npm run dev:turbo |
Dev server (Turbopack — más rápido). |
npm run build |
Build de producción. |
npm run start |
Servir el build. |
npm run lint |
ESLint. |
npm run typecheck |
tsc --noEmit. |
npm run validate |
lint + typecheck (recomendado pre-merge). |
npm run clean |
Borrar .next. |
npm run sync-prices |
Sync de precios Stripe → Supabase (script en scripts/). |
BlackPulse/
├── public/
│ └── .well-known/security.txt # security@blackpulse.coffee
├── docs/
│ ├── SECURITY.md
│ └── store-remodel-plan.md
├── supabase/ # SQL — ver supabase/README.md
├── scripts/ # sync-catalog-prices.{mjs,sh}
├── src/
│ ├── app/
│ │ ├── [locale]/
│ │ │ ├── (auth)/ # sign-in, sign-up
│ │ │ ├── (marketing)/ # home, about, blog, legal, suscripcion
│ │ │ ├── (shop)/ # shop, [slug], checkout, success
│ │ │ ├── account/ # cuenta del usuario
│ │ │ ├── admin/ # panel
│ │ │ └── opengraph-image.tsx # OG dinámica (edge runtime)
│ │ ├── api/ # REST: products, checkout, webhooks, admin/*
│ │ ├── robots.ts
│ │ ├── sitemap.ts
│ │ └── layout.tsx
│ ├── components/
│ │ ├── motion/ # SmoothScrollProvider, MagneticButton,
│ │ │ # SplitText, ScrollReveal, AmbientBackdrop…
│ │ ├── marketing/ # Hero, BrandStory, ReviewsCarousel, …
│ │ ├── shop/ # ProductCard (Roast Bloom), Cart, Filters…
│ │ ├── admin/ # Sidebar, charts
│ │ ├── layout/ # Header, Footer, AnnouncementBar
│ │ └── ui/ # shadcn primitives
│ ├── config/ # site (brand, URLs, emails), products (upsells, promo codes), pricing, credibility
│ ├── i18n/ # routing, request, navigation
│ ├── lib/
│ │ ├── security/ # apiResponse, clientIp, limits
│ │ ├── seo/ # metadata-helpers, paths
│ │ ├── admin/ # requireAdmin, auditLog
│ │ ├── pinecone/, stripe/, supabase/, upstash/, resend/, posthog/
│ │ └── i18n/ # localize-product, flavor-notes
│ ├── messages/ # es.json, en.json
│ ├── store/ # cartStore (Zustand)
│ ├── types/
│ └── proxy.ts # Clerk + next-intl + admin guard
├── next.config.ts
├── package.json
└── README.md
ADN visual: Bauhaus contemporáneo × minimalismo japonés. Paleta marrón profundo (#4A1E00) + crema cálida (#FBE6C5) + negro warm (#0A0806). Tipografía Playfair Display (display) + Geist Sans (body) + Geist Mono (data). Geometría afilada (radius 2px), tokens fluidos OKLCH.
| Componente | Para qué |
|---|---|
SmoothScrollProvider |
Lenis global, respeta prefers-reduced-motion. |
MagneticButton |
CTA magnético (cursor follow + spring) con click ripple. |
SplitText |
Reveal letra/palabra con blur + y-offset. |
ScrollReveal |
Entrada whileInView con stagger y variant blur. |
AmbientBackdrop |
Orbs flotantes (decoración pasiva). |
HeroScrollLayer |
Parallax suave con factor configurable. |
AnimatedTastingMeter |
Meter animado para PDP. |
| Clase | Efecto |
|---|---|
.tabular-nums |
Dígitos no saltan en precios/contadores. |
.bp-grain |
Overlay de ruido SVG (textura de film, opacity 4.5%). |
.bp-bloom-clip |
Reveal radial desde centro (Roast Bloom). |
.bp-sweep |
Underline que se dibuja izq→der en group:hover. |
.bp-link-grow |
Underline que crece desde 0 → 100%. |
.animate-heartbeat |
Pulso sutil 1.6s para badges. |
.animate-halo |
Anillo rotante lento (60s). |
.bp-divider / .bp-divider-sm |
Líneas Bauhaus 1.5px / 1px. |
Las cards de productos exponen view-transition-name: product-{slug} cuando son priority. Cuando se navegue al PDP con la API de View Transitions, la imagen vuela a su posición destino (shared element transition). Los CSS hooks están en globals.css.
Resumen — detalle completo en docs/SECURITY.md.
| Tema | Implementación |
|---|---|
| CSP / HSTS / Permissions-Policy | next.config.ts, solo en producción (en dev se desactiva CSP para no bloquear scripts). |
| CSP allowlist | Clerk, Stripe (js.stripe.com, hooks.stripe.com), PostHog (eu), Supabase, Cloudflare Turnstile. |
| Admin guard | requireAdmin() en handlers admin; proxy.ts devuelve 403 JSON para /api/admin/*. |
| Rate limit | Upstash: products, search, newsletter, checkout. Stub silencioso si Redis no está configurado. |
| Errores API | 500 genérico en producción (internalServerError en lib/security/apiResponse.ts). |
| Webhooks | Stripe + Clerk con verificación de firma, secret check, body size limit. |
| Idempotencia | Stripe checkout.session.completed por stripe_session_id. Clerk user.created por upsert. |
| Validación | Zod en todos los POST/PATCH; roast_level/origin_country validados contra enum canónico (config/products.ts). |
| GDPR | Soft-delete (anonimización) en user.deleted. Newsletter opt-in con email confirm. |
security.txt |
mailto:security@blackpulse.coffee. |
No usar ADMIN_DEV_BYPASS=true en producción. El proxy lo guarda detrás de NODE_ENV === "development" pero igual: nunca lo configures en Vercel.
- Importar repo en vercel.com/new (cuenta privada del proyecto).
- Framework: Next.js (auto-detectado).
- Build command:
npm run build(default). - Output:
.next(default). - Node version: 20.x (ver
enginesenpackage.json). - Variables de entorno: copiar todas las de
.env.examplecon valores de producción:NEXT_PUBLIC_APP_URL=https://blackpulse.coffee- Stripe live keys (
pk_live_,sk_live_,STRIPE_WEBHOOK_SECRETdel endpoint de producción) - Clerk production instance keys (
pk_live_,sk_live_) - Supabase production project
- Upstash Redis production
- Resend, Pinecone, PostHog
- Deploy.
- Comprar
blackpulse.coffee(Vercel Domains o registrador externo). - En Vercel → Project → Settings → Domains →
Add→blackpulse.coffeeywww.blackpulse.coffee. - Apuntar DNS según las instrucciones (CNAME
cname.vercel-dns.como A76.76.21.21). - Forzar HTTPS (Vercel lo hace por defecto).
| Servicio | Endpoint | Variable a sincronizar |
|---|---|---|
| Stripe | https://blackpulse.coffee/api/webhooks/stripe |
STRIPE_WEBHOOK_SECRET |
| Clerk | https://blackpulse.coffee/api/webhooks/clerk |
CLERK_WEBHOOK_SECRET |
Eventos mínimos a suscribir:
- Stripe:
checkout.session.completed,customer.subscription.*,invoice.payment_succeeded,charge.refunded. - Clerk:
user.created,user.updated,user.deleted.
src/app/[locale]/opengraph-image.tsx(runtime = "edge") — generación dinámica de la OG image. Vercel la sirve desde edge nodes; cuesta $0 hasta volúmenes altos.
- LCP < 2.5s (hero con
priorityen imagen yfont-display: swap). - CLS < 0.1 (todas las imágenes con
fill+aspect-ratio). - INP < 200ms (motion lazy, Lenis off en reduced-motion).
npm run validate # lint + typecheck
npm run build # producciónSi el build falla por acorn o archivos rotos en node_modules → rm -rf node_modules .next && npm install (incidente conocido en ciertos entornos).
| Servicio | Para qué | Plan recomendado al lanzar |
|---|---|---|
| Vercel | Hosting + edge | Hobby al inicio, Pro cuando supere límites |
| Supabase | DB + Storage (imágenes producto) | Free tier al lanzar |
| Clerk | Auth | Free hasta 10k MAU |
| Stripe | Pagos | Pay as you go |
| Resend | Emails transaccionales | Free 3k/mes; verificar dominio |
| Upstash | Redis (cache + ratelimit) | Free 10k req/día |
| Pinecone | Vector search | Free starter (suficiente al inicio) |
| PostHog | Product analytics | Free 1M eventos/mes (EU region) |
| (Opcional) Sentry | Error monitoring | Free 5k errores/mes |
Admin → /es/admin/products/new → completar campos. Después:
# Sincronizar precios con Stripe
npm run sync-pricesSi tenés Pinecone configurado, ejecutá el job desde admin → /es/admin/jobs → "Pinecone Embeddings Sync".
Admin → /es/admin/logs (requiere haber ejecutado la migración 001_admin_audit_config.sql).
Admin → /es/admin/jobs → "Low Stock Notifier" envía email vía Resend a la dirección configurada cuando hay productos con stock_quantity <= 5.
| Archivo | Propósito |
|---|---|
docs/SECURITY.md |
Hardening, cabeceras, webhooks. |
docs/store-remodel-plan.md |
Plan de UX/diseño de la tienda. |
supabase/README.md |
Orden de migraciones SQL. |
CHANGELOG.md |
Historial de cambios. |
Repo privado. © Black Pulse — 2026.