01Premisa

Doc 13 detalla cómo se construye Marketplace SMC a nivel granular: librería específica por capa · cómo conversan entre sí · flujos técnicos detallados · ADRs registradas · cuándo refactorizar.

02Stack completo · librería por librería

2.1 · Runtime + Framework

2.2 · UI + Frontend

2.3 · Backend + Data

2.4 · Integraciones externas

2.5 · DevOps + Observability

03Arquitectura de capas

04Request lifecycle · de browser a DB y vuelta

Browser (founder) hace acción
     ↓
Next.js Middleware (auth · rate limit · idempotency check)
     ↓
Route Handler (/api/X) o Server Action
     ↓
Zod schema validation (input)
     ↓
Business logic layer (services/ folder)
     ↓
Drizzle ORM (type-safe queries · transactions)
     ↓
Supabase Postgres (RLS apply by tenant_id)
     ↓
[opcional] pg_notify si data afecta otros canales
     ↓
[opcional] Side effects (call MeLi · Open Factura · etc)
     ↓
Zod schema validation (output)
     ↓
Response al browser (JSON o RSC stream)
     ↓
Sentry log si error · PostHog event si feature usage
     ↓
mkt_api_logs row append-only para audit

Target end-to-end: API lectura p95 <350ms · mutación p95 <600ms.

05Data flow cross-canal · venta MeLi

1. MeLi POST webhook a /api/webhooks/meli
2. Middleware verifica HMAC SHA-256 firma
3. Middleware verifica idempotency_key contra mkt_idempotency
4. Si new event: INSERT mkt_orders (status='created')
5. Trigger Postgres: UPDATE mkt_inventory.reserved += qty
   (con SELECT FOR UPDATE para evitar concurrency oversell)
6. Trigger Postgres: pg_notify('inventory_changed', product_id)
7. Listener Node.js subscriber recibe notify
8. Listener llama channels-sync API por cada adapter activo:
   · Adapter D2C → actualiza ISR revalidate
   · Adapter MP → actualiza stock en MP API
   · Adapter B2B → invalida cache portal
9. Mientras tanto · evento order.created dispara:
   · Side effect: emit DTE 39 vía Open Factura
   · Side effect: generate label vía Chilexpress
   · Side effect: send email comprador vía Resend
10. Cada side effect → row en mkt_api_logs (audit)
11. Sentry breadcrumbs en cada paso · si error → alerta

06Event-driven architecture

EVENTOS INTERNOS (pg_notify · solo Postgres)
─────────────────────────────────────────────────────
inventory_changed      → channels-sync · ISR revalidate
order_completed        → emit DTE · email comprador
opportunity_detected   → push notification UI
ads_roas_low           → alerta founder (sugerencia pausa)
licitacion_match       → notification Javier
threshold_phase_met    → email cierre fase

EVENTOS EXTERNOS (webhooks inbound · HMAC verificado)
─────────────────────────────────────────────────────
POST /webhooks/meli           → order events MeLi
POST /webhooks/payment        → pasarelas (MP · WebPay)
POST /webhooks/courier        → tracking updates
POST /webhooks/mp             → adjudicación MP
POST /webhooks/supplier/:id   → dropship suppliers

EVENTOS PROGRAMADOS (Vercel Cron)
─────────────────────────────────────────────────────
POST /cron/refresh-meli       6h · refresh OAuth tokens
POST /cron/sync-mp            8am · sync licitaciones diarias
POST /cron/cache-cleanup      7d · eliminar Smart Cache Cold
POST /cron/scoring-daily      6am · Cerebro scoring oportunidades
POST /cron/conciliacion       1ro mes · matching pagos vs DTE
POST /cron/reputation-tracker 1h · refresh materialized view

07Channel Adapter Pattern · interface + 4 impl

Interface

interface ChannelAdapter {
  readonly channelId: 'meli' | 'd2c' | 'mp' | 'b2b';
  readonly displayName: string;

  // Catalog
  publishProduct(product: Product, listing: ChannelListing): Promise<{ externalId: string }>;
  updateProduct(externalId: string, changes: Partial): Promise;
  unpublishProduct(externalId: string): Promise;
  syncStock(externalId: string, qty: number): Promise;

  // Orders
  fetchOrders(since: Date): Promise;
  acceptOrder(externalOrderId: string): Promise;
  shipOrder(externalOrderId: string, tracking: string): Promise;
  cancelOrder(externalOrderId: string, reason: string): Promise;

  // Auth
  refreshAuth(): Promise;
  isAuthValid(): Promise;

  // Health
  ping(): Promise<{ ok: boolean; latency_ms: number }>;
}

4 Implementaciones

Beneficio: agregar canal nuevo = 1 archivo nuevo. NO refactor del resto.

