supabase-postgres-best-practices

Filosofía: "Guided Setup"

• Proyecto: Configuración global del cliente (prompts, documentos)
• Campaña: Ejecución específica por nicho (país, industria, ECP)
• Control granular: El usuario selecciona qué documentos usar en cada paso

Stack Tecnológico

• Frontend: Next.js 14 (App Router), React, TailwindCSS
• Backend: Supabase Cloud (Postgres + Row Level Security)
• IA: Gemini 2.0 Flash (análisis) y Pro (outputs finales)
• Edge Functions: Deno runtime en Supabase Cloud
• Deployment: Vercel (frontend) + Supabase Cloud (backend)

`projects`

Configuración del proceso para un cliente

• Prompts maestros editables (5 pasos)
• Guías paso a paso para el usuario
• context_config: JSONB que mapea step_X → [doc_ids]

`knowledge_base_docs`

Documentos subidos con contenido extraído

• Categorías: product, competitor, research, output
• Extracción automática: PDF (pdf-parse), DOCX (mammoth), TXT
• Token count automático (trigger SQL)

`ecp_campaigns`

Sesiones de análisis por nicho

• Inputs: ECP name, problem core, country, industry
• Outputs: research + 4 pasos de análisis
• Status tracking completo

`execution_logs`

Auditoría detallada de cada llamada a IA

> 📖 Guía Completa de Deployment: Lee [cloud-deployment.md](./docs/deployment/cloud-deployment.md) para instrucciones paso a paso.

Resumen Rápido

1. Crear proyecto en Supabase Cloud (gratis)

