Reader Copilot: de idea a PWA completa con Claude Code remoto
La idea
En el trabajo arrancamos un challenge de lectura. Uno de esos donde cada uno elige un libro y va compartiendo avances. Yo aproveche para retomar la saga de Robert Langdon de Dan Brown, que me gusta mucho, y arranque con Origen.
Si leiste algo de Dan Brown sabes como es: cada dos paginas aparece una referencia a una obra de arte, un edificio, un descubrimiento cientifico, una figura historica. En Origen te tira la Casa Mila de Gaudi, el Museo Guggenheim de Bilbao, obras de arte contemporaneo, la capilla de la Sagrada Familia, teorias sobre el origen de la vida. Yo iba leyendo y cada dos por tres paraba para googlear como se veia algo, o para entender una referencia que no cachaba.
La idea de Reader Copilot nacio de esa friccion: una app donde subis un ePub o PDF, la IA analiza cada capitulo, extrae todas las referencias culturales (obras de arte, esculturas, musica, lugares, figuras historicas, textos) y te las presenta como tarjetas interactivas con imagenes reales. No imagenes generadas por IA --- fotos reales de las obras, los lugares, las personas.
El concepto se fue expandiendo:
- Sistema anti-spoilers: un modo “Mientras Leo” que solo muestra referencias hasta el capitulo actual
- Chat por capitulo: podes hacerle preguntas a la IA sobre lo que acabas de leer
- Quiz/Trivia: para compartir con los del challenge
- Sistema de clubes: con codigos de invitacion para compartir libros y progreso
El tagline que le pusimos resume todo: “Every page has a story behind the story”.
La ejecución: Claude Code en una Mac Mini
Esta es la parte que más me interesa contar, porque el proyecto entero fue construido con Claude Code corriendo de forma remota en una Mac Mini.
El setup
Una Mac Mini encendida 24/7 funcionando como servidor de desarrollo remoto. Claude Code como herramienta principal de desarrollo. Yo desde cualquier lugar --- la notebook, el celular, donde sea --- dándole instrucciones y revisando lo que genera.
El desarrollo se organizó en fases (de la 0 a la 6.5), cada una con tareas gestionadas en un backlog de Obsidian sincronizado con Notion. Claude Code no solo escribía código --- leía el PRD, creaba las tareas en el backlog, las tomaba, las implementaba, corría tests, y pasaba a la siguiente.
Lo que Claude Code construyó
Literalmente todo:
- Scaffolding del proyecto Next.js 16 con React 19
- Esquema de base de datos: 14 tablas en PostgreSQL (Neon) con Drizzle ORM
- Sistema de autenticación completo con better-auth
- Pipeline de parsing de libros (ePub y PDF)
- Integración con APIs de OpenAI para análisis de capítulos
- Más de 30 endpoints de API
- Todos los componentes de UI con Tailwind CSS 4 y shadcn/ui
La cadena de resolución de imágenes
Una de las partes más interesantes del proyecto es cómo resolvemos las imágenes de las referencias culturales. No usamos IA generativa --- necesitamos fotos reales de la Mona Lisa, no una interpretación de DALL-E.
La solución es una cadena de resolución con múltiples fuentes:
/** * Resolve a real image for a cultural reference. * Chain: Wikipedia REST -> Wikidata P18 -> Wikimedia Commons -> Museum APIs */export async function fetchImage( searchTerm: string, type: string = "other",): Promise<ImageResult> { // Wikipedia REST — fastest, 1 fetch const wikipedia = await searchWikipedia(searchTerm); if (wikipedia?.imageUrl) return wikipedia;
// Wikidata P18 — structured, reliable const wikidata = await searchWikidata(searchTerm); if (wikidata?.imageUrl) return wikidata;
// Wikimedia Commons — broadest const wikimedia = await searchWikimediaCommons(searchTerm); if (wikimedia?.imageUrl) return wikimedia;
// Museum APIs — artwork/sculpture only const museum = await searchMuseumApis(searchTerm, type); if (museum?.imageUrl) return museum;
return { imageUrl: null, attribution: null, wikipediaUrl: null, source: null };}Wikipedia REST es la más rápida (un solo fetch), Wikidata P18 es la más estructurada, Wikimedia Commons tiene el catálogo más amplio, y las APIs de museos (Met Museum, Art Institute of Chicago) son las más precisas para obras de arte. Si una fuente falla, pasa a la siguiente. Simple, efectivo, y sin dependencia de servicios pagos.
Los tipos de referencia
El esquema soporta nueve tipos de referencias culturales, cada uno con su propio tratamiento visual:
export const referenceTypeEnum = pgEnum("reference_type", [ "artwork", // Pinturas, dibujos, grabados "sculpture", // Esculturas y relieves "architecture", // Edificios, iglesias, monumentos "music", // Composiciones musicales "symbol", // Símbolos, códigos, criptografía "place", // Lugares geográficos o históricos "person", // Figuras históricas "text", // Textos, manuscritos, libros "other", // Todo lo demás]);La migración que Claude Code resolvió solo
A mitad del desarrollo tomamos una decisión arquitectónica importante: migrar de Cloudflare (D1/R2/Queues) + Anthropic Claude a Vercel + Neon + OpenAI. Las razones eran prácticas --- Vercel simplificaba el deployment de Next.js, Neon daba un Postgres real en lugar de SQLite, y OpenAI GPT-5 Mini/Nano ofrecían mejor relación costo/calidad para el análisis de capítulos.
Claude Code manejó toda la migración. Entendía la arquitectura completa porque la había construido, así que el cambio de proveedores fue limpio.
Code review con Codex CLI
Las revisiones de código se delegaban a un subagente de Codex CLI (@codex-reviewer) que funcionaba como un segundo par de ojos. El agente encontró problemas críticos que en una revisión manual podrían haberse escapado:
- Timeouts de Vercel en el análisis de capítulos largos
- Race conditions en el procesamiento paralelo de referencias
- Checks de seguridad faltantes en endpoints de API
El stack final
- Framework: Next.js 16, React 19
- Estilos: Tailwind CSS 4, shadcn/ui
- Base de datos: Neon Postgres, Drizzle ORM
- Auth: better-auth
- Storage: Vercel Blob
- AI: OpenAI GPT-5 Mini/Nano
- Deployment: Vercel
El cambio en el rol del desarrollador es real. Pasás de escribir código a diseñar la arquitectura, definir los requisitos, y revisar lo que el agente produce. Es un cambio de mentalidad importante.
El rediseño con Stitch MCP
Cuando la app estaba funcionalmente completa, el diseño necesitaba una mejora seria. La UI era funcional pero genérica --- los componentes de shadcn/ui sin personalizar no transmiten mucho.
Acá entró Google Stitch a través de MCP (Model Context Protocol), integrado directamente con Claude Code.
El proceso
- Creé un brief de diseño describiendo la app, sus 10 pantallas principales, y el sistema de diseño que quería
- Stitch generó tokens de diseño inspirados en Material Design 3, usando el espacio de color OKLCh
- El rediseño se ejecutó en 7 fases, cada una como un commit separado:
- Tokens de diseño
- Navegación
- Landing y autenticación
- Biblioteca
- Detalle de libro
- Capítulo y referencias
- Clubes
Todo se mergeó en un solo PR.
Decisiones de diseño
- Escala de colores: zinc como base neutral
- Colores por tipo de referencia: purple para artwork, orange para sculpture, blue para architecture, teal para music, amber para symbols, emerald para places, rose para personas, cyan para textos
- Tipografía: Geist como fuente principal
- Dark mode: soporte completo desde el día uno
Lo interesante de la integración con Stitch MCP es que la IA podía generar los diseños Y aplicarlos al código en el mismo flujo de trabajo. No había handoff entre diseño y desarrollo --- era un proceso continuo.
Un detalle menor pero molesto: después del rediseño, descubrimos que font-mono se había aplicado accidentalmente a labels de UI que deberían haber sido font-sans. Son las cosas que pasan cuando automatizás --- siempre hay que revisar los detalles.
Lecciones aprendidas
Claude Code remoto en una Mac Mini funciona para proyectos full-stack reales. No es un experimento --- es un flujo de trabajo productivo. La combinación de Claude Code para el desarrollo, Codex CLI para las revisiones, y Stitch MCP para el diseño crea un pipeline de desarrollo asistido por IA que cubre todo el ciclo.
La organización en fases con un backlog en Obsidian mantuvo el proyecto en carril. Sin estructura, un agente de IA puede dispersarse. Con tareas claras, priorizadas y organizadas por fase, el desarrollo fue lineal y predecible.
Las migraciones mid-project son manejables cuando la IA conoce toda la arquitectura. Claude Code había construido cada línea de código, así que migrar de un proveedor a otro no requirió explicarle el contexto --- ya lo tenía.
El costo de operar la app es casi cero. Todo corre en tiers gratuitos: Vercel, Neon, Vercel Blob. Para un club de lectura de 3-8 personas, el costo mensual es menor a $1. El gasto real está en las APIs de OpenAI durante el análisis de capítulos, pero con GPT-5 Nano es insignificante.
El rol del desarrollador cambia, no desaparece. Pasás menos tiempo escribiendo código y más tiempo pensando en arquitectura, revisando output, y tomando decisiones de diseño. Es un cambio que requiere adaptación, pero el resultado es que una persona puede construir lo que antes requería un equipo.
Reader Copilot empezo como una necesidad personal en un challenge de lectura del trabajo. Retome la saga de Dan Brown, me encontre googleando cada dos paginas, y pense “esto lo puede resolver una app”. Termino siendo una prueba de concepto de lo que se puede construir cuando le das a un agente de IA las herramientas correctas y una estructura clara de trabajo. Cada pagina tiene una historia detras de la historia --- y cada proyecto tiene una historia de como se construyo.