08Supplier Adapter Pattern

interface SupplierAdapter {
  readonly supplierId: string;
  readonly displayName: string;
  readonly authMode: 'api_key' | 'oauth' | 'email_automated' | 'whatsapp_business';

  syncCatalog(): Promise;
  checkStock(sku: string): Promise<{ available: number; updated_at: Date }>;
  createPurchaseOrder(items: OrderItem[], shipTo: Address): Promise<{ poId: string }>;
  cancelPurchaseOrder(poId: string, reason: string): Promise;
  trackShipment(poId: string): Promise<{ status: string; eta: Date; tracking_number?: string }>;
  handleReturn(orderId: string, items: ReturnItem[]): Promise<{ rmaId: string }>;
  ping(): Promise<{ ok: boolean }>;
}

ADR-0003 formaliza este pattern para modo dropshipping Y1.

09Estructura monorepo

marketplace-smc/                       (repo principal · Next.js app)
├── app/
│   ├── (founders)/                   (route group · auth wall)
│   │   ├── dashboard/
│   │   ├── productos/
│   │   ├── ordenes/
│   │   ├── cerebro/
│   │   ├── oportunidades/
│   │   ├── ads/
│   │   ├── mercado-publico/
│   │   ├── b2b/
│   │   └── settings/
│   ├── (public)/                     (route group · sin auth)
│   │   ├── d2c/                      (storefront Y2)
│   │   └── b2b/rfq/                  (portal cliente B2B)
│   └── api/
│       ├── auth/
│       ├── products/
│       ├── orders/
│       ├── channels/{meli|d2c|mp|b2b}/
│       ├── suppliers/
│       ├── ads/
│       ├── cerebro/
│       ├── webhooks/{meli|payment|courier|mp|supplier}/
│       └── cron/
├── lib/
│   ├── db/                           (Drizzle schema + migrations)
│   ├── adapters/
│   │   ├── channels/{meli,d2c,mp,b2b}.ts
│   │   └── suppliers/{xxx}.ts
│   ├── cerebro/                      (scoring · chat SSE · cache)
│   ├── auth/                         (Supabase Auth helpers SSR)
│   ├── validators/                   (Zod schemas)
│   └── utils/
├── packages/
│   ├── ui/                           (@smc/ui · componentes atómicos)
│   ├── shared/                       (@smc/shared · tipos cross-canal)
│   └── prompts/                      (@smc/prompts · versionados IA)
├── supabase/
│   ├── migrations/                   (SQL versionado)
│   └── seed.sql
├── .github/workflows/
│   ├── ci.yml                        (lint + type + test + build + tag)
│   └── e2e.yml                       (Playwright nightly · Y2)
└── public/

10Integración BD · cómo se conecta

Next.js Server Components / Route Handlers
     ↓
import { db } from '@/lib/db'         (singleton client)
     ↓
Drizzle ORM (type-safe queries)
     ↓
postgres.js (driver con connection pooling)
     ↓
Supabase Postgres (RLS enforced)
     ↓
Si tenant_id en JWT no matches → 0 rows (RLS bloquea)

Patrones obligatorios

// ✅ Server-side · createServerClient (RLS aplicada)
import { createServerClient } from '@/lib/supabase/server';

export async function getProducts() {
  const supabase = await createServerClient();
  const { data } = await supabase.from('products').select('*');
  return data;
}

// ❌ NUNCA queries con service_role en código client-side

// ✅ Server Action con Zod validation
'use server';
import { z } from 'zod';
import { createServerClient } from '@/lib/supabase/server';

const schema = z.object({
  sku: z.string().min(3),
  name: z.string().min(1),
  base_price: z.number().int().positive(),
});

export async function createProduct(input: unknown) {
  const parsed = schema.parse(input);
  const supabase = await createServerClient();
  const { data, error } = await supabase.from('products').insert(parsed).select().single();
  if (error) throw new Error(error.message);
  return data;
}

11Orquestación · cuando entra una orden

ORDEN ENTRA → orchestrator decide qué hacer
     ↓
1. Identify channel (meli · mp · d2c · b2b)
2. Call ChannelAdapter[channel].acceptOrder()
3. Postgres transaction:
   · INSERT mkt_orders
   · UPDATE mkt_inventory (reserve)
   · INSERT mkt_order_items
4. If is_dropship product → SupplierAdapter[supplier_id].createPurchaseOrder()
5. Trigger pg_notify('order_completed')
6. Side effect listener:
   · emit DTE
   · generate label (si stock propio)
   · send email comprador
7. PostHog event 'order.completed'
8. Sentry breadcrumb success

12Deploy · ambientes · CI/CD

Ambientes

Pipeline CI · GitHub Actions