- Ir a [app.supabase.com](https://app.supabase.com)

- Crear nuevo proyecto: ecp-generator

1. Aplicar migraciones (crear tablas)

- Copiar SQL de supabase/migrations/20250101000000_initial_schema.sql

- Pegar en SQL Editor de Supabase → Run

1. Obtener credenciales

- Supabase: Settings → API (URL + anon key + service role key)

- Gemini: [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)

1. Configurar variables de entorno

```bash

cp .env.example .env

# Editar .env con tus credenciales

```

1. Deploy Edge Function

```bash

supabase login

supabase link --project-ref TU_PROJECT_REF

supabase functions deploy generate-ecp-step

supabase secrets set GEMINI_API_KEY=tu-api-key

```

1. Correr el proyecto

```bash

npm install

npm run dev

```

🎉 Abre http://localhost:3000

Si prefieres trabajar con Supabase localmente usando Docker en lugar de la nube:

Prerrequisitos

• Docker Desktop instalado y ejecutándose ([docker.com](https://www.docker.com/products/docker-desktop))
• Node.js 18+ y npm

Pasos para Desarrollo Local

#### 1. Iniciar Supabase Local

```bash

npm run supabase:start

```

Esto iniciará todos los servicios de Supabase en contenedores Docker:

• PostgreSQL en puerto 54322
• API REST en puerto 54321
• Studio (UI web) en puerto 54323
• Inbucket (emails) en puerto 54324

Importante: La primera vez descargará las imágenes Docker (~2-3 GB).

#### 2. Obtener Credenciales Locales

El comando anterior mostrará en la terminal:

```

API URL: http://localhost:54321

anon key: eyJhbGc...

service_role key: eyJhbGc...

```

#### 3. Configurar Variables de Entorno Locales

Actualiza tu archivo .env:

```env

# Supabase Local

NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321

NEXT_PUBLIC_SUPABASE_ANON_KEY=

SUPABASE_SERVICE_ROLE_KEY=

# API Keys (mismas que producción)

GEMINI_API_KEY=tu-gemini-api-key

OPENAI_API_KEY=tu-openai-api-key

```

#### 4. Acceder a Supabase Studio

Abre [http://localhost:54323](http://localhost:54323) para:

• Ver tablas y datos
• Ejecutar queries SQL
• Monitorear logs
• Gestionar autenticación

#### 5. Aplicar Migraciones (Automático)

Las migraciones en supabase/migrations/ se aplican automáticamente al iniciar.

Para reaplicar desde cero:

```bash

npm run supabase:reset

```

#### 6. Iniciar la Aplicación

```bash

npm install

npm run dev

```

Abre [http://localhost:3000](http://localhost:3000)

Comandos Útiles

```bash

# Ver estado y credenciales

npm run supabase:status

# Detener Supabase

npm run supabase:stop

# Reiniciar base de datos (borra todos los datos)

npm run supabase:reset

# Crear nueva migración

npm run supabase:migration:new nombre_migracion

# Ver logs de Edge Functions

npm run supabase:logs

npm run supabase:logs:execute

```

Desarrollo Local vs Cloud

| Aspecto | Local (Docker) | Cloud (Supabase) |

|---------|---------------|------------------|

| Setup | Requiere Docker Desktop | Solo credenciales |

| Latencia | ~0ms (localhost) | ~50-200ms |

| Datos | Volátiles (puedes resetear) | Persistentes |

| Colaboración | Solo tu máquina | Compartido con equipo |

| Edge Functions | Emuladas localmente | Deno runtime en producción |

| Ports | 54321-54326 | HTTPS estándar |

Recomendación: Usa local para desarrollo rápido e iteración. Usa cloud para testing final y producción.

Troubleshooting Local

Error: Cannot connect to Docker daemon

• Solución: Inicia Docker Desktop y espera a que esté completamente cargado

Error: port 54321 already allocated

• Solución: npm run supabase:stop o cambiar puertos en supabase/config.toml

Las migraciones no se aplican

• Solución: npm run supabase:reset para reaplicar todas

Edge Function no responde

• Verifica que el servicio esté corriendo: npm run supabase:status
• Revisa logs: npm run supabase:logs

1️⃣ Crear Proyecto

• Define nombre y descripción
• El sistema crea prompts por defecto (editables)

2️⃣ Subir Documentos

• Producto: Features, beneficios, pricing
• Competidor: Análisis de mercado
• Research: Estudios de audiencia
• Output: Resultados de pasos previos

3️⃣ Configurar Contexto

Por cada paso, selecciona documentos:

• Step 1 (Find Place): Docs de competidores + research
• Step 2 (Select Assets): Docs de producto
• Step 3 (Proof Points): Case studies + validación
• Step 4 (Final Output): Outputs de pasos 1-3

4️⃣ Crear Campaña

• Define: ECP name, problema, país, industria
• El sistema guía paso a paso

5️⃣ Ejecutar Análisis

• Deep Research (automático)
• Step 1 → Guardar output como doc
• Step 2 → Seleccionar output de Step 1 + docs producto
• Step 3 → Usar outputs anteriores
• Step 4 → Generar mensajes finales

Row Level Security (RLS)

Todas las tablas tienen RLS habilitado:

• Los usuarios solo ven sus propios proyectos
• Los documentos están protegidos por ownership del proyecto
• Las campañas heredan permisos del proyecto padre

Validación de Tokens

• Warning: > 1.5M tokens (75%)
• Error: > 2M tokens (100%)
• Monitoreo visual en tiempo real

Gemini 2.0 Flash

• Usado para: Deep Research, Steps 1-3
• ~$0.075 por 1M tokens input
• Rápido y económico para análisis

Gemini 2.0 Pro (opcional)

• Usado para: Step 4 (output final)
• Mayor calidad en generación de copy
• ~$3.50 por 1M tokens input

Grounding Estricto

```typescript

const SYSTEM_INSTRUCTION = `

Your knowledge base is STRICTLY LIMITED to the context provided.

Do NOT use your internal training data.

If info is not in documents, state: "Information not found."

`

```

```

/

├── src/

│ ├── app/

│ │ ├── page.tsx # Lista de proyectos

│ │ ├── projects/

│ │ │ ├── new/page.tsx # Crear proyecto

│ │ │ └── [projectId]/page.tsx # Dashboard del proyecto

│ │ └── api/

│ │ └── documents/

│ │ └── upload/route.ts # API de upload + extracción

│ ├── components/

│ │