Shopilot.ai Shopilot.ai

// Electron Main Process Components:
// 1. WindowManager: 1200x800 default, split 70% WebContentsView / 30% Sidebar
// 2. MarketplaceDetector URL patterns:
//    mercadolibre.com.*/seller/*      -> MeLi Seller Center
//    mercadolibre.com.*/p/*           -> MeLi Product Page
//    sellercentral.amazon.com/*       -> Amazon Seller Central
//    admin.shopify.com/*              -> Shopify Admin
//    *                                -> Other (no injection)
// 3. SessionManager: separate cookie partitions per marketplace
// 4. TabManager: Cmd+1=MeLi, Cmd+2=Amazon, Cmd+3=Shopify
// 5. CredentialsManager: JWT in Electron safeStorage
// 6. OAuthPopupManager: dedicated BrowserWindow for OAuth2 redirects
// 7. IPC channels: marketplace:detected, auth:get-token, nav:go, notification:show, oauth:start

// Preload Script (secure bridge):
contextBridge.exposeInMainWorld('shopilotBridge', {
  getMarketplaceContext: () => ipcRenderer.invoke('ctx'),
  getAuthToken: () => ipcRenderer.invoke('auth:get-token'),
  navigateTo: (url: string) => ipcRenderer.send('nav:go', url),
  onNotification: (cb: Function) => ipcRenderer.on('notification', cb),
  startOAuth: (marketplace: string) => ipcRenderer.invoke('oauth:start', marketplace),
})
// NEVER expose ipcRenderer directly

// === COACH → SHELL (server-to-client events) ===
interface TextChunkEvent     { type: 'text_chunk';             text: string }
interface ToolStartEvent     { type: 'tool_start';             toolId: string; toolName: string; category: 'READ'|'WRITE'|'ANALYSIS'|'SYSTEM' }
interface ToolProgressEvent  { type: 'tool_progress';          toolId: string; message: string }  // "Consultando metricas..."
interface ToolCompleteEvent  { type: 'tool_complete';          toolId: string; resultSummary: string }
interface ConfirmationReqEv  { type: 'confirmation_required';  confirmationId: string; action: string; before: object; after: object }
interface SuggestionEvent    { type: 'suggestion';             id: string; suggestionType: string; message: string; priority: number }
interface ErrorEvent         { type: 'error';                  code: string; message: string }
interface RoundEndEvent      { type: 'round_end';              roundNumber: number; creditsUsed: number }

// === SHELL → COACH (client-to-server events) ===
interface MessageEvent       { type: 'message';               text: string; marketplaceContext: MarketplaceContext }
interface ConfirmationResEv  { type: 'confirmation_result';   confirmationId: string; approved: boolean }
interface CancelEvent        { type: 'cancel' }
interface ContextUpdateEvent { type: 'context_update';        marketplace: string; page: string; productId?: string }

// Connection: wss://api.shopilot.ai/ws?token={JWT}
// Reconnect: exponential backoff (1s, 2s, 4s, 8s, max 30s)
// Heartbeat: ping/pong every 30s, timeout 90s
// Session restore: on reconnect, server replays last incomplete round

// === React Hooks (7 total, was 4) ===
// useShopilot()     — WebSocket lifecycle, send/receive, streaming text assembly, reconnect
// useMarketplace()  — IPC marketplace:detected events, current context
// useSuggestions()   — Receives suggestion events via WebSocket (was: REST polling)
// useCredentials()   — Get/refresh JWT via IPC
// useProfile()       — GET/PUT /users/:userId/profile, form state (NEW)
// useBilling()       — GET /billing/status, plan/credits/period (NEW)
// useEnrollment()    — GET /auth/marketplaces/:userId, connect/disconnect flows (NEW)

// === Sidebar Views (react-router, in-sidebar navigation) ===
// /chat              — Default: ChatPanel + SuggestionCards + ToolProgress + ConfirmationDialog
// /profile           — ProfileView: name, categories, goals, language, connected marketplaces (read-only)
// /billing           — BillingView: plan badge, credits bar, billing period, upgrade/pack/portal buttons
// /enrollment        — EnrollmentView: marketplace cards (MeLi/Amazon/Shopify), connect/disconnect, status
// /onboarding        — OnboardingWizard: 5-step guided setup (first run only)

// === Sidebar Navigation ===
// Header: Logo + marketplace indicator + credits badge + nav icons (chat | profile | billing | enrollment)
// Bottom nav or icon bar for view switching — chat is always the primary/default view

// === Keyboard Shortcuts ===
// Cmd+L -> Focus chat input
// Cmd+B -> Toggle sidebar
// Cmd+K -> Command palette
// Cmd+1..9 -> Switch marketplace tabs
// Escape -> Cancel current operation / dismiss confirmation
// Cmd+Enter -> Send message (Enter = newline)
// Cmd+Shift+D -> Toggle Dev Tools panel (dev mode only)

// Auto-Updater: electron-updater + GitHub Releases, check on startup + every 6h

// From #2 Orchestrator:
// WebSocket wss://api.shopilot.ai/ws  — streaming protocol defined above

// From #13 Billing:
// GET  /billing/status             — BillingStatus (plan, credits, period)
// POST /billing/checkout           — Stripe Checkout redirect (upgrade to Pro)
// POST /billing/packs/checkout     — Stripe Checkout redirect (buy Credit Pack)
// POST /billing/portal             — Stripe Customer Portal redirect

// From #12 Marketplace Provider:
// POST   /auth/connect/:marketplace           — Start OAuth2, returns redirect URL
// GET    /auth/callback/:marketplace          — OAuth2 callback (handled in popup)
// GET    /auth/marketplaces/:userId           — List connected marketplaces + status
// DELETE /auth/disconnect/:userId/:marketplace — Revoke tokens + cleanup

// From UserProfile API (DynamoDB):
// GET  /users/:userId/profile      — UserProfile (name, categories, goals, prefs)
// PUT  /users/:userId/profile      — Update UserProfile

• [Shell] App opens, loads MeLi, sidebar works in <5s
• [Shell] MarketplaceDetector identifies: seller center, product detail, search results
• [Shell] App does not exceed 500MB RAM with 3 tabs open (target 400MB)
• [Shell] .dmg installs on Mac without unsigned app errors
• [Chat] WebSocket streaming: text_chunk events render <50ms after receipt (no visible lag)
• [Chat] tool_start/tool_progress/tool_complete events show real-time progress indicator
• [Chat] Confirmations show clear before/after with working Accept/Reject buttons
• [Chat] WebSocket reconnects automatically with exponential backoff, session restores last incomplete round
• [Profile] ProfileView loads user data, edits save to backend, changes reflect in Coach context within next message
• [Billing] BillingView shows plan, credits remaining (bar), billing period. Upgrade button opens Stripe Checkout. Pack button opens pack Checkout
• [Enrollment] "Connect MeLi" opens OAuth2 popup, completes flow, marketplace appears as connected. Same for Amazon and Shopify
• [Enrollment] "Disconnect" revokes tokens and updates status immediately
• [Onboarding] First-time user sees OnboardingWizard: profile setup → marketplace connect → first chat → tour. Completion persisted
• [Onboarding] Returning user skips onboarding, goes directly to chat
• [Shortcuts] Cmd+L focus chat, Cmd+B toggle sidebar, Cmd+K command palette
• [Update] Auto-updater downloads and installs updates without crash