name: CI — Marketplace
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    permissions:
      contents: write  # para push tag

    steps:
      - Checkout
      - Setup Node 22
      - npm ci
      - npm test (Vitest)
      - npx tsc --noEmit (type-check)
      - npm run build (Next.js production build)
      - if main + tests OK → git tag deploy-marketplace-YYYY.MM.DD-XXX
      - if main → AWS Amplify auto-deploy hook
      - smoke test post-deploy (curl marketplace.smconnection.cl status 200)
      - if smoke fail → rollback automático + alerta Sentry

Rollback strategy

• AWS Amplify mantiene últimos 25 builds
• Rollback en 1 click vía console O CLI
• Tag deploys permite git checkout fácil
• Si rollback dispara → notification founders + Sentry incident

13Escalabilidad técnica · cuándo refactorizar

SEÑAL                                          ACCIÓN
─────────────────────────────────────────────────────
Build time > 5min                              Turbopack tuning · code splitting
Bundle client > 500KB                          Dynamic imports · server components
API p95 > 800ms                                Add caching · index DB · query review
DB connections agotadas                        Pool tuning · pgBouncer
1 canal > 80% revenue                          Acelerar diversificación (BR-driven)
Founder > 8h/día sistema                       Automatizar más · agentes IA bg
Tests > 5min                                   Parallelizar · test sharding
Costo IA > $300K CLP/mes                       Cache prompts comunes · downgrade modelos
Tabla Postgres > 1M rows                       Indexar correctamente · particionar
Tenant count > 5                               Migrar de tenant_id implicit a explicit
                                               sharding (Y3+)

Cuándo NO refactorizar

• ❌ "Para hacer el código más limpio" sin métrica concreta
• ❌ "Para usar la tecnología nueva X" sin caso de uso real
• ❌ "Porque siempre quise" — guardarse para hobbies personales

14ADRs registradas · 6 decisiones

14b · ADR-0006 · SoloTodo Plan B mientras MeLi aprueba app

Status: ✅ Accepted · 2026-05-27

Context: app SmartConnection-Marketplace en review PolicyAgent MeLi (developers.mercadolibre.cl). Mientras no esté aprobada · endpoints públicos MeLi devuelven 403 desde servidores (anti-scraping). Sin OAuth tampoco se puede leer catálogo.

Decisión: usar SoloTodo API (api.solotodo.com · MELI_STORE_ID=260) como fuente de catálogo MeLi Chile mientras MeLi aprueba.

Por qué SoloTodo:

• 58K+ productos MeLi Chile indexados (verificado live 2026-05-27)
• Precios actualizados cada 6-12h
• URLs reales del producto en MeLi (clickeables)
• Cross-store: agrupa precios MeLi vs Falabella · París · Ripley · etc
• API pública sin auth · sin costo
• Estable hace años (proyecto chileno consolidado)

Trade-offs aceptados:

• ❌ NO permite publicar ni vender · solo lectura
• ❌ NO entrega cuentas propias (es público · vemos competencia · no nuestras ventas)
• ❌ Latencia 6-12h vs real-time webhook MeLi
• ✅ Cubre 100% análisis competencia + scoring oportunidades
• ✅ Cero costo · cero riesgo policy
• ✅ Cuando MeLi apruebe → se mantiene como caché/fallback redundante

Cómo se usa en código:

• lib/solotodo-client.ts (329 líneas · client con tipos completos)
• app/api/solotodo/test/route.ts (health check)
• app/dashboard/settings/page.tsx (botón "Probar conexión SoloTodo")
• Sprint 3: integrar en Sistema Oportunidades como fuente de precios competencia

Cuándo deprecate SoloTodo:

• NUNCA · se mantiene siempre como fallback redundante
• Costo cero · no afecta cuotas MeLi · ayuda a validar consistencia precios

Riesgo: SoloTodo cambia API o sube paywall.

Mitigación: API pública desde 2014 · sin señales de cierre. Si pasa → seguimos con MeLi OAuth directo.

14c · ADR-0007 · Gmail API en vez de Resend Y1

Status: ✅ Accepted · 2026-05-27

Context: necesitamos enviar emails transaccionales (tracking · confirmación venta · post-venta · alertas founders). Sprint inicial sugirió Resend (servicio especializado · $0-20/mes). Founders ya tienen Google Workspace activo (smconnection.cl) con Gmail API funcional.

Decisión: usar Gmail API (cuenta marketplace@smconnection.cl) como motor de envío Y1.

Por qué Gmail API:

• Costo cero adicional (Workspace Business Starter ya pagado)
• Reputación dominio establecida (mejor deliverability que Resend nuevo)
• OAuth 2.0 SDK oficial googleapis
• 500-2000 emails/día por usuario Workspace (suficiente Y1)
• API SMC ya tiene credenciales (reference_google_workspace.md)

