Arquitectura y hoja de ruta

Qué es este prototipo

Una aplicación de una sola página, autocontenida, sin servidor: todo el contenido vive como datos estructurados y se renderiza en el navegador. Está organizada igual que la plataforma final (contenido separado de la presentación, un esquema de documento común para el buscador y laboratorios como módulos independientes), para que migrar sea mover piezas y no reescribirlas.

Stack de producción previsto

Capa	Tecnología	En este prototipo
Frontend	Next.js (App Router), React, TypeScript estricto, Tailwind CSS	HTML, CSS y JavaScript sin dependencias
Contenido	MDX en `/content` con frontmatter tipado	Objetos JS en un único módulo de datos
Matemáticas	KaTeX renderizado en servidor	KaTeX en el navegador, salida MathML
Visualización	D3, Plotly y Recharts	Canvas y SVG a mano
Backend	Python + FastAPI	—
Datos	PostgreSQL + pgvector	—
Búsqueda	Híbrida: texto completo + similitud de embeddings, preparada para RAG	Índice en memoria con el mismo esquema de documento
Despliegue	Docker Compose (frontend, backend, db), CI con GitHub Actions	—

Estructura del repositorio

/frontend        Next.js: app/, components/, lib/, labs/ (un módulo por laboratorio)
/backend         FastAPI: app/api, app/services, app/models, app/search (pgvector)
/content         MDX: machine-learning/, deep-learning/, mathematics/, llm/, papers/, projects/
/data            datasets de ejemplo y scripts de descarga
/notebooks       un notebook por artículo y por proyecto
/models          modelos entrenados versionados
/public          imágenes y recursos estáticos
/docs            arquitectura, decisiones (ADR), guía de contenido
/tests           unitarios (Vitest, pytest) y end-to-end (Playwright)
/docker          Dockerfiles y docker-compose.yml

URLs semánticas

Prototipo	Producción
`#random-forest`	`/machine-learning/random-forest`
`#transformer`	`/llm/transformer-visualizer`
`#lab-gd`	`/lab/gradient-descent`
`#project-mantenimiento`	`/projects/predictive-maintenance`
`#papers`	`/papers/attention-is-all-you-need` (una página por paper)

Modelo de datos

Una entidad común Document (id, tipo, slug, título, resumen, cuerpo, área, nivel, etiquetas, fechas) de la que heredan Artículo, Algoritmo, Proyecto, Paper, Dataset y Laboratorio. Cada documento se trocea en fragmentos (Chunk) con su embedding en una columna vector de pgvector: esa misma tabla sirve para la búsqueda semántica y para el RAG. El buscador de este prototipo ya indexa documentos con los campos id, tipo, título, texto y ruta.

SEO, seguridad y calidad

SEO: en producción, cada página con title, meta description, Open Graph, canonical, JSON-LD (Article, Dataset, ScholarlyArticle), sitemap.xml y robots.txt generados en el build.
Seguridad: validación con Pydantic en la API, rate limiting, cabeceras CSP y HSTS, secretos solo en variables de entorno del servidor y nunca claves de API en el frontend. En este prototipo, todo texto introducido por el usuario se escapa antes de mostrarse.
Accesibilidad: navegación completa por teclado, foco visible, modo claro y oscuro, respeto a prefers-reduced-motion.

Fases

Prototipo navegable con el contenido núcleo (esta versión).
Migración a Next.js con el contenido en MDX y tests.
Backend FastAPI, PostgreSQL y Docker Compose.
Búsqueda semántica con pgvector y asistente RAG sobre el contenido del portal.
Ampliación del contenido: un artículo completo por algoritmo y un laboratorio por concepto clave.