• [Shell] App abre, carga MeLi, sidebar funciona en <5s
• [Shell] MarketplaceDetector identifica: seller center, detalle de producto, resultados busqueda
• [Shell] App no excede 500MB RAM con 3 tabs abiertos (meta 400MB)
• [Shell] .dmg se instala en Mac sin errores de app no firmada
• [Chat] Streaming WebSocket: eventos text_chunk renderizan <50ms despues de recepcion (sin lag visible)
• [Chat] Eventos tool_start/tool_progress/tool_complete muestran indicador de progreso en tiempo real
• [Chat] Confirmaciones muestran before/after claro con botones Aceptar/Rechazar funcionales
• [Chat] WebSocket reconecta automaticamente con backoff exponencial, sesion restaura ultimo round incompleto
• [Perfil] ProfileView carga datos del usuario, ediciones guardan al backend, cambios se reflejan en contexto del Coach en el siguiente mensaje
• [Billing] BillingView muestra plan, creditos restantes (barra), periodo de facturacion. Boton upgrade abre Stripe Checkout. Boton pack abre Checkout de packs
• [Enrollment] "Conectar MeLi" abre popup OAuth2, completa flujo, marketplace aparece como conectado. Igual para Amazon y Shopify
• [Enrollment] "Desconectar" revoca tokens y actualiza estado inmediatamente
• [Onboarding] Usuario nuevo ve OnboardingWizard: setup perfil → conectar marketplace → primer chat → tour. Completacion persistida
• [Onboarding] Usuario que regresa salta onboarding, va directo al chat
• [Shortcuts] Cmd+L foco chat, Cmd+B toggle sidebar, Cmd+K paleta de comandos
• [Update] Auto-updater descarga e instala updates sin crash

Window: 1200x800 · Split: 70/30 · RAM: <500MB (target 400MB) · WS heartbeat: 30s · WS reconnect: exp backoff max 30s · Auto-update: startup + 6h · Mac only MVP

// === ATOMS (13) — base components, single responsibility ===
Button, Input, Badge, Icon, StatusDot, Spinner, Toggle, Divider,
AvatarInitials, CreditBadge, ProgressBar, Tooltip, KbdShortcut

// === AI-NATIVE ATOMS (6) — specific to conversational copilot ===
StreamingCursor (█), ThinkingPulse (•••), ToolBadge,
AgentStatusBar, RiskBadge, TTLCountdown

// === MOLECULES (10) — atom combinations ===
SearchBar, TabBar, Select, Toggle (labeled), Tooltip (rich),
ProgressBar (labeled), Dropdown, KbdShortcut (combo), InputField, CreditDisplay

// === ORGANISMS (16) — complex UI blocks ===
ChatInputBar, MessageBubble, ContextBar, ToolAccordion, ConfirmDialog,
ReActStream, ProactiveCard, DataTable, AuditLog, RollbackPanel,
FraudAlert, MarketplaceKPI, CreditEconomy, OnboardingStep,
EnrollmentCard, ErrorRecovery

// === SCREENS (5) — full views at 360px sidebar width ===
ChatView, Dashboard, Settings, Billing, Enrollment

D1: Brand emotion      PENDING  A: "Warm Precision" (rec) / B: "Data Intelligence" / C: "Growth Engine"
D2: Primary color      PENDING  Orange #F97316 / Indigo #6366F1 / Sky #0EA5E9 / Emerald #10B981
D3: Background mode    PENDING  Dark-first (rec) / Light-first / Both
D4: Typography         PENDING  Inter + JetBrains Mono / Geist + Geist Mono / IBM Plex
D5: Logo               PENDING  Wordmark / Icon + Wordmark (rec) / Abstract mark
D6: Border radius      PENDING  Sharp (2-4px) / Standard (6-8px) / Rounded (12-20px)
D7: Shadow policy      PENDING  None / Minimal / Soft
D8: Semantic palette   PENDING  Green/Amber/Red/Blue standard (blocked by D3)
D9: UI voice           PENDING  Direct & human / Technical & precise / Empowering & confident

// Until D1-D9 are decided, cannot generate design-tokens.json nor implement components

// 00 Primitives (raw values — NEVER applied directly to designs)
color/blue/50..900, gray/50..900, red/50..900, green/50..900
spacing/0, 1(4px), 2(8px), 3(12px), 4(16px), 6(24px), 8(32px)
radius/none(0), sm(4), md(8), lg(12), xl(16), full(9999)
font-size/xs(12), sm(14), base(16), lg(18), xl(20), 2xl(24)

// 01 Semantic (with Light/Dark modes — what components use)
color/bg/primary       → white (light) | gray/900 (dark)
color/bg/secondary     → gray/50 (light) | gray/800 (dark)
color/text/primary     → gray/900 (light) | white (dark)
color/border/default   → gray/200 (light) | gray/700 (dark)
color/interactive/primary → blue/600
spacing/component/padding-sm → spacing/2
radius/component/button → radius/md

// 02 Component (optional — unique overrides only)
button/bg/primary      → color/interactive/primary
input/border           → color/border/default
input/border-focus     → color/border/focus

// Code Syntax mapping: variable → var(--color-bg-primary)

Figma Team: Shopilot Design
├── [LIB] Foundations & Tokens     ← variables, colors, typography, spacing
├── [LIB] Iconography              ← icons (changes frequently, many assets)
├── [LIB] Core Components          ← atoms + molecules
├── [LIB] Pattern Components       ← organisms + templates
├── Documentation & Playground     ← usage guides, do/don't (not published)
└── Changelog & Governance         ← change history (not published)

// Publish order: Tokens → Icons → Core Components → Patterns
// Each component file has: Cover, Getting Started, Changelog, Atoms, Molecules, Organisms, ._Base, Archive

// .claude/settings.json — MCP permissions
mcp__figma__get_file            // read full Figma file
mcp__figma__get_node            // read specific component node
mcp__figma__get_design_context  // extract design context
mcp__figma__get_variable_defs   // read token variables (MUST run before implementing)
mcp__figma__get_metadata        // read component metadata (MUST run before implementing)
mcp__pencil__design             // complementary: rapid prototyping without designer

// Workflow:
// 1. Agent runs get_variable_defs + get_metadata
// 2. Reads component structure from Figma
// 3. Implements matching React component in core-product-desktop-client
// 4. Code review verifies fidelity to Figma spec

// 5 mandatory deliverables from external design team:
1. Logo system: icon+wordmark, reduced icon, monochrome (white+black), SVG+PNG @1x-3x
2. Color palette: primary, secondary, semantic (success/warning/error/info), neutrals, dark mode mapping, WCAG AA ratios
3. Typography: display + body + monospace fonts, scale (10-24px), weights, files (.woff2 + .ttf)
4. Voice & tone: 3-5 brand personality attributes, context variations, "sounds like" vs "doesn't sound like"
5. 44 components with brand identity applied: all states (default, hover, active, focus, disabled), dark mode, WCAG AA

