Especificación

Cómo funciona, en lenguaje sencilloCopiar enlace

Una aplicación Next.js 16 se ejecuta en Google Cloud Run en https://wovain.com. Sirve el sitio web, una API y un servidor MCP al que se conecta ChatGPT. El sitio web y ChatGPT llaman a los mismos procedimientos de la API, así que siempre hacen lo mismo. Una base de datos PostgreSQL en Cloud SQL recuerda usuarios, conexiones, ejecuciones, ideas, diseños, productos y campañas.

Cuando el vendedor pide ideas, la API pregunta a Qloo qué temas aman los fans de la semilla y pregunta a Tavily qué hay en las noticias y en los marketplaces dentro de esos temas. Nemotron, alojado en Nebius Token Factory, redacta el brief del diseño y la ficha; fal dibuja el arte; Nemotron lo evalúa y el código vuelve a comprobar el tamaño de impresión. Al aprobar, la API crea un producto de Fourthwall y, más tarde, una campaña de Meta, siempre en pausa. La documentación vive aparte en https://docs.wovain.com.

Por qué no algo más elaborado: una aplicación y un único conjunto de procedimientos mantienen pequeña la prueba de concepto e idénticas las dos superficies.

El recorrido principal a través del sistemaCopiar enlace

Ref. PRD: prd.md > The Core Journey.

1. El vendedor inicia sesión → Better Auth (/api/auth) crea una sesión en PostgreSQL. ChatGPT, en cambio, inicia sesión mediante el servidor OAuth de Better Auth y llama a POST /api/mcp con un token de acceso.
2. El vendedor introduce una semilla → la página o la herramienta MCP research_trends llama a ideas.research → researchIdeas en packages/api/src/flow/ideas.ts usa Qloo y Tavily de packages/core → las ideas ordenadas se guardan.
3. El vendedor elige una idea → designs.generate (generateDesign) → brief de Nemotron (draftBrief), arte de fal (createArtist), precio (priceFor), juez Nemotron (judgeDesign) → el diseño se guarda como pending_approval.
4. El vendedor aprueba → designs.approve (decideDesign).
5. products.create (createDesignProduct) llama a Fourthwall con la conexión sellada del vendedor; products.publish lo hace público.
6. campaigns.create (createProductCampaign) → texto publicitario de Nemotron (writeAdCopy) → stagePausedCampaign crea en Meta la campaña, el conjunto de anuncios y los anuncios en pausa.
7. runs.start (startRun) encadena estos pasos; con autopilot: true, Nemotron elige la idea (pickIdea) y revisa el diseño (reviewDesign).

Pila tecnológicaCopiar enlace

Dónde se ejecuta y cómo probarloCopiar enlace

• Producción: Cloud Run en https://wovain.com; docs en https://docs.wovain.com.
• ChatGPT: añade un conector con la URL https://mcp.wovain.com/api/mcp. El descubrimiento OAuth se sirve en /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server; el vendedor inicia sesión y concede acceso en la página de consentimiento.
• En local: Node.js (consulta .nvmrc), pnpm y Docker para PostgreSQL.

pnpm install
docker compose up -d
pnpm run dev

Las claves van en los valores de apps/web/.env.schema: BETTER_AUTH_SECRET, BETTER_AUTH_URL, DATABASE_URL, TOKEN_ENCRYPTION_KEY, NEBIUS_API_KEY, QLOO_API_KEY, TAVILY_API_KEY, FAL_KEY, META_APP_ID, META_APP_SECRET. Nunca hagas commit de valores reales.

El envío requiere un vídeo de demostración corto y el repositorio público; el despliegue es adicional. URL del vídeo: por añadir. URL del repositorio: por añadir.

Aspecto y tonoCopiar enlace

Cálido, sencillo, números primero; voz de entrenador. Temas claro y oscuro a partir de los tokens de shadcn; una acción principal por tarjeta. Funciona en ancho de móvil.

ComponentesCopiar enlace

Aplicación web (apps/web)Copiar enlace

Páginas (login, dashboard, consent), /api/rpc, /api/auth, /api/mcp, /api/connections/[provider]/start y callback, y las rutas OAuth .well-known. src/services.ts construye db, auth y core. Ref. PRD: prd.md > Screens and Layout.

API (packages/api)Copiar enlace

appRouter en src/routers/index.ts lista ideas, designs, products, campaigns, runs y connections; la lógica de cada paso está en src/flow/*. publicProcedure añade el registro de evlog; protectedProcedure exige una sesión o un usuario MCP. Ref. PRD: prd.md > Features and Behavior.

Servidor MCP (packages/api/src/mcp.ts)Copiar enlace

createMcpServer registra list_connections, research_trends, generate_design, approve_design, reject_design, create_product, publish_product, create_campaign, start_run y get_run, cada uno llamando al mismo router. Ref. PRD: prd.md > Screens and Layout.

Core (packages/core)Copiar enlace

createCore conecta Qloo (qloo.ts), Tavily (trends.ts), Nemotron (nemotron.ts), fal (fal.ts), precios (pricing.ts), el juez (design.ts), el autopilot (autopilot.ts), anuncios (ads.ts), Fourthwall (fourthwall.ts), el cliente OAuth de origen (upstream.ts) y el sellado de tokens (sealing.ts). Ref. PRD: prd.md > Features and Behavior.

Autenticación (packages/auth)Copiar enlace

createAuth construye Better Auth sobre la base de datos de Drizzle; mcpResource es la URL a la que están ligados los tokens de acceso. Ref. PRD: prd.md > States and Boundaries.

Base de datos (packages/db)Copiar enlace

Tablas de Better Auth en src/schema/auth.ts; tablas del vendedor en src/schema/seller.ts. Ref. PRD: prd.md > States and Boundaries.

Flujos de DuoCopiar enlace

Flujos de autorreparación, explorador y desarrollo alrededor del repositorio; definiciones en docs/flows.md. Ref. PRD: prd.md > Features and Behavior (After deploy).

Modelo de datosCopiar enlace

Las migraciones se generan con pnpm run db:generate.

Estructura de archivosCopiar enlace

wovain/
├── apps/
│   ├── web/              # Next.js 16: pages, /api/rpc, /api/auth, /api/mcp
│   └── fumadocs/         # docs site, content/docs in en, fr, es
├── packages/
│   ├── api/              # oRPC routers, flow steps, MCP server
│   ├── auth/             # Better Auth configuration
│   ├── core/             # providers, pricing, judge, autopilot
│   ├── db/               # Drizzle schema, relations, client, migrations
│   ├── ui/               # shared shadcn/ui components
│   └── config/           # shared tsconfig
├── docs/                 # scope, PRD, spec, app map, flows
├── infra/                # deployment
└── AGENTS.md

Servicios externos y dependenciasCopiar enlace

Modos de fallo importantesCopiar enlace

• Falta la clave de un proveedor → el paso falla con NOT_CONFIGURED nombrando la variable; los demás pasos siguen funcionando.
• El vendedor no ha conectado Fourthwall o Meta → la herramienta MCP devuelve el error, el motivo, la solución y el enlace para conectar.
• Un paso falla en una ejecución → la ejecución queda failed con su paso y su error.

Qué se simplificó y por quéCopiar enlace

• Una sola aplicación en lugar de servicios separados de API y MCP — un único conjunto de procedimientos mantiene coherentes las superficies.
• Resultados de herramientas en JSON en lugar de widgets de ChatGPT — menos código; los widgets pueden llegar después.
• Campañas en pausa en lugar de lanzamientos en vivo — elimina el riesgo de gasto involuntario.
• Solo camiseta — un producto basta para probar el bucle.
• Sin optimizador — primero hacen falta datos reales de gasto.

Decisiones y asuntos abiertosCopiar enlace

• El código pone las salvaguardas y Nemotron decide dentro de ellas — elegido para que un error del modelo no pueda publicar un diseño sin comprobar ni gastar dinero; el coste es corregir a veces una buena respuesta del modelo.
• Qloo antes que Tavily — el gusto acota la búsqueda de noticias; el coste es depender de la cobertura de Qloo para la semilla.
• Resuelto: ChatGPT se conecta a https://mcp.wovain.com/api/mcp; el plugin MCP de Better Auth es el servidor OAuth y requireMcpAuth verifica cada token.
• Abierto: alcance de la revisión de la app de Meta para crear campañas desde el servidor.
• Concepto poco familiar tratado: la diferencia entre un modelo que sugiere un valor y un código que lo garantiza. Aclarado con la regla de que las comprobaciones decididas por el código (tamaño de impresión, precio mínimo, rango de presupuesto) no son salida del modelo, demostrado por las pruebas de packages/core/src/design.test.ts.