Trade-offs:

• ❌ No tiene templates fancy ni analytics builtin (debemos loggear nosotros)
• ❌ Limit 500-2000/día · si Marketplace explota (>2K órdenes/día) tendríamos que migrar
• ❌ Sin warming dominio automático
• ✅ Cero costo · cero proveedor nuevo
• ✅ Templates en código versionados @smc/prompts (regla Hoku)

Cuándo migrar a Resend:

• Volumen >1.5K emails/día sostenido (Y2 escalado)
• Necesitamos templates editables sin deploy
• Founders quieren métricas opens/clicks builtin

Cómo se usa en código (Sprint 4):

• lib/email/gmail-client.ts · googleapis SDK
• lib/email/templates/ · markdown templates versionados
• Cron 5min batch envíos (evita rate limit)
• Logging en mkt_email_logs (similar a mkt_ai_logs)

14d · ADR-0008 · Pagos dual: transferencia Kanki-style + MercadoPago opt

Status: ✅ Accepted · 2026-05-27

Context: necesitamos cobrar en D2C storefront. Sprint inicial sugirió MercadoPago + WebPay Plus. Founders recién partiendo · sin volumen para justificar setup pasarelas. Kanki Street (proyecto hermano SMC) opera con transferencia bancaria manual exitosamente.

Decisión: ofrecer transferencia bancaria Kanki-style como default Y1 + MercadoPago opcional activable por SKU/cliente. WebPay Plus deferido Y2.

Por qué dual:

Flow transferencia Kanki-style:

• Cliente hace checkout · ve datos transferencia (cuenta · RUT · monto · referencia)
• Cliente sube comprobante PDF/imagen en UI
• Sistema crea orden status=payment_pending
• Founder recibe alerta · revisa comprobante · marca payment_verified
• Workflow normal sigue (DTE + label + despacho)

Flow MercadoPago (cuando activado por SKU):

• Cliente hace checkout · redirect MercadoPago
• Pago real-time · webhook firmado → orden status=paid directo
• Workflow normal sigue

Tabla mkt_orders.payment_method: 'transferencia' | 'mercadopago' | 'webpay' (futuro)

Tabla mkt_payment_proofs (nueva Sprint 5): comprobantes uploaded con verify state

Cuándo activar MercadoPago default:

• >20 órdenes/día sostenido 30 días
• Founders confirman costo 2.9-4.5% es asumible vs tiempo manual
• Cliente B2B grande que exige instantáneo

Costo evitado Y1: ~2.9-4.5% × revenue total Y1. Con 50 órdenes/mes × $25K CLP × 12 meses = $15M CLP/año revenue · ahorro ~$435K-675K CLP.

15Performance budgets

16Security requirements · 12 items con implementación

17Observabilidad · LLMOps detallado

LOG estructurado JSON por evento
─────────────────────────────────────────────────────
{
  timestamp: "2026-10-15T14:23:11.234Z",
  level: "info|warn|error",
  request_id: "uuid-correlation",
  user_id: "uuid",
  tenant_id: "uuid",
  feature: "products.list",
  endpoint: "/api/products",
  method: "GET",
  status: 200,
  duration_ms: 124,
  error_msg: null,
  metadata: { /* feature-specific */ }
}

→ stdout (CloudWatch) + tabla mkt_api_logs (Postgres queryable)

LLMOps específico Cerebro
─────────────────────────────────────────────────────
{
  timestamp: "2026-10-15T14:23:15.123Z",
  feature: "cerebro.chat",
  provider: "groq",
  model: "llama-3.3-70b-versatile",
  prompt_version: "chat-v2.1",
  tokens_in: 1234,
  tokens_out: 456,
  cost_usd: 0.00021,
  latency_ms: 287,
  cache_hit: false,
  fallback_used: false,
  hallucination_flag: false
}

→ tabla mkt_ai_logs · dashboards costo/feature/día/founder

ALERTAS configuradas (CloudWatch + Sentry)
─────────────────────────────────────────────────────
- Error rate > 1% por 5 min          → email founders
- p95 API > 800ms por 10 min         → email
- Cost IA diario > 80% budget        → email + auto-throttle
- Sync canal fallido > 3 retries     → email + alert PostHog
- DTE SII rechazo                    → email INMEDIATO
- 401/403 spike > 10/min             → posible attack · email

18Próximos pasos técnicos

• ✅ Doc 13 v2 · granular · librerías · flujos detallados
• ⏭️ Tu OK plan
• ⏭️ Empezar implementación Q4-26 según Doc 18 Plan Ejecución
• ⏭️ Doc 19 UAT post-construcción