// NOT in scope: user flows, social media guidelines, corporate stationery, motion specs, code implementation

Brand decisions (Pablo D1-D9)
    ↓
External design team creates Figma with variables + codeSyntax
    ↓
Agent runs get_variable_defs + get_metadata via Figma MCP
    ↓
Generates design-tokens.json (W3C DTCG format)
    ↓
Style Dictionary transforms → CSS :root + Tailwind config
    ↓
Agent implements React component in core-product-desktop-client (#1)
    ↓
Code review verifies fidelity: tokens + a11y + responsive + states

Status:  specs → ✓ | Figma → ✗ | design-tokens.json → ✗ | React components → ✗

Blockers:
1. 9 brand decisions (D1-D9) not yet taken — blocks entire pipeline
2. No brand assets — no logo, no licensed fonts, no brand book in repo
3. No Figma file — no source of truth for agent (requires multi-file libraries, 3 variable collections, Code Syntax, Auto Layout, Light/Dark modes)
4. No brand book — external design team has not delivered yet

core-product-design-system/
├── README
├── CLAUDE.md                              ← agent instructions
├── brand/                                 ← brand assets (PENDING)
│   ├── logo/                              ← logo variants (SVG, PNG)
│   ├── fonts/                             ← licensed fonts
│   └── brand-book.md                      ← brand guidelines
├── tokens/                                ← pipeline output (PENDING)
│   └── design-tokens.json                 ← generated from Figma variables
└── .claude/
    ├── settings.json                      ← MCP permissions (figma + pencil)
    ├── memory/MEMORY.md                   ← state, decisions, catalogue
    └── specs/ (8 docs, 1930 lines)        ← architecture, contracts, dev plan, testing, figma specs

AC-18.1:  All 9 brand decisions (D1-D9) resolved and documented
AC-18.2:  Brand book delivered: logo system + color palette + typography + voice/tone + 44 components with brand applied
AC-18.3:  Figma multi-file structure: Foundations, Icons, Core Components, Patterns (not monolithic)
AC-18.4:  3 variable collections (Primitives → Semantic → Component) with Code Syntax + Light/Dark modes
AC-18.5:  All 44 components in Figma: Auto Layout, all states, Component Properties, slash naming
AC-18.6:  design-tokens.json generated → Style Dictionary → CSS :root + Tailwind config in #1
AC-18.7:  Claude reads and implements Figma components in #1 via Figma MCP (get_variable_defs + get_metadata)
AC-18.8:  WCAG 2.2 AA compliance: contrast ≥4.5:1 text, ≥3:1 UI, :focus-visible, touch target ≥44px
AC-18.9:  No React components in #1 exist outside of what is defined in the Figma
AC-18.10: Zero Figma anti-patterns: no detached instances, no hardcoded hex, no generic names, no absolute positioning

// OrchestrationSession — stateful domain model
interface OrchestrationSession {
  sessionId: string             // ULID
  conversationId: string        // DynamoDB conversation ID
  userId: string                // Memberstack ID
  marketplace: Marketplace

  status: 'idle' | 'running' | 'awaiting_confirmation' | 'done' | 'error'
  currentRound: number          // 0..MAX_ROUNDS

  messages: ConversationMessage[]
  // { role: 'user', content: string }
  // { role: 'assistant', content: ContentBlock[] }  // may include tool_use
  // { role: 'user', content: ToolResultBlock[] }

  pendingConfirmation: ConfirmationRequest | null
  // { toolName, toolArgs, riskLevel: 'reversible'|'irreversible',
  //   preview: { before, after }, expiresAt: Date (30min) }

  costAccumulator: { totalTokens: number, toolCallCount: number }
}

// RoundDecision — output of evaluating each LLM response
type RoundDecision =
  | 'respond'         // text only -> emit response, end loop
  | 'execute_tool'    // tool_use blocks -> execute and observe
  | 'await_confirm'   // write tool -> pause loop, persist session
  | 'max_rounds'      // round 10 -> force final response
  | 'cost_guard'      // >50K tokens -> force final response

// IReActOrchestrator — conversational entry point
interface IReActOrchestrator {
  handleMessage(params: {
    userId: string; conversationId: string;
    content: string; marketplace: Marketplace;
  }): Promise<OrchestrationResult>

  resumeAfterConfirmation(params: {
    sessionId: string; confirmed: boolean;
  }): Promise<OrchestrationResult>
}

// IEventEmitter — decouples loop from transport
type OrchestrationEvent =
  | { type: 'text_chunk'; content: string }
  | { type: 'tool_start'; toolName: string; args: unknown }
  | { type: 'tool_result'; toolName: string; result: unknown; latencyMs: number }
  | { type: 'confirmation_required'; preview: ConfirmationPreview }
  | { type: 'end_turn'; summary: OrchestrationSummary }
  | { type: 'error'; message: string }
// Phase 0.3: RestResponseEventEmitter (accumulate, return at end)
// Phase 4:   WebSocketEventEmitter (real-time streaming)

// OrchestrationSummary — included in end_turn event
interface OrchestrationSummary {
  rounds: number
  tokensUsed: number
  actionsExecuted: ActionSummary[]   // WRITE tools executed this turn
  confirmationsRequested: number
  latencyMs: number
}

// ActionSummary — one WRITE action performed by the Coach
interface ActionSummary {
  toolName: string                   // e.g. 'update_product_content'
  sku: string
  fieldChanged: string               // e.g. 'title'
  previousValue: unknown             // from snapshot_product
  newValue: unknown
  success: boolean
}
// Enables: Shell shows seller what changed, Feedback Loop (#15) measures impact

// IContextWindowManager — compaction + truncation
interface IContextWindowManager {
  guard(messages: ConversationMessage[], modelTokenLimit: number): Promise<ConversationMessage[]>
  truncateToolResult(result: unknown, maxTokens: number): unknown
}
// Triggers at 92% of model limit. Preserves last 10 messages + active round tool_results.

// IOrchestrationRepository — session persistence for ConfirmationFlow
// DynamoDB with 35min TTL. Only used during PAUSE/RESUME.

// IOrchestrationTracer — fire-and-forget observability
// Reuses ConversationTrackingOrchestrator. If PostgreSQL fails, loop continues.

• [Ph 0.3] Conversation history sent to LLM in every turn (fix: data exists in DynamoDB, just load and pass)
• [Ph 0.3] ReAct loop active with MAX_ROUNDS=10 guard + cost guard (50K tokens)
• [Ph 0.3] Context compaction triggers at 92% of model limit, preserves last 10 messages
• [Ph 0.3] OrchestrationSession persisted in DynamoDB with 35min TTL
• [Ph 0.3] REST response via RestResponseEventEmitter (accumulate + return)
• [Ph 1] ConfirmationFlow: pause/serialize/confirm/reject/timeout works end-to-end
• [Ph 1] Tool loop detection: same tool+args in 2 consecutive rounds is blocked
• [Ph 1] Prompt caching with cache_control reduces input token cost 60-80%
• [Ph 4] WebSocket streaming with text_chunk events in real-time
• [Ph 1] Tool error recovery: errors become observations, LLM retries with corrected args. Max 3 consecutive failures on same tool → respond with available info
• [Ph 2] ResponseVerifier: post-generation check contrasts cited data (fees, metrics, prices) against retrieved data. Discrepancy → clarification or regeneration
• [Ph 2] Extended thinking: selective activation for complex multi-variable analysis (e.g., sales diagnosis across price, positioning, competitors, seasonality). Not active for simple queries
• [Ph 4] SubtaskRunner: independent sub-objectives executed in parallel (e.g., "analyze my top 3 products" → 3 parallel analyses → merged response)
• [Ph 1] end_turn event includes actionsExecuted[] enumerating every WRITE tool result from the turn (toolName, SKU, fieldChanged, previousValue, newValue, success)

• [F 0.3] Historial de conversacion enviado al LLM en cada turno (fix: dato existe en DynamoDB, solo cargar y pasar)
• [F 0.3] Loop ReAct activo con guard MAX_ROUNDS=10 + cost guard (50K tokens)
• [F 0.3] Compactacion de contexto se dispara al 92% del limite del modelo, preserva ultimos 10 mensajes
• [F 0.3] OrchestrationSession persistida en DynamoDB con TTL de 35min
• [F 0.3] Respuesta REST via RestResponseEventEmitter (acumular + retornar)
• [F 1] ConfirmationFlow: pause/serializar/confirmar/rechazar/timeout funciona end-to-end
• [F 1] Deteccion de loop de tools: misma tool+args en 2 rondas consecutivas se bloquea
• [F 1] Prompt caching con cache_control reduce costo de tokens de entrada 60-80%
• [F 4] WebSocket streaming con eventos text_chunk en tiempo real
• [F 1] Recuperacion de errores de tools: errores se convierten en observaciones, LLM reintenta con args corregidos. Max 3 fallos consecutivos en misma tool → responder con info disponible
• [F 2] ResponseVerifier: verificacion post-generacion contrasta datos citados (fees, metricas, precios) contra datos recuperados. Discrepancia → aclaracion o regeneracion
• [F 2] Razonamiento extendido: activacion selectiva para analisis complejos multi-variable (ej: diagnostico de ventas cruzando precio, posicionamiento, competidores, temporada). No se activa para consultas simples
• [F 4] SubtaskRunner: sub-objetivos independientes ejecutados en paralelo (ej: "analiza mis 3 productos mas vendidos" → 3 analisis en paralelo → respuesta fusionada)
• [F 1] Evento end_turn incluye actionsExecuted[] listando cada resultado de WRITE tool del turno (toolName, SKU, fieldChanged, previousValue, newValue, success)

MAX_ROUNDS: 10 · Cost guard: 50K tokens · Compaction: 92% · Truncation: 4K tokens · Confirmation TTL: 35min · Cache hit L1: >95%

interface ToolDefinition {
  name: string              // Name the LLM uses to invoke
  description: string       // description_for_llm — optimized for correct selection
  inputSchema: JSONSchema    // Parameters (JSON Schema format)
  riskLevel: ToolRiskLevel  // 'read_only' | 'reversible' | 'irreversible'
  marketplace: Marketplace[] // Compatible marketplaces. [] = all
  category: ToolCategory    // 'READ' | 'ANALYSIS' | 'SYSTEM' | 'WRITE'
  phase: Phase              // Implementation phase (1-5)
  estimatedTokens?: number  // Result cost estimate (for cost guard)
}

interface ToolContext {
  userId: string
  marketplace: Marketplace
  plan: 'free' | 'pro'
  conversationId: string
  executionId?: string      // From IOrchestrationTracer
}

interface ToolResult {
  toolName: string
  content: unknown          // Raw result
  truncated: boolean        // true if truncated by ContextWindowManager
  latencyMs: number
  tokensEstimate: number
}

type PolicyDecision =
  | { allowed: true;  requiresConfirmation: false }
  | { allowed: true;  requiresConfirmation: true; preview: ConfirmationPreview }
  | { allowed: false; reason: string }

// The ONLY port the orchestrator sees
interface IToolExecutor {
  getToolDefinitions(context: ToolContext): ToolDefinition[]
  execute(toolName: string, toolArgs: Record<string, unknown>,
          context: ToolContext): Promise<ToolResult>
}

interface IToolRegistry {
  register(def: ToolDefinition, handler: IToolHandler): void
  registerRemote(def: ToolDefinition, dispatcher: IRemoteDispatcher): void
  getDefinitions(context: ToolContext): ToolDefinition[]
  getHandler(toolName: string): IToolHandler | IRemoteDispatcher
}

interface IToolPolicyFilter {
  check(toolName: string, context: ToolContext): PolicyDecision
  // Gates: 1. marketplace gate  2. risk gate
}

interface IToolHook {
  beforeTool?(toolName: string, args: unknown, ctx: ToolContext): Promise<void>
  afterTool?(toolName: string, result: ToolResult, ctx: ToolContext): Promise<void>
}
// Hooks: ObservabilityHook (after), ProactiveSuggestionHook (after),
//        FeedbackCaptureHook (before+after, WRITE only → #15)
// Hooks never block execution — fire-and-forget

• ToolRegistry loads all tool definitions at Lambda startup with inputSchema validation
• IToolExecutor.getToolDefinitions() returns only tools available for user's marketplace and plan
• LLM selects correct tool >90% of the time via description_for_llm
• ToolPolicyFilter blocks all WRITE tools without confirmation — no bypass path
• Multiple read_only tools in same round execute via Promise.all (parallel)
• ObservabilityHook fires after every tool execution (fire-and-forget)
• Tool handler timeout of 10s prevents blocking the ReAct loop
• [Ph 1] SessionResultCache: same tool+args within a session returns cached result for READ/ANALYSIS tools. WRITE tools never cached. Cache scoped to session lifetime
• [Ph 2] FeedbackCaptureHook: beforeTool captures product metrics snapshot via Data Sync (#10) for WRITE tools; afterTool logs executed action to Feedback Loop (#15). Fire-and-forget — never blocks execution

• ToolRegistry carga todas las definiciones al arrancar Lambda con validacion de inputSchema
• IToolExecutor.getToolDefinitions() retorna solo tools disponibles para el marketplace y plan del usuario
• LLM selecciona la tool correcta >90% del tiempo via description_for_llm
• ToolPolicyFilter bloquea todas las tools WRITE sin confirmacion — sin bypass
• Multiples tools read_only en el mismo round se ejecutan via Promise.all (paralelo)
• ObservabilityHook se dispara tras cada ejecucion de tool (fire-and-forget)
• Timeout de handler de 10s previene bloquear el loop ReAct
• [Ph 1] SessionResultCache: misma tool+args dentro de una sesion retorna resultado cacheado para tools READ/ANALYSIS. Tools WRITE nunca se cachean. Cache con alcance de vida de la sesion
• [Ph 2] FeedbackCaptureHook: beforeTool captura snapshot de metricas del producto via Data Sync (#10) para tools WRITE; afterTool registra accion ejecutada en Feedback Loop (#15). Fire-and-forget — nunca bloquea ejecucion

36 tools · 4 categories (READ/ANALYSIS/SYSTEM/WRITE) · 5 phases · TypeScript · Internal use only (no REST)

interface SystemPromptContext {
  userProfile?: UserProfileSummary    // undefined until Phase 0.2
  criticalAlerts?: HealthAlert[]      // undefined until Phase 1.8
  writeCapable?: boolean              // false/undefined until Phase 3
}

interface UserProfileSummary {
  marketplaces: Marketplace[]
  categories: string[]
  declaredGoals: string[]
}

interface HealthAlert {
  domain: 'inventory' | 'advertising' | 'organic' | 'financial'
  level: 'Critique' | 'Delicate'
  product?: string
  metric: string
}

interface ComposedSystemPrompt {
  blocks: SystemPromptBlock[]
  estimatedTokens: number
  cachedBlockCount: number
}

interface SystemPromptBlock {
  text: string
  cache_control?: { type: 'ephemeral' }
}

// Token Budget (system prompt only):
// L1 Base: ~500 tokens (always)
// L2 Session: ~150-300 tokens (from Phase 0.2/1.8)
// L3 Execution: ~100-150 tokens (from Phase 3, write_capable only)
// Typical total: ~750-950 tokens | Hard cap: 1200 tokens
// Truncation priority: L3 first, then L2.alerts

// domain/common/services/ISystemPromptComposer.ts
interface ISystemPromptComposer {
  compose(context: SystemPromptContext): ComposedSystemPrompt
}

// Returns blocks[] (not string) so AnthropicClient can apply
// cache_control per block. Other clients (Vertex, OpenRouter)
// concatenate blocks as plain string — no functional change.

// ChatOptions extension (Phase 1.9, backward compatible):
interface ChatOptions {
  systemPrompt?: string | SystemPromptBlock[]
}

// Dependencies:
// SystemPromptComposer
// ├── IUserProfileRepository      (reads UserProfile, Phase 0.2)
// └── IBrandHealthContextService  (reads Critique alerts, Phase 1.8)
// The composer does NOT call the LLM. Does NOT know conversation
// history. Only composes text blocks from already-resolved data.

• System prompt assembled from blocks[] with per-block cache_control support
• L1 (base identity) always present at position 0, always with cache_control: ephemeral
• L2 injects UserProfile (marketplaces, categories, goals) when available
• L2 injects critical Critique alerts when active — Delicate-only sessions omit alert block
• L3 activates write confirmation guardrails only when writeCapable === true
• Total system prompt stays under 1200 tokens hard cap (typical ~750-950)
• AnthropicClient serializes blocks with cache_control; other clients concatenate to string

• System prompt ensamblado desde blocks[] con soporte de cache_control por bloque
• L1 (identidad base) siempre presente en posicion 0, siempre con cache_control: ephemeral
• L2 inyecta UserProfile (marketplaces, categorias, objetivos) cuando disponible
• L2 inyecta alertas criticas Critique cuando activas — sesiones solo-Delicate omiten bloque de alertas
• L3 activa guardrails de confirmacion de escritura solo cuando writeCapable === true
• System prompt total se mantiene bajo 1200 tokens limite duro (tipico ~750-950)
• AnthropicClient serializa bloques con cache_control; otros clientes concatenan a string

3 layers · L1 ~500t cached · L2 ~150-300t · L3 ~100-150t · 1200 hard cap · blocks[] for Anthropic prompt caching

interface IContextAssembler {
  assemble(request: ContextAssemblyRequest): Promise<AssembledContext>
}
interface ContextAssemblyRequest {
  userId: string; marketplace: Marketplace; query: string; conversationId: string
}
interface AssembledContext {
  kbChunks: KBChunkModel[]; brandHealthChunks: BrandHealthChunkType[]
  estimatedTokens: number; sourcesFailed: ContextSource[]
}
type ContextSource = 'kb' | 'brand_health'

interface IContextWindowManager {
  allocate(available: TokenBudget): ContextAllocation
  trim(context: AssembledContext, allocation: ContextAllocation): TrimmedContext
}
interface TokenBudget {
  modelContextWindow: number      // 200K
  systemPromptTokens: number; historyTokens: number
  toolDefinitionsTokens: number; expectedResponseTokens: number  // 4000
}
interface ContextAllocation {
  kbChunksTokens: number; brandHealthTokens: number; toolResultsTokens: number
}
interface TrimmedContext {
  kbChunks: KBChunkModel[]; brandHealthChunks: BrandHealthChunkType[]; truncated: boolean
}

// Internal invocation by AgentLoopOrchestrator — NO REST endpoint

// IContextAssembler (RagOrchestrator implements)
assemble(request: ContextAssemblyRequest): Promise<AssembledContext>

// IContextWindowManager (ContextWindowManager implements)
allocate(budget: TokenBudget): ContextAllocation
trim(context: AssembledContext, allocation: ContextAllocation): TrimmedContext

// Flow:
// 1. AgentLoopOrchestrator calls assemble() at start of each turn
// 2. assemble() embeds query once, runs KB + BrandHealth searches in parallel
// 3. allocate() calculates: available = 200K - system - history - tools - 4000
// 4. trim() fits assembled context within allocation, truncating if needed

• assemble() retrieves top-K KB chunks by semantic similarity from BigQuery kb_embeddings
• Brand health chunks filtered by detected intent (advertising, inventory, organic, financial)
• Single embedding call, two parallel searches via Promise.allSettled
• If KB or brand health fails, Coach responds with remaining context (graceful degradation invariant)
• ContextWindowManager calculates: available = 200K - system - history - tools - 4000
• Trimming priority: brand health first, then KB, then old tool results
• [Ph 2+] HyDE: when query is short/ambiguous, system generates hypothetical answer and uses it as search vector instead of the raw question. Hypothetical never shown to user. Activated selectively based on query characteristics

• assemble() recupera top-K chunks de KB por similitud semantica desde BigQuery kb_embeddings
• Chunks de brand health filtrados por intent detectado (advertising, inventory, organic, financial)
• Una sola llamada de embedding, dos busquedas paralelas via Promise.allSettled
• Si KB o brand health falla, Coach responde con contexto restante (invariante de degradacion graciosa)
• ContextWindowManager calcula: available = 200K - system - history - tools - 4000
• Prioridad de recorte: brand health primero, luego KB, luego tool results antiguos
• [Ph 2+] HyDE: cuando la query es corta/ambigua, el sistema genera una respuesta hipotetica y la usa como vector de busqueda en lugar de la pregunta cruda. La hipotetica nunca se muestra al usuario. Se activa selectivamente segun caracteristicas de la query

interface IProactiveSuggestionService {
  afterTool(input: SuggestionInput): Promise<Suggestion[]>           // Phase 2
  afterToolWithContext(input: SuggestionInput): Promise<Suggestion[]> // Phase 4
}

interface SuggestionInput {
  toolName: string
  result: ToolResult
  userId: string
  marketplace: Marketplace
  brandHealthSummary?: HealthSummary
  conversationContext: Message[]        // last N messages
  recentSuggestions: RecentSuggestion[] // for deduplication
}

interface Suggestion {
  message: string                       // conversational question, inviting tone
  priority: 'high' | 'normal'
  suggestionType: string                // dedup key: "stock", "pricing", "health", "reviews", etc.
  productId?: string                    // if applies to a specific product
}

interface RecentSuggestion {
  suggestionType: string
  productId?: string
  suggestedAt: string                   // ISO8601 — for 7-day window
}
// Stored in UserProfile.recentSuggestions[] (DynamoDB, last 30 entries)

// Internal invocation via HookLifecycle after_tool — NO REST endpoint

// Phase 2: lightweight LLM evaluation post-tool
afterTool(input: SuggestionInput): Promise<Suggestion[]>

// Phase 4: full session context + parallel to streaming
afterToolWithContext(input: SuggestionInput): Promise<Suggestion[]>

// Flow:
// 1. ToolExecutor completes tool → HookLifecycle.afterTool fires
// 2. ProactiveSuggestionService.afterTool() sends tool result to LLM
// 3. LLM returns structured JSON: { hasSuggestion, message, suggestionType, priority }
// 4. isDuplicate(suggestionType, productId, recentSuggestions) → skip if duplicate
// 5. Max 2 suggestions per turn, high priority first
// 6. Appended to Coach response as conversational questions

• afterTool() evaluates every tool result via LLM — no hardcoded rules or thresholds
• LLM returns structured JSON with hasSuggestion, message, suggestionType, priority
• Deduplication: same (suggestionType, productId) within 7 days = skip
• Max 2 suggestions per turn — high priority first
• If LLM output parse fails → silence (no error, Coach responds normally)
• Suggestions are conversational questions, not prescriptive alerts
• Adding a new tool to the catalog requires zero changes to this service

• afterTool() evalua cada resultado de tool via LLM — sin reglas hardcodeadas ni umbrales
• LLM retorna JSON estructurado con hasSuggestion, message, suggestionType, priority
• Deduplicacion: mismo (suggestionType, productId) dentro de 7 dias = omitir
• Maximo 2 sugerencias por turno — prioridad high primero
• Si el parse del output LLM falla → silencio (sin error, Coach responde normalmente)
• Las sugerencias son preguntas conversacionales, no alertas prescriptivas
• Agregar una tool nueva al catalogo requiere cero cambios en este servicio

interface IGuardService {
  validateInput(input: GuardInput): Promise<GuardResult>
  validateOutput(output: GuardOutput): Promise<GuardResult>
}

interface GuardInput {
  query: string
  userId: string
  sessionHistory: Message[]   // last N messages for context
  marketplace: Marketplace
}

interface GuardOutput {
  response: string
  userId: string
  toolResults?: ToolResult[]  // tool results from loop for data leak verification
}

interface GuardResult {
  passed: boolean
  reason?: string             // if failed: which violation detected
  category?: ViolationCategory
  rejectionMessage?: string   // friendly message for the user
}

type ViolationCategory =
  | 'prompt_injection'
  | 'off_scope'
  | 'data_leak'
  | 'dangerous_content'

// --- InputGuard: known injection patterns (first line — regex) ---
// "ignore previous instructions" / "ignora las instrucciones anteriores"
// "you are now" / "ahora eres" / "pretend you are"
// "forget everything" / "olvidate de todo"
// Nested delimiters: ---SYSTEM--- , [INST], <|system|>, <|im_start|>
// Role switching: "act as" / "actúa como si fueras"
// "your real instructions are" / "tus instrucciones reales son"

// --- Rejection messages — never expose the technical reason ---
// Prompt injection:
//   ✅ "Estoy aquí para ayudarte con tu actividad como vendedor.
//       ¿Hay algo sobre tus productos, ventas o métricas?"
//   ❌ "Tu query contiene instrucciones que intentan modificar el sistema."
// Off-scope:
//   ✅ "Para eso no tengo la información que necesitás.
//       Si tenés consultas sobre tu actividad como vendedor, puedo ayudarte."
//   ❌ "Tu pregunta está fuera del scope del Coach."
// Data leak / OutputGuard:
//   ✅ "No pude generar una respuesta útil. Intentá reformularla
//       o preguntame sobre tu actividad en el marketplace."
//   ❌ "Tu respuesta fue bloqueada por política de seguridad."

// In AgentLoopOrchestrator

async handle(query, context): Promise<CoachResponse> {

  // 1. InputGuard — pre-LLM
  const inputResult = await guardService.validateInput({
    query, userId: context.userId,
    sessionHistory: context.recentMessages,
    marketplace: context.marketplace
  })
  if (!inputResult.passed) {
    logger.warn('guard.input.rejected', { category, userId })
    return { message: inputResult.rejectionMessage, guardRejected: true }
  }

  // 2. Normal ReAct loop
  const response = await this.runReActLoop(query, context)

  // 3. OutputGuard — post-LLM
  const outputResult = await guardService.validateOutput({
    response: response.message, userId: context.userId,
    toolResults: response.toolResults
  })
  if (!outputResult.passed) {
    logger.error('guard.output.rejected', { category, userId })
    if (outputResult.category === 'data_leak')
      await alertService.critical('data_leak_detected', { userId })
    return { message: outputResult.rejectionMessage, guardRejected: true }
  }

  return response
}

• [Ph 1] InputGuard detects known prompt injection patterns via regex (~5-10ms, no LLM cost)
• [Ph 1] InputGuard detects off-scope queries and returns friendly redirection message
• [Ph 1] Rejection messages never expose the technical reason — attacker cannot determine why they were rejected
• [Ph 1] If InputGuard fails internally, query passes through (graceful degradation invariant)
• [Ph 2] LLMGuardChecker activates only when pattern matching has low confidence. If classifier confidence < 0.7, query passes (doubt favors the user)
• [Ph 3] OutputGuard detects data leak: response mentions userId that is not the current user's
• [Ph 3] Data leak triggers critical CloudWatch alert (not just log). OutputGuard detects dangerous content via pattern matching
• [Ph 3] If OutputGuard fails internally, response passes through (graceful degradation invariant)

• [Ph 1] InputGuard detecta patrones conocidos de prompt injection via regex (~5-10ms, sin costo LLM)
• [Ph 1] InputGuard detecta queries fuera de scope y retorna mensaje amable de redireccion
• [Ph 1] Mensajes de rechazo nunca exponen el motivo técnico — atacante no puede determinar por que fue rechazado
• [Ph 1] Si InputGuard falla internamente, el query pasa (invariante de degradacion graciosa)
• [Ph 2] LLMGuardChecker se activa solo cuando pattern matching tiene baja confianza. Si confianza del clasificador < 0.7, query pasa (la duda favorece al usuario)
• [Ph 3] OutputGuard detecta data leak: respuesta menciona userId que no es del usuario actual
• [Ph 3] Data leak dispara alerta critica de CloudWatch (no solo log). OutputGuard detecta contenido peligroso via pattern matching
• [Ph 3] Si OutputGuard falla internamente, la respuesta pasa (invariante de degradacion graciosa)

Security layer · Not auth · 2 validation points · Graceful degradation invariant · 4 violation categories · 3 phases

Client (seller — Memberstack ID)
  ↓ 1:N
AgentClient (conversation session — persists between messages)
  ↓ 1:N
AgentExecution (one execution = one user message)
  ↓ 1:N             ↓ 1:N              ↓ 1:N
AgentLog[]       AgentCost[]      ExecutionContextLink[]
(ordered event   (one per charge        ↓ N:1
 timeline)        type)           ContextSnapshot[]
                                  (kb_chunks, brand_health)

# CoachTrace — what a single execution contains
CoachTrace
│── Identity
│   │── execution_id       UUID
│   │── user_id            Memberstack ID
│   │── conversation_id    DynamoDB conversation
│   └── marketplace        MercadoLibre / Amazon / etc.
│
│── Lifecycle
│   │── status             pending → running → done | error
│   │── started_at / ended_at
│   └── duration_ms        End-to-end latency
│
│── Pipeline Steps (AgentLog[])
│   │── embedding          latency, text size
│   │── vector_search      latency, chunks found, top score
│   │── brand_health       intent detected, metrics queried
│   │── llm_call           model, tokens in/out, latency
│   └── agent_error        error type, message, stack
│
│── Costs (AgentCost[])
│   │── EMBEDDING          1 credit per Vertex AI call
│   │── VECTOR_SEARCH      1 credit per BigQuery search
│   │── BRAND_HEALTH       1 credit per brand health query
│   └── TOKENS             CEIL((input+output)/1000) credits
│
└── Context (ContextSnapshot[])
    │── kb_chunks          Exact chunks the LLM saw
    └── brand_health       Brand health metrics injected

# Credits are NEVER calculated in the application —
# trigger trg_calculate_agent_credits computes on INSERT

│                  │ DynamoDB              │ PostgreSQL                       │
│ What it stores   │ ConversationTrace     │ AgentExecution+Logs+Costs+Snaps  │
│ Granularity      │ Aggregated pipeline   │ Per-step with latency+params     │
│ Access           │ Same table as chat    │ Separate DB, optional            │
│ TTL              │ 90 days (auto-delete) │ Configurable retention           │
│ Read latency     │ <10ms (hot store)     │ SQL ad-hoc queries               │
│ Activation       │ Always on             │ ENABLE_AGENT_TRACKING=true       │

• Each user message generates a ConversationTrace in DynamoDB and (if enabled) a full AgentExecution in PostgreSQL
• AgentExecution contains at least one AgentLog of type rag_metrics with pipeline latencies
• AgentCost reflects exactly the charge types used in that execution (EMBEDDING, VECTOR_SEARCH, BRAND_HEALTH, TOKENS)
• ContextSnapshots linked to the execution contain the exact chunks sent to the LLM
• If PostgreSQL is unavailable, the Coach responds normally — tracking never blocks the flow
• Failed executions have status = 'error' and error_message populated
• Credits in clients and agents_clients stay automatically synchronized by database triggers
• ConversationTraces in DynamoDB auto-expire at 90 days (TTL)

• Cada mensaje del usuario genera un ConversationTrace en DynamoDB y (si esta habilitado) un AgentExecution completo en PostgreSQL
• AgentExecution contiene al menos un AgentLog de tipo rag_metrics con latencias del pipeline
• AgentCost refleja exactamente los tipos de cargo usados en esa ejecucion (EMBEDDING, VECTOR_SEARCH, BRAND_HEALTH, TOKENS)
• Los ContextSnapshot vinculados a la ejecucion contienen los chunks exactos enviados al LLM
• Si PostgreSQL no esta disponible, el Coach responde normalmente — el tracking nunca bloquea el flujo
• Las ejecuciones con error tienen status = 'error' y error_message poblado
• Los creditos en clients y agents_clients se mantienen sincronizados automaticamente por triggers de base de datos
• Los ConversationTrace en DynamoDB expiran solos a los 90 dias (TTL)

DynamoDB TTL: 90 days · PostgreSQL: optional (ENABLE_AGENT_TRACKING) · Credits: DB triggers, never app code · Charge types: EMBEDDING(1) + VECTOR_SEARCH(1) + BRAND_HEALTH(1) + TOKENS(CEIL(in+out/1000))DynamoDB TTL: 90 dias · PostgreSQL: opcional (ENABLE_AGENT_TRACKING) · Creditos: triggers de BD, nunca codigo de app · Tipos de cargo: EMBEDDING(1) + VECTOR_SEARCH(1) + BRAND_HEALTH(1) + TOKENS(CEIL(in+out/1000))

-- Dataset: knowledge_base | Table: kb_embeddings
id            STRING    NOT NULL   -- "KB-financial-NP__chunk_0"
document_id   STRING    NOT NULL   -- "KB-financial-NP"
namespace     STRING    NOT NULL   -- "financial"
doc_type      STRING    NOT NULL   -- "metric"
title         STRING               -- "Net Profit (NP)"
chunk_index   INT64               -- 0
source        STRING               -- Relative path to .md
tags          ARRAY<STRING>        -- ["financial", "metric"]
text          STRING               -- Chunk content (≤ 1000 chars)
embedding     ARRAY<FLOAT64>       -- Vertex AI text-embedding-004 (1024 dims)
created_at    TIMESTAMP NOT NULL
updated_at    TIMESTAMP NOT NULL
language      STRING    NOT NULL   -- "es"

-- YAML Front-Matter (required fields):
-- id, namespace, type, title, version (SemVer), last_reviewed (ISO date),
-- language, tags, metric_refs
-- Conditional: condition+severity+action_hint (card), formula+unit+thresholds (metric),
--   source (learning), metric_refs required (health)

// Consumed by RagOrchestrator in core-intelligence-conversation-api
RAGEmbeddingService
  └── VertexEmbeddingClient.embed(userQuery)
        → ARRAY<FLOAT64> [1024 dims, text-embedding-004]

RAGVectorSearchService
  └── BigQuery COSINE_DISTANCE against kb_embeddings
        → top-K chunks (KBChunkModel[])

RAGChunkRankingService.rank(chunks, query) → top-5 reranked
RAGLLMService.generateAnswer(query, chunks, options)
  → injection as <knowledge_base> context in the LLM prompt

// Embedding coherence: coach-api MUST use the same model
// (text-embedding-004) as the KB indexer. Changing the model
// requires re-indexing all 2,875 documents.

• 2,875 documents indexed and searchable in BigQuery kb_embeddings
• Go pipeline validates front-matter: required fields, unique IDs, metric_refs against 23-metric catalog
• Semantic search returns relevant chunks in <500ms via COSINE_DISTANCE
• Freshness report alerts on docs exceeding namespace thresholds (60/90/180 days)
• Namespace filter in RAGVectorSearchService scopes search by intent
• Re-indexing marks old chunks as stale when document is updated (is_current flag)
• LLM correctly cites KB information in responses (human-verifiable)
• [Ph 1] Contextual Retrieval: each chunk includes LLM-generated summary of its role in the full document before embedding. Runs once at indexing/re-indexing time, not per query. Search recall improves measurably vs baseline

• 2,875 documentos indexados y buscables en BigQuery kb_embeddings
• Pipeline Go valida front-matter: campos requeridos, IDs unicos, metric_refs contra catalogo de 23 metricas
• Busqueda semantica retorna chunks relevantes en <500ms via COSINE_DISTANCE
• Reporte de frescura alerta sobre docs que exceden umbrales por namespace (60/90/180 dias)
• Filtro de namespace en RAGVectorSearchService limita busqueda por intent
• Re-indexacion marca chunks viejos como stale cuando se actualiza el documento (flag is_current)
• LLM cita informacion del KB correctamente en respuestas (verificable por humano)
• [Ph 1] Contextual Retrieval: cada chunk incluye resumen generado por LLM de su rol en el documento completo antes de embeber. Se ejecuta una vez en indexacion/re-indexacion, no por query. El recall de busqueda mejora mediblemente vs baseline

2,875 docs · 11 namespaces · 23 metrics · Go 1.24.0 · Vertex AI 004 (1024 dims) · BigQuery · Automatic context (not a tool)

# ═══ COMPLETE DATA PIPELINE (Medallion — GCS) ═══

# BRONZE — Raw marketplace responses (per user, per marketplace)
# gs://shopilot-data/bronze/{marketplace}/{user_id}/{date}.parquet
# Retention: persistent (Coldline after 90d)

# SILVER — Normalized + validated (unified schemas)
products.parquet:
├── user_id, product_id, marketplace, title, price, stock
├── status, visits_30d, sales_30d, conversion_30d
├── health_score: float (0-100), last_updated, synced_at

# GOLD — Pre-computed aggregates + Brand Health
daily_summary.parquet:
├── user_id, date, marketplace
├── total/active/paused_products, total_orders, total_revenue
├── total_visits, avg_conversion_rate, out_of_stock_count
├── new_questions_count, competitor_price_changes

brand_health.parquet:    # Rules from legacy (TBD)
├── user_id, marketplace, calculated_at
├── overall_score: float (0-100)
├── dimension_scores: { products, pricing, stock, reputation, ... }
├── alerts: [{ type, severity, message }]

# ═══ FAST DATA LAYER (FastAPI reads from Parquet — no Redis) ═══

# FastAPI reads directly from GCS Parquet files via pyarrow.
# No intermediate cache. Data freshness = last Complete Data sync cycle.
# Pre-write snapshot: gs://shopilot-data/bronze/snapshots/{tool}/{user_id}/{ts}.parquet

# Tool contract (#3 Tool Registry):
#   READ  : get_product, get_product_metrics, get_orders,
#            get_buyer_questions, get_product_reviews,
#            get_category_requirements, get_campaigns,
#            get_campaign_metrics, get_store, get_store_metrics
#   ANALYSIS: get_product_fee_estimate

# Data Lake Structure (GCS):
# gs://shopilot-data/
# ├── bronze/          Raw (batch) + pre-write snapshots
# │   └── snapshots/   Pre-write state captures (one Parquet per tool+ts)
# ├── silver/          Normalized unified
# ├── gold/            Brand Health + aggregations
# └── embeddings/      Generated for Cerebro KB (#9)

# Data API (FastAPI on Cloud Run) — serves ALL layers via pyarrow Parquet reads:

# Fast Data (reads from Bronze/Silver Parquet — contract per #3 Tool Registry):
# GET /data/{user_id}/fast/get_product?sku=X&marketplace=Y
# GET /data/{user_id}/fast/get_product_metrics?sku=X&marketplace=Y
# GET /data/{user_id}/fast/get_orders?from=DATE&to=DATE
# GET /data/{user_id}/fast/get_buyer_questions?sku=X
# GET /data/{user_id}/fast/get_product_reviews?sku=X
# GET /data/{user_id}/fast/get_category_requirements?category_id=X
# GET /data/{user_id}/fast/get_campaigns?marketplace=Y
# GET /data/{user_id}/fast/get_campaign_metrics?campaign_id=X
# GET /data/{user_id}/fast/get_store?marketplace=Y
# GET /data/{user_id}/fast/get_store_metrics?marketplace=Y
# GET /data/{user_id}/fast/get_product_fee_estimate?sku=X&price=N  (ANALYSIS)
# GET /data/{user_id}/snapshot/{tool}/{ts}   -> pre-write snapshot from GCS

# Silver layer (normalized):
# GET /data/{user_id}/products?status=active&marketplace=X
# GET /data/{user_id}/orders?from=DATE&to=DATE

# Gold layer (aggregated):
# GET /data/{user_id}/summary?days=30
# GET /data/{user_id}/brand-health                     -> Brand Health report
# GET /data/{user_id}/metrics/daily
# GET /data/{user_id}/anomalies

# Embedding triggers:
# POST /data/{user_id}/embed/fast    -> Bronze fast data -> Cerebro KB
# POST /data/{user_id}/embed/health  -> Gold Brand Health -> Cerebro KB

# Airflow DAGs (Complete Data — configurable period):
# meli_sync:         configurable (default: 1h active, 6h all)
# amazon_sync:       configurable (default: 1h active, 6h all)
# shopify_sync:      configurable (default: 1h active, 6h all)
# brand_health:      configurable (default: 1h post-sync)
# embedding_sync:    configurable (default: 1h post brand_health)
# snapshot_cleanup:  daily (removes pre-write snapshots older than 24h)
# openmetadata_sync: configurable (default: 6h, lineage + dictionaries)

• [Complete] MeLi + Amazon + Shopify DAGs run every hour without errors for 50 users
• [Complete] Brand Health Gold report computes correctly (legacy rules migrated)
• [Fast] On-demand read for any Marketplace Provider Tool responds in <500ms
• [Fast] Pre-write snapshot cached before every write Tool execution
• [Fast] TTL cleanup removes expired fast data without manual intervention
• [Both] Open Metadata lineage and data dictionaries generated for both pipelines
• [Both] Embedding sub-pipelines feed Cerebro KB (#9): Bronze fast → real-time, Gold → Brand Health
• [API] Data API serves Bronze, Silver, and Gold layers. <200ms p95 for Gold queries
• [Auth] Token management via Marketplace Provider (#12) — local Auth Vault scheme replaced

• [Completo] DAGs MeLi + Amazon + Shopify corren cada hora sin errores para 50 usuarios
• [Completo] Reporte Brand Health Gold se calcula correctamente (reglas legacy migradas)
• [Rapido] Lectura on-demand para cualquier Tool del Marketplace Provider responde en <500ms
• [Rapido] Snapshot pre-escritura cacheado antes de cada ejecucion de Tool de escritura
• [Rapido] Limpieza TTL elimina datos rapidos expirados sin intervencion manual
• [Ambos] Linaje y diccionarios Open Metadata generados para ambos pipelines
• [Ambos] Sub-pipelines de embeddings alimentan Cerebro KB (#9): Bronze rapido → tiempo real, Gold → Brand Health
• [API] Data API sirve capas Bronze, Silver y Gold. <200ms p95 para queries Gold
• [Auth] Gestion de tokens via Marketplace Provider (#12) — esquema local Auth Vault reemplazado

Complete: 1h sync · Fast: <500ms on-demand, TTL cleanup · API: all 3 layers, <200ms Gold · Embeddings: Bronze+Gold → KB