🏗️ Arquitecto de Software · CULTIVA IA

Diseño de Sistema v2.0 — CULTIVA IA Platform

Arquitectura escalable para soportar el crecimiento de 150 a 5.000 usuarios en 6 meses, con procesamiento asíncrono de IA, sistema de créditos multi-tenant y caché semántica.

Arquitecto Senior Software Architect
Fecha 18 Jun 2026
Estado ✓ Diseño Aprobado
ADRs 6 decisiones
Timeline 8 semanas
Presupuesto infra ~320€/mes
⚠️
Estado Actual — Problemas Identificados
Crítico

Timeouts en Vercel Edge

Las API routes tienen límite de 30s. Claude API puede tardar 45-90s en generaciones largas. Causa: arquitectura síncrona sin cola de trabajos.

Crítico

Sin Rate Limiting

Un usuario puede hacer 1.000 llamadas en un día sin restricción. Sin sistema de créditos, el coste de Claude API escala sin control directo.

Alto

Latencia 3-8s promedio

Sin caché semántica, prompts idénticos o similares consumen tokens de Claude en cada llamada. El 40% de las peticiones son variaciones de los mismos prompts.

Alto

Arquitectura mono-tenant

No hay separación de configuración entre agencias. Imposible ofrecer subdominio propio, prompts customizados o branding white-label por cliente.

Medio

Sin historial semántico

Las generaciones no se guardan con embeddings. Sin búsqueda semántica sobre el historial del usuario para reutilizar outputs similares.

Medio

Monolito Next.js acoplado

Lógica de negocio mezclada con componentes de UI. Difícil de escalar horizontalmente o desplegar servicios de forma independiente.

🏗️
Arquitectura Propuesta — Sistema v2.0
Capa Cliente
Next.js 15 App (Vercel)
Multi-tenant Subdomain Router
Tenant Config Provider
Real-time Dashboard (Supabase Subs)
API Gateway + Auth
Next.js API Routes (validación + auth)
Rate Limiter (Upstash Redis)
Credits Middleware
Webhook Dispatcher
Capa de Servicios
Job Queue (Upstash QStash)
AI Worker Service (Railway)
Semantic Cache Service
Credits Ledger Service
Tenant Config Service
Capa de Datos
Supabase PostgreSQL (core data)
pgvector (embeddings historial)
Upstash Redis (caché + rate limit)
Supabase Storage (outputs grandes)
Capa IA
Claude API (Anthropic)
text-embedding-3-small (OpenAI)
Semantic Similarity Cache (cosine 0.92)
Prompt Template Engine
📋
Architecture Decision Records (ADRs)
ADR-001 Cola de trabajos asíncrona con Upstash QStash Aceptado

Las generaciones con IA pueden tardar entre 15-90 segundos. Vercel Edge Functions tienen un límite de 30s que causa timeouts frecuentes. Se necesita desacoplar la petición HTTP del trabajo de IA.

✓ Ventajas
  • Sin timeouts: el usuario recibe un job_id inmediatamente
  • Reintentos automáticos con backoff exponencial
  • QStash es serverless, sin infra que gestionar
  • Coste: ~5€/mes para 500K mensajes
✗ Desventajas
  • UX más compleja: polling o websocket para notificar resultado
  • Latencia añadida de ~2s por el overhead de la cola
  • Necesita worker persistente en Railway
ADR-002 Caché semántica con pgvector + similitud coseno 0.92 Aceptado

El 40% de las peticiones son variaciones semánticamente similares del mismo prompt. Se pueden cachear outputs y reutilizarlos cuando la similitud supera el umbral, ahorrando tokens y latencia.

✓ Ventajas
  • Ahorro estimado 35-40% en costes de Claude API
  • Respuesta instantánea para cache hits (~50ms vs 5s)
  • pgvector ya incluido en Supabase, sin coste adicional
✗ Desventajas
  • Riesgo de "false positives" — outputs incorrectos para prompts diferentes
  • Umbral 0.92 conservador; ajustar según feedback de usuarios
  • Coste de embedding por petición (~0.00002$/1K tokens)
ADR-003 Sistema de créditos con ledger inmutable en PostgreSQL Aceptado

Se necesita controlar el consumo por usuario según su plan (Free/Pro/Agency). Un sistema de créditos con transacciones inmutables permite auditoría, rollback y billing preciso.

✓ Ventajas
  • Audit trail completo de cada consumo
  • Transacciones ACID: no doble descuento
  • Base para billing por uso si se monetiza más
✗ Desventajas
  • Más complejo que un simple counter en Redis
  • Requiere migración de BD y lógica de negocio adicional
ADR-004 Multi-tenancy por Row Level Security (RLS) + subdomain config Aceptado

Las agencias cliente necesitan su propio subdominio, configuración de prompts y branding. Se puede implementar con RLS de Supabase + middleware de Vercel que detecta el tenant por hostname.

✓ Ventajas
  • Datos completamente aislados por tenant a nivel DB
  • No necesita BD separada por cliente — más barato
  • Middleware Vercel nativo, sin coste adicional
✗ Desventajas
  • Un bug en RLS puede exponer datos entre tenants
  • Testing de RLS policies más complejo
  • No hay aislamiento de rendimiento entre tenants
📈
Plan de Escalabilidad — por Tiers de Usuarios
Tier Usuarios activos Arquitectura Infra clave Coste est./mes
● Ahora 150 Monolito Next.js + Supabase direct Vercel Hobby Supabase Free ~20€
● v2.0 (T+8w) 5.000 Next.js + QStash Queue + Redis Cache + pgvector Vercel Pro Railway Worker Upstash Redis ~320€
● v3.0 (6m) 50.000 + Redis Cluster + CDN assets + Read replicas Supabase Pro Cloudflare R2 Redis Cluster ~900€
● v4.0 (12m) 500.000+ Microservicios + CQRS + Event sourcing + Multi-region GCP/AWS Kafka K8s ~8.000€
💰
Desglose de Costes — Arquitectura v2.0 (5.000 usuarios)
Servicio Plan Propósito €/mes
VercelProFrontend + API routes + Edge middleware20€
SupabaseProPostgreSQL + Auth + pgvector + Storage25€
RailwayStarterAI Worker (Node.js/Python) para procesar cola15€
Upstash RedisPay-as-you-goRate limiting + caché rápida + sesiones20€
Upstash QStashPay-as-you-goCola de mensajes para jobs asíncronos (500K msgs)10€
Claude API (Anthropic)Generaciones IA (con ahorro del 35% por caché semántica)180€
OpenAI Embeddingstext-embedding-3-small para caché semántica8€
CloudflareFreeDNS + subdominios multi-tenant0€
TOTAL estimado (5.000 usuarios activos)278€
🗓️
Plan de Migración — 8 Semanas
W1

Fundamentos: Credits Ledger + Rate Limiting

Migración de BD con tabla credits_ledger. Middleware de rate limiting con Upstash Redis. Tests unitarios de toda la lógica de créditos.

DB Migration Upstash Redis Tests
W2

Cola de trabajos asíncrona con QStash

Configurar Upstash QStash. Crear AI Worker en Railway. Refactorizar API routes para publicar jobs en lugar de llamar Claude directamente.

QStash Railway Worker API Refactor
W3

Real-time: polling → Supabase Subscriptions

Eliminar polling de frontend. Implementar canal Supabase Realtime para notificar al cliente cuando el job termina. UX del spinner → resultado.

Supabase Realtime UX Upgrade
W4

Caché semántica con pgvector

Activar extensión pgvector en Supabase. Implementar pipeline: embed prompt → buscar similares → hit/miss → guardar resultado con embedding.

pgvector Semantic Cache Cost Savings
W5

Multi-tenancy: subdominio + RLS + config por tenant

Middleware Vercel para detección de tenant por hostname. Tabla tenant_config con branding, prompts y planes. RLS policies en todas las tablas.

Multi-tenant Vercel Middleware RLS
W6-8

QA, monitoring, webhooks y go-live

Panel de métricas en tiempo real para admins. Webhooks de notificación para clientes. Load testing con k6 (objetivo: 500 req/s). Migración de datos y cutover.

Load Testing Monitoring Webhooks
System Design Checklist — Estado v2.0
User stories documentadas (12 historias)
Contratos API definidos (OpenAPI 3.0)
Modelos de datos especificados
Objetivos de rendimiento: p95 < 200ms (sin IA), p95 < 8s (con IA)
Disponibilidad: 99.5% uptime (SLA Vercel/Supabase Pro)
Diagrama de arquitectura creado
Flujo de datos documentado (happy path + error paths)
6 ADRs con trade-offs documentados
Estrategia de despliegue definida
!
Tests de carga con k6 (pendiente W7)
!
Plan de backup y recovery documentado
!
Runbook de rollback en caso de fallo
🚩
Anti-patrones Detectados en el Sistema Actual
God Object

El componente AIGenerator.tsx hace fetch, maneja estado y renderiza. Separar en hook + presenter.

Tight Coupling

Las API routes importan directamente el SDK de Anthropic. Necesita una capa de abstracción AIProvider.

Premature Optimization

Cache de Redis implementada con TTL de 1 hora sin datos de qué se cachea realmente. Medir primero.

Magic

Los prompts están hardcodeados en 12 archivos diferentes sin sistema de versionado ni testing.