Arquitectura pro con Claude Code: base de datos, región y Kubernetes

Claude Code te arma una aplicación completa, pero si no le das tus números, elige la base de datos, el servidor y la región por costumbre. A veces acierta, pero esta guía sirve para que la decisión salga de tus datos y no de la costumbre.

Las tres preguntas

Pregunta	Qué decide	Cómo se responde
¿Se lee mucho o se escribe mucho?	La base de datos y cómo escala	Cuenta cuántas lecturas hay por cada escritura en tus pantallas y procesos principales
¿Dónde están tus usuarios?	La región del servidor y de la base	El país desde donde entra la mayoría, y qué ley protege sus datos
¿Cuánto puedes operar?	Si necesitas Kubernetes o no	Cuántos servicios tienes y cuántas personas los mantienen

1. ¿Se lee mucho o se escribe mucho?

Piénsalo como una biblioteca y una oficina de correos. A la biblioteca llega mucha gente a leer los mismos libros: haces copias y dejas los más pedidos en la entrada. Al correo en Navidad llegan miles de cartas: no las clasificas en la puerta, las apilas y las ordenas atrás, a tu ritmo.

Si se lee mucho (catálogo, blog, panel, ficha de producto):

• Una base relacional como Postgres va perfecto para empezar.
• Cuando crece, primero mides cuál consulta es la lenta. Después:
  • Caché (por ejemplo, Redis) para pocos datos muy pedidos y compartidos entre usuarios.
  • Réplicas de lectura, que son copias de la base para consultar, cuando las consultas son muchas y variadas.
• Las réplicas van unos segundos atrasadas. Si alguien guarda algo y lo quiere ver de inmediato, esa lectura va a la base principal.

Si se escribe mucho (métricas, eventos, chat, registros):

• Pones una cola que recibe todo y trabajadores que lo guardan a su ritmo. Así un pico no tumba la base.
• Los trabajadores tienen que tolerar recibir el mismo mensaje dos veces, y los mensajes que fallan varias veces van a una cola aparte para revisarlos.
• Si el volumen es enorme, existen bases hechas para escribir, como Cassandra, o para analizar eventos, como ClickHouse.

Por dentro, cada base guarda los datos de forma distinta. Postgres los ordena en un árbol, que sirve para buscar. Cassandra anota todo al final, como un cuaderno, y ordena después, entonces aguanta muchísimas escrituras. La caché, en cambio, no sirve para datos que cambian a cada rato, porque cada escritura la borra antes de que alcance a servir.

Tabla para elegir tu base de datos

Tus datos se parecen a…	Modelo	Ejemplos de motor
Pagos, reservas, pedidos (tiene que cuadrar)	Relacional	Postgres, MySQL
Catálogo o contenido con forma variable	Documental (o JSON dentro de Postgres)	MongoDB, Postgres con jsonb
Sesiones, contadores, lo más pedido	Clave-valor en memoria	Redis
Eventos, métricas, registros a gran volumen	Columnar o wide-column	ClickHouse, Cassandra
Relaciones entre muchas cosas (recomendaciones)	Grafo	Neo4j

Si no sabes cuál elegir, empieza con Postgres y agrega otra base solo cuando un dominio concreto lo pida y lo puedas medir.

2. ¿Dónde están tus usuarios?

La luz en la fibra óptica viaja a unos 200.000 km por segundo. De Santiago a Virginia (Estados Unidos) hay unos 8.091 km en línea recta, así que la ida y vuelta mínima es de unos 81 milisegundos. En la práctica es más, porque los cables no van en línea recta y cada equipo de red suma tiempo.

Lo que más se nota es tener el servidor en un país y la base en otro, porque cada consulta paga ese viaje. Una página que hace 20 consultas seguidas de 100 milisegundos tarda 2 segundos solo en viajes (cifras de ejemplo).

• Servidor y base, en la misma región. Es lo primero que revisas.
• La región, cerca de la mayoría de tus usuarios. Muchas plataformas crean tus funciones o tu base en Estados Unidos si no eliges otra cosa: revísalo al crear el proyecto.
• Lo estático (imágenes, JavaScript, CSS) va a una CDN, que lo sirve desde cerca de cada usuario.

Además, la región es una decisión legal. En Europa, el Reglamento General de Protección de Datos (RGPD) pone reglas para transferir datos personales fuera de la Unión. En Chile, la Ley 21.719 de protección de datos personales, vigente desde el 1 de diciembre de 2026, también regula la transferencia internacional. Si guardas datos de personas, revisa qué exige la ley de tu país antes de elegir región.

3. ¿Cuánto puedes operar?

Kubernetes es como un director de orquesta para tus contenedores: si uno se cae lo vuelve a levantar, si llega más tráfico agrega copias, y actualiza tu aplicación sin cortar el servicio.

Ojo, no hace tu aplicación más rápida y no es para empezar, porque además del clúster alguien tiene que mantener sus versiones, permisos, redes y monitoreo.

Tu situación	Lo que conviene
Una aplicación y un equipo chico	Plataforma administrada (Railway, Render, Fly.io o similar) y un monolito ordenado por módulos
Tráfico en picos o tareas esporádicas	Funciones serverless para esas partes
Muchos servicios y un equipo que pueda mantener un clúster	Kubernetes, idealmente administrado por tu proveedor de nube

Y con los servicios pasa lo mismo que con la base: separa un módulo en su propio servicio solo cuando tenga una razón medible, como un tráfico muy distinto al resto o un equipo propio que lo despliega por su cuenta.

4. Cómo usarlo en Claude Code

Claude Code conoce toda esta teoría, pero no tus números, así que lo haces en tres pasos.

Paso 1. Escribe tus números en el CLAUDE.md del proyecto. Así cada sesión arranca con ellos.

## Números del negocio
- Usuarios: 5.000 al mes (meta a un año: 50.000)
- País de la mayoría: Chile
- Patrón: 90 % lecturas (catálogo), 10 % escrituras (reservas)
- Datos personales: sí (nombre, correo, teléfono)
- Equipo: 2 personas, sin experiencia operando servidores
- Presupuesto de infraestructura: US$ 50 al mes

(Los números son de ejemplo: pon los tuyos, aunque sean estimados.)

Paso 2. Pídele alternativas antes de programar. Usa el modo plan y este prompt:

Lee la sección «Números del negocio» del CLAUDE.md.

Antes de escribir código, propón la arquitectura de este proyecto respondiendo:

1. ¿El sistema se lee más o se escribe más? Separa por módulo si cambia.
2. Qué base de datos conviene para cada módulo y por qué, según ese patrón.
3. Cuándo agregarías caché, réplicas de lectura o una cola, y qué métrica te diría que llegó el momento.
4. En qué región van el servidor y la base, considerando dónde están los usuarios y qué ley protege sus datos.
5. Dónde lo despliego (plataforma administrada, serverless o Kubernetes), considerando el tamaño del equipo.

Dame dos alternativas con su costo mensual aproximado, su complejidad y sus riesgos, y recomienda una. Si te falta un dato, pregúntamelo en vez de suponerlo. No escribas código todavía.

Paso 3. Guarda la decisión en el proyecto. Pídele que la escriba en docs/decisiones/0001-base-de-datos.md (un registro de decisión de arquitectura). Así la próxima sesión no la vuelve a discutir.

# 0001 · Base de datos: Postgres con una réplica de lectura

## Contexto
90 % lecturas, 5.000 usuarios al mes en Chile, equipo de 2 personas.

## Decisión
Postgres en la misma región que el servidor. Una réplica de lectura cuando
la consulta del catálogo pase de 200 ms en el percentil 95.

## Alternativas descartadas
- Caché con Redis: el catálogo cambia varias veces por hora.
- Kubernetes: una sola app y nadie para operar el clúster.

## Consecuencias
Las lecturas de la réplica pueden ir unos segundos atrasadas.

Checklist antes de escalar

• ¿Mediste cuál es la consulta o la parte lenta, o lo estás suponiendo?
• ¿El servidor y la base están en la misma región?
• ¿La región está cerca de tus usuarios y cumple la ley de sus datos?
• ¿Sabes cuántas lecturas hay por cada escritura en tu parte más usada?
• ¿La decisión está escrita en el proyecto, con lo que descartaste?
• ¿Tienes a alguien que opere lo que vas a agregar?