00Mapa interactivo HLA · Visio-style

Diagrama vivo de la arquitectura Marketplace SMC. Click en cualquier bloque para ver detalle · descripción · stack · owner · canales · docs relacionados. Filtros arriba para aislar el flujo de un canal específico (MeLi · D2C · MP · B2B). Hover destaca la ruta end-to-end que toca ese componente. Zoom con la rueda + ⌘/Ctrl o con los botones · arrastrá para hacer pan.

Tip: click en un bloque para ver detalle · Esc cierra · arrastra el canvas para hacer pan · ⌘/Ctrl + scroll para zoom.

00bProcesos dinámicos · 5 escenarios

Cómo recorre el sistema un caso real paso a paso. Seleccioná un escenario (A · B · C · D · E) para ver su pipeline horizontal con etapas y pasos integración (INT-XXX). Click en un paso para ver descripción · stack · sample payload · errores comunes · docs relacionados.

Tip: cambiar escenario re-renderiza el pipeline · click en cualquier INT-XXX abre detalle del paso · Esc cierra.

01Arquitectura alto nivel

01bArquitectura v5 · Opportunities System

Scoring Engine · 6 señales

02Stack técnico decidido

03Estructura monorepo

smc-marketplace-hub/
├── apps/
│   ├── web/                    # Next.js app (frontend + API)
│   │   ├── app/
│   │   │   ├── (auth)/         # login · signup
│   │   │   ├── (dashboard)/    # cockpit operador
│   │   │   │   ├── inventory/
│   │   │   │   ├── channels/
│   │   │   │   │   ├── meli/
│   │   │   │   │   ├── mp/
│   │   │   │   │   ├── d2c/
│   │   │   │   │   └── b2b/
│   │   │   │   ├── orders/
│   │   │   │   ├── finance/
│   │   │   │   ├── cerebro/
│   │   │   │   └── analytics/
│   │   │   └── api/
│   │   │       ├── webhooks/   # meli · mp · webpay · etc.
│   │   │       ├── cron/       # refresh-tokens · mp-tenders
│   │   │       └── v1/         # APIs internas REST
│   │   └── package.json
│   └── storefronts/            # marcas propias futuras
│       └── marca-1/            # primera marca migrada al Hub
│
├── packages/
│   ├── core/                   # @smc/core · dominio puro
│   │   ├── inventory/
│   │   ├── orders/
│   │   ├── finance/
│   │   ├── events/             # Event bus interno
│   │   └── tenants/
│   ├── channels/               # @smc/channels · adapters
│   │   ├── _interface.ts       # interfaz ChannelAdapter
│   │   ├── meli/
│   │   ├── mp/
│   │   ├── d2c/
│   │   ├── b2b/
│   │   └── falabella/
│   ├── ui/                     # @smc/ui (existente)
│   ├── shared/                 # @smc/shared · types · utils
│   ├── ai/                     # @smc/ai · Cerebro · Groq client · prompts
│   └── billing/                # @smc/billing · DTE · Open Factura
│
├── supabase/
│   ├── migrations/             # SQL versionado
│   ├── seed/                   # data fixtures dev
│   └── functions/              # Edge Functions opcional
│
├── .github/
│   └── workflows/              # CI/CD
│
└── docs/                       # blueprint + ADRs (estos docs)

04Event-driven · cómo funciona

Cada operación significativa emite un evento. Los módulos suscritos reaccionan automático. Esto evita acoplamiento (módulo finance no llama a inventory · escucha eventos).

05Multi-tenancy técnico · Row Level Security

Setup RLS Postgres

-- En cada query, el server setea el tenant context
SET app.current_tenant = '<tenant-uuid>';

-- Policy aplicada a TODAS las tablas (excepto mk_tenants y mk_users)
CREATE POLICY tenant_isolation ON mk_products
  USING (tenant_id = current_setting('app.current_tenant')::uuid)
  WITH CHECK (tenant_id = current_setting('app.current_tenant')::uuid);

ALTER TABLE mk_products ENABLE ROW LEVEL SECURITY;
ALTER TABLE mk_products FORCE ROW LEVEL SECURITY;

Flujo request

1. Operador hace login · recibe JWT que incluye tenant_id
2. Cada request incluye header X-Tenant-Id
3. Middleware Next.js valida JWT + tenant_id match con permisos del usuario
4. Middleware setea SET app.current_tenant = ? en conexión Postgres
5. Cualquier query subsiguiente está auto-filtrada por RLS
6. Imposible (técnicamente) que tenant A vea data de tenant B aunque haya bug en código aplicación

06Deploy · ambientes · CI/CD

Pipeline CI/CD

push branch → GitHub Actions:
   1. install (cache pnpm)
   2. lint (eslint)
   3. type-check (tsc --noEmit)
   4. unit tests (vitest run)
   5. build (next build)
   6. integration tests (vitest --integration)
   7. e2e smoke (playwright · solo en main)
   8. deploy (auto vía Amplify webhook)
   9. health check post-deploy (curl /api/health)
   10. rollback automático si health falla

Migraciones BD

• SQL versionado en supabase/migrations/YYYY-MM-DD-name.sql
• CI corre migraciones contra staging primero · verifica · luego PRD
• Rollback scripts obligatorios para cada migration
• Zero downtime · todas las migraciones backward-compatible (additive)

07Observabilidad · LLMOps

08Seguridad operativa

• Secrets: AWS Secrets Manager (Amplify env vars en plano solo en MVP · migrar a Secrets Manager Q2)
• OAuth tokens externos: cifrados at rest con pgcrypto en mk_channels.credentials
• Refresh tokens: cron auto-renueva antes de expirar (existe lib en código actual)
• HTTPS: obligatorio · HSTS · TLS 1.3 mínimo · cert auto AWS ACM
• CSP: Content Security Policy estricta · no inline scripts
• Rate limiting: por IP en endpoints públicos · por tenant en API interna
• Audit trail: mk_audit_changes en cada UPDATE/DELETE de tablas financieras
• 2FA: opcional MVP · obligatorio para rol admin desde Fase 2
• Backups BD: Supabase point-in-time recovery 7 días (plan Pro) · snapshot diario S3
• Penetration testing: antes de Fase 4 (SaaS público) · vendor externo
• SOC2 readiness: documentar controles desde día 1 · si se vuelve SaaS · auditoría Q4 año 2

09Escalabilidad técnica · cuándo refactorizar

10ADRs · decisiones registradas

Architectural Decision Records · cada decisión clave queda en docs/adrs/NNNN-titulo.md