Reader Copilot: de idea a PWA completa con Claude Code remoto
La idea
Todo empezó en un club de lectura. Somos entre 3 y 8 personas, y estábamos leyendo El Código Da Vinci. Cada dos páginas aparecía una referencia a una obra de arte, una escultura, un lugar histórico o un personaje real. Alguien preguntaba “che, cómo era la Virgen de las Rocas?”, otro googleaba, otro mandaba un link de Wikipedia, y la conversación se cortaba.
La idea de Reader Copilot nació de esa fricción: una app donde subís un ePub o PDF, la IA analiza cada capítulo, extrae todas las referencias culturales (obras de arte, esculturas, música, lugares, figuras históricas, textos) y te las presenta como tarjetas interactivas con imágenes reales. No imágenes 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 capítulo actual
- Chat por capítulo: podés hacerle preguntas a la IA sobre lo que acabás de leer
- Quiz/Trivia: para las reuniones del club de lectura
- Sistema de clubes: con códigos de invitación 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 empezó como una necesidad personal en un club de lectura. Terminó 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 página tiene una historia detrás de la historia --- y cada proyecto tiene una historia de cómo se construyó.