Skip to content

About

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Black Pulse

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.


Índice


Estado del proyecto

Ú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/.

Pendiente antes del lanzamiento

  1. Comprar blackpulse.coffee (disponible $23.99/año) y apuntar DNS a Vercel.
  2. Verificar dominio en Resend para que los emails transaccionales no caigan en spam.
  3. Cambiar Stripe a pk_live_ / sk_live_ y configurar webhook endpoint en producción.
  4. Configurar webhooks de Clerk en el dashboard de production (user.created/updated/deleted).
  5. (Opcional) Instalar @sentry/nextjs para error monitoring — variables comentadas en el archivo de ejemplo de entorno.
  6. NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION para Search Console.
  7. Reemplazar favicon (src/app/favicon.ico es el de Next.js por defecto).
  8. Crear cupón BP10 en Stripe (o cambiar EXIT_PROMO_CODE en src/config/products.ts) — se muestra en el exit-intent modal al suscribirse a la newsletter.
  9. Configurar variables de entorno nuevas (CONTACT_EMAIL, ADMIN_EMAIL, NEXT_PUBLIC_INSTAGRAM_URL, NEXT_PUBLIC_TWITTER_HANDLE) — ver sección Variables de entorno.

Stack

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
Email 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

Setup local

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 dev

Abrir http://localhost:3000 (redirige a /es).

Requisitos: Node.js >= 20.9 y < 23 (ver engines en package.json).


Variables de entorno

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í.

Variables nuevas (mayo 2026)

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.


Scripts

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/).

Estructura

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

Diseño y motion

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.

Primitives de motion (src/components/motion/)

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.

Utilidades CSS clave (src/app/globals.css)

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.

View Transitions

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.


Seguridad

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.


Despliegue en Vercel

Primer deploy

  1. Importar repo en vercel.com/new (cuenta privada del proyecto).
  2. Framework: Next.js (auto-detectado).
  3. Build command: npm run build (default).
  4. Output: .next (default).
  5. Node version: 20.x (ver engines en package.json).
  6. Variables de entorno: copiar todas las de .env.example con valores de producción:
    • NEXT_PUBLIC_APP_URL=https://blackpulse.coffee
    • Stripe live keys (pk_live_, sk_live_, STRIPE_WEBHOOK_SECRET del endpoint de producción)
    • Clerk production instance keys (pk_live_, sk_live_)
    • Supabase production project
    • Upstash Redis production
    • Resend, Pinecone, PostHog
  7. Deploy.

Dominio personalizado

  1. Comprar blackpulse.coffee (Vercel Domains o registrador externo).
  2. En Vercel → Project → Settings → Domains → Add → blackpulse.coffee y www.blackpulse.coffee.
  3. Apuntar DNS según las instrucciones (CNAME cname.vercel-dns.com o A 76.76.21.21).
  4. Forzar HTTPS (Vercel lo hace por defecto).

Webhooks en producción

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.

Cosas que se construyen en edge runtime

  • 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.

Performance objetivo

  • LCP < 2.5s (hero con priority en imagen y font-display: swap).
  • CLS < 0.1 (todas las imágenes con fill + aspect-ratio).
  • INP < 200ms (motion lazy, Lenis off en reduced-motion).

Verificar antes de un deploy

npm run validate  # lint + typecheck
npm run build     # producción

Si el build falla por acorn o archivos rotos en node_modules → rm -rf node_modules .next && npm install (incidente conocido en ciertos entornos).


Servicios externos

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

Operación día a día

Añadir un producto

Admin → /es/admin/products/new → completar campos. Después:

# Sincronizar precios con Stripe
npm run sync-prices

Si tenés Pinecone configurado, ejecutá el job desde admin → /es/admin/jobs → "Pinecone Embeddings Sync".

Ver logs de admin

Admin → /es/admin/logs (requiere haber ejecutado la migración 001_admin_audit_config.sql).

Stock bajo

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.

Documentación adicional

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.

About

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages