platform-argentum
Catálogo web sobre Argentina, con prosa épica de registro alto.
Estado. La aplicación compila, corre contra PostgreSQL y está desplegada.
Existen dos módulos: catalogo, con la tabla entidad, el registro de
descriptores y la primera ficha curada (contenido/procer/manuel-belgrano.ts),
y identidad, con cuentas de email y contraseña o Google sobre Better Auth
(ADR 0019). /catalogo y /catalogo/[slug] se sirven contra el módulo real,
y /ingresar y /registrarse contra identidad; el inicio de sesión en
producción espera la configuración de sus variables (#123). Todavía no
existen moderacion, aprendizaje ni progreso: las pantallas de
/ficha, /tarjetas, /quiz y /quiz/resultado son presentación con datos
simulados. La arquitectura y el stack están decididos en
docs/adr/.
Qué es
Un catálogo de contenido sobre Argentina —próceres, monumentos, animales,
comida, fechas patrias, eventos históricos— pensado para un lector de doce
años en adelante, que lo lea, lo entienda y lo repase jugando. La audiencia y
el registro épico de la prosa están decididos en
ADR 0012; una versión
para chicos más chicos, en otra lengua y quizás otro diseño, está pospuesta,
no cancelada (ver
docs/decisiones-pendientes.md).
La idea no es un enciclopedismo: es que el contenido se pueda ver a simple
vista, con una interfaz clara y sin fricción, y que arriba de ese catálogo
haya tarjetas de repaso y un juego de preguntas que refuercen lo leído.
El conjunto de tipos de contenido no está cerrado a propósito. Hoy son los
que están arriba; mañana pueden ser otros. Toda la arquitectura está diseñada
alrededor de ese hecho: agregar un tipo nuevo tiene que ser barato (ver
ADR 0001).
Alcance
MVP
- Catálogo de lectura. Listado y ficha por entidad, para todos los tipos.
- Tarjetas de repaso. Con la respuesta del lado de atrás.
- Quiz de preguntas. Individual, con puntaje. Las preguntas y sus opciones
se generan a partir del propio catálogo, no se redactan a mano.
- Progreso y panel de resultados. Qué respondiste bien, qué mal, en qué
temas fallás más.
- Puntos y ligas. El puntaje cae en una liga fija: Cobre, Plata, Oro o
Litio, los metales del suelo argentino. No se sube ni se baja de liga, y no
se compite con nadie. Es un incentivo, no un ranking.
Las cuentas existen (ADR 0019), pero ninguna pantalla exige sesión y el
progreso todavía no se guarda. A quién se le atribuye el progreso de un
visitante, y si se reconcilia con su cuenta cuando se registra, es una decisión
abierta a propósito: la audiencia arranca a los doce años
(ADR 0012) y a esa edad se sigue siendo menor, así que persistir un
identificador por navegador sigue siendo una decisión sobre datos de menores,
no un detalle de implementación —la dimensión se aflojó con la nueva audiencia,
pero no desapareció—. Está registrada, con su disparador y su regla interina,
en docs/decisiones-pendientes.md.
Después del MVP
- Propuestas de la comunidad. Los usuarios proponen altas, modificaciones y
bajas de contenido; nada se publica sin que un administrador lo apruebe.
- Roles.
usuario, admin y superadmin. Un visitante sin sesión no es un
rol: es la ausencia de sesión.
- Aplicación mobile. Mencionada como posibilidad a largo plazo. La
arquitectura la admite sin reescritura (ver
ADR 0002).
Cómo está construido
Una sola aplicación fullstack, un solo deploy, organizada en cinco módulos:
| Módulo | De qué se ocupa |
|---|
catalogo | Entidades, tipos y sus fichas |
aprendizaje | Tarjetas de repaso y quiz |
progreso | Eventos de actividad, puntos, ligas, áreas flojas |
moderacion | Propuestas de la comunidad y su aprobación |
identidad | Cuentas, sesiones y roles |
Regla de límite, vinculante: la capa web no consulta la base de datos; le
pide al módulo. Toda verificación de permisos ocurre dentro del módulo,
nunca solo en la interfaz.
El catálogo se guarda en una sola tabla con un discriminador de tipo y una
columna JSONB. Los campos de cada tipo se definen en descriptores en
código, que son la fuente única para tipar la columna, validar la importación,
validar las propuestas, y renderizar el formulario y la ficha.
El contenido curado se escribe en archivos versionados en este repositorio y
un script lo importa a la base, que es lo que sirve la aplicación. Así el
contenido tiene historial, revisión y vuelta atrás, sin construir nada.
Stack
| Capa | Tecnología |
|---|
| Framework | Next.js 16 · React 19 · TypeScript |
| Estilos | Tailwind CSS v4 |
| Base de datos | PostgreSQL |
| Acceso a datos | Drizzle ORM |
| Validación | Zod |
| Tests | Vitest |
| Hosting | Vercel |
| Base gestionada | Neon |
| Autenticación | Better Auth (ADR 0019) |
El criterio de selección fue explícito: lo mejor para el proyecto, no lo más
conocido ni lo más novedoso. El razonamiento completo, con las alternativas que
se descartaron y por qué, está en
ADR 0003.
Puesta en marcha
Requisitos: Node 22 (fijado en .nvmrc), pnpm y Docker.
git clone https://github.com/luciano-stefano-meloclaps/platform-argentum.git
cd platform-argentum
pnpm install
cp .env.example .env # completar DATABASE_URL y DATABASE_URL_UNPOOLED
docker compose up -d # PostgreSQL 18 local
pnpm db:migrate # aplica las migraciones
pnpm contenido:importar # carga el contenido curado en la base local
pnpm dev # http://localhost:3000
Los valores de la base local salen de docker-compose.yml. El archivo es .env
—no .env.local—: es el que leen pnpm db:ping y drizzle.config.ts.
Ojo: en Next.js, .env.local pisa a .env. Si existe un .env.local, la
aplicación (pnpm dev, pnpm build) usa sus valores y no los de .env, aunque
pnpm db:migrate y drizzle.config.ts sigan leyendo .env. Si la aplicación y
las migraciones parecen apuntar a bases distintas, mirá primero si hay un
.env.local olvidado.
Variables de identidad y entornos de Vercel
El módulo identidad (Better Auth, ADR 0019) necesita BETTER_AUTH_SECRET,
BETTER_AUTH_URL, GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET. Se leen en el
primer uso, no al compilar: pnpm build no las exige, pero la primera petición
que las necesite falla con un error que nombra la que falta. En Vercel se
cargan en los tres entornos (Production, Preview y Development), con
BETTER_AUTH_SECRET y BETTER_AUTH_URL distintos por entorno, y el URI de
redirección <BETTER_AUTH_URL>/api/auth/callback/google registrado en Google
Cloud Console por cada URL. El detalle, sin valores reales, está en
.env.example.
Comandos
| Comando | Qué hace |
|---|
pnpm dev | Servidor de desarrollo |
pnpm build | Compila para producción |
pnpm typecheck | next typegen y tsc --noEmit |
pnpm lint | ESLint |
pnpm test | Tests con Vitest |
pnpm db:ping | Verifica que la base responda |
pnpm db:generate | Genera migraciones a partir del esquema |
pnpm db:migrate | Aplica las migraciones pendientes |
pnpm contenido:importar | Importa contenido/ a la base, validando cada ficha contra el descriptor de su tipo (ADR 0004) |
pnpm desplegar:datos | db:migrate y después contenido:importar. Contra una base que no sea local exige DB_CONFIRMAR_DESTINO=<host> (ADR 0023); el procedimiento está en docs/runbooks/desplegar-datos.md |
Antes de dar por terminado un cambio: pnpm typecheck && pnpm lint && pnpm test.
Las pruebas de catalogo corren contra el PostgreSQL de Docker: sin
docker compose up -d, fallan con ECONNREFUSED.
Cómo agregar contenido
El contenido vive en contenido/<tipo>/<slug>.ts: un archivo TypeScript por
entidad, tipado por el descriptor de su tipo
(ADR 0009). El directorio es el
tipo y el nombre del archivo es el slug. La prosa va entre comillas
dobles concatenadas con +: cada tramo termina con un espacio salvo el último
del campo, un párrafo nuevo es "\n\n" y la importación no normaliza nada
(ADR 0030).
// contenido/procer/manuel-belgrano.ts
export default {
nombre: "Manuel Belgrano",
datos: {
nombreCompleto: "Manuel José Joaquín del Corazón de Jesús Belgrano",
anioDeNacimiento: 1770,
anioDeMuerte: 1820,
resumen:
"Abogado, economista y militar porteño. Creó la bandera celeste y blanca " +
"en 1812 y dedicó su vida y su fortuna a la independencia y a la escuela " +
"pública.",
semblanza:
"Manuel Belgrano no fue un militar que aprendió a gobernar: fue un " +
"sembrador obligado, contra su naturaleza y su fortuna, a defender " +
"el surco con la espada. " +
"\n\n" +
"…",
imagen: {
textoAlternativo: "Retrato de Manuel Belgrano",
credito: "Museo Histórico Nacional",
licencia: "dominio-publico",
},
},
};
Se eligió TypeScript y no Markdown ni JSON por una razón concreta: el error
aparece en el editor, antes de correr nada. Las alternativas y sus trade-offs
están en el ADR 0009.
La imagen va en public/contenido/<tipo>/<slug>.webp y el archivo no declara
su ruta —se deriva del tipo y del slug—, pero sí su texto alternativo, su crédito
y su licencia, que es un conjunto cerrado: una imagen sin derechos declarados
no compila.
Se abre un pull request, se revisa y se aprueba. La importación valida cada
ficha contra el descriptor de su tipo: si no cumple el esquema, falla y el
contenido no entra.
Cómo se trabaja
Por rebanadas: cada una es una funcionalidad completa —de los datos hasta la
pantalla— que termina desplegada y usable por sí sola. No se construye "todo el
backend" y después "todo el frontend".
Cada rebanada se corta en tickets, que son issues de este repositorio, y
nada entra al historial sin un ticket que lo explique. El trabajo lo hacen
agentes de Claude Code con roles y límites definidos en
CLAUDE.md.
El estado de cada ticket se sigue en el
tablero del proyecto
(Backlog, Listo, En curso, En revisión y Hecho). Los tickets se
clasifican con etiquetas de tipo, área y prioridad; el esquema está en
docs/agents/issue-tracker.md.
El trabajo con ticket llega a la rama development: el
delivery-specialist pushea la rama de la rebanada y abre el pull request
contra development —nunca contra main—, y lo mergea. Cada uno de esos dos
pasos, push y merge, requiere la verificación explícita del usuario antes de
ejecutarse.
Mergear development a main y desplegar sigue siendo enteramente del
usuario, en su propio tiempo.
Documentación
Antes de proponer un cambio que contradiga una decisión registrada, leé el ADR
correspondiente. Si la decisión cambia, se escribe un ADR nuevo que supersede
al anterior; el viejo no se edita.
