ADR-004: Frontend Framework

Estado

Aceptada - 2024 (Sevastopol implementado con Astro + SolidJS)

Contexto

El frontend Sevastopol requiere:

Performance: Carga rápida (TTFB menor a 500ms), especialmente en Chile con conexiones variables
Interactividad: Componentes complejos (DataTables, formularios multi-step, charts)
SEO: Indexable por motores de búsqueda (aunque sistema es privado, buena práctica)
Developer Experience: Productividad alta, TypeScript nativo, tooling moderno
Bundle size: Minimizar JavaScript envi ado al cliente

Restricciones

Team size: Equipo pequeño, necesita framework con curva de aprendizaje razonable
Ecosystem: Preferencia por herramientas open-source con comunidad activa
Backend integration: Debe integrarse fácilmente con Orchestrator (Node.js API)

Decisión

Implementar frontend con Astro + SolidJS:

Astro

Static Site Generation (SSG) y Server-Side Rendering (SSR) hybrid
HTML generado en build-time o server-time (sin JS inicial)
“Bring your own framework” - permite mezclar React, Vue, Solid, etc.

SolidJS

Reactive UI library similar a React pero más performante
Usado para componentes interactivos (“Islands”)
Fine-grained reactivity (re-renderiza solo lo que cambia)
Bundle size pequeño (~7KB gzipped)

Arquitectura Islands

 [Astro Page (SSR/SSG)]
       ↓
   Static HTML
       +
   Islands (Interactive components with SolidJS)

Ejemplo:

---
// page.astro (Astro)
import DataTableIsland from '@/islands/DataTable.tsx'; // SolidJS
---

<h1>Employees</h1>
<p>Static content rendered by Astro</p>

<!-- Interactive island hydrated on client -->
<DataTableIsland data={employeesData} client:load />

Consecuencias

Positivas

✅ Server-Side Rendering → TTFB rápido

Astro genera HTML en servidor
Cliente recibe HTML completo inmediatamente (no espera JS)
Perceived performance es excelente (~200-300ms TTFB)

✅ Islands Architecture → JS mínimo

Solo componentes interactivos se hidratan con JavaScript
Página con 10 componentes pero 2 interactive → solo 2 se hidratan
Reduce bundle size en ~60-80% vs SPA tradicional

✅ SolidJS → Performance en Islands

Fine-grained reactivity = solo partes que cambian se re-renderan
No Virtual DOM (menos overhead vs React)
Benchmarks: SolidJS es 2-3x más rápido que React en updates

✅ TypeScript nativo

Astro y SolidJS tienen soporte TypeScript de primera clase
Type-safety en toda la aplicación (props, API calls, etc.)

✅ Developer Experience

Astro tiene tooling excelente (Vite bajo el capó, HMR rápido)
SolidJS API es familiar si se conoce React (JSX, hooks-like)
File-based routing en Astro (pages/ = routes automáticas)

✅ Flexibility

Astro permite mezclar frameworks (SolidJS para performance-critical, otros si se necesita)
No lock-in a un solo framework

Negativas (Trade-offs)

❌ Ecosystem más pequeño vs React

React tiene 100x más librerías, componentes, tutorials, Stack Overflow answers
SolidJS tiene ~10-20 librerías populares (suficiente pero limitado)
Mitigación: Implementamos componentes custom (DataTable, Modal, etc.) desde cero

❌ Curva de aprendizaje

Astro es framework nuevo (2021), menos developers lo conocen
SolidJS tiene conceptos únicos (Signals, Stores diferentes a React State)
Mitigación: Documentación excelente de ambos frameworks, equipo aprendió rápido

❌ Hydration overhead

Islands deben “hidratarse” en cliente (cargar JS, attach events)
Si toda página es interactiva, no hay beneficio vs SPA
Mitigación: Diseño cuidadoso de qué es Island vs qué es static

❌ Deployment complexity

SSR requiere servidor Node.js (no puede ser solo static hosting)
Más complejo que SPA subido a CDN
Mitigación: Containerización con Docker simplifica deploy

❌ Community & hiring

Contratar developers con experiencia Astro+Solid es difícil
Más fácil encontrar React developers
Mitigación: Documentación interna (Jean d’Arc), onboarding process

Alternativas Consideradas

Opción A: Next.js + React

Descripción: Framework SSR más popular del ecosistema React.

Rechazada porque:

Bundle size: React + Next.js envían ~120-150KB gzipped (vs ~40-60KB Astro+Solid)
Performance: Virtual DOM overhead en re-renders (vs fine-grained SolidJS)
Overkill para caso de uso: Muchas features de Next.js no se usan (ISR, Edge functions, etc.)
Vendor tie-in: Next.js es Vercel product (aunque open-source, optimizado para Vercel)

Cuándo sería válida: Si se requiere ecosystem React completo (ej: integración con muchas librerías React), o equipo ya experto en Next.js.

Opción B: Vue + Nuxt

Descripción: Similar a Next.js pero en ecosistema Vue.

Rechazada porque:

Razones similares a Next.js: SSR framework completo vs Islands ligero
Vue 3 Composition API: Similar a React hooks, no ofrece ventaja vs SolidJS
Ecosystem francófono: Mucha documentación en francés (barrera idioma)

Cuándo sería válida: Si equipo ya usa Vue en otros proyectos.

Opción C: SvelteKit

Descripción: Framework SSR con Svelte (compilador, no runtime).

Considerada seriamente:

Performance: Svelte es performante (sin Virtual DOM, similar a Solid)
Bundle size: Comparable a Astro+Solid
DX: Excelente developer experience

Rechazada porque:

Menos flexible: SvelteKit es framework monolítico (solo Svelte, no multi-framework como Astro)
Reactivity menos granular: Svelte re-renderiza componente completo vs Solid (solo partes)
Ecosystem: Solid + Astro creciendo más rápido en 2024

Decisión marginal: SvelteKit fue segunda opción, Astro+Solid ganó por flexibilidad e Islands.

Opción D: Vanilla JS + jQuery

Descripción: Sin framework, solo JavaScript y manipulación DOM directa.

Rechazada porque:

Productividad baja: Escribir cada feature desde cero vs componentes reutilizables
Mantenibilidad: Spaghetti code sin estructura clara
TypeScript complejo: Sin framework, type-safety es difícil
No viable para equipo moderno

Cuándo sería válida: Proyecto muy simple (5-10 páginas estáticas, mínima interactividad).

Referencias

Implementación:

Sevastopol Config - Configuración Astro
Islands - Componentes SolidJS
Pages - Routing Astro

Decisiones relacionadas:

Sevastopol Islands - Documentación de Islands admin
Sevastopol UI Components - Atomic Design

Referencias externas:

Notas Adicionales

Performance Metrics

Lighthouse Score (Sevastopol production):

Performance: 95-98
Accessibility: 100
Best Practices: 100
SEO: 100

Load Time: ~300-400ms TTFB, ~1.2s LCP (Largest Contentful Paint)

Bundle Analysis

Typical page bundle:

Astro static HTML: ~15KB
SolidJS core: ~7KB gzipped
Islands code: ~20-40KB (depending on page)
Total: ~40-60KB (vs 120-150KB typical React SPA)

Developer Feedback

Pro:

“Astro file-based routing es muy intuitivo”
“SolidJS reactivity es rápida y predecible”
“HMR es instantáneo vs webpack lento”

Con:

“Documentación Solid tiene gaps en español”
“Debugging Islands hydration es tricky al inicio”

Future Considerations

Migración a React Component Library: Si se necesita integrar componente React específico (ej: Recharts, React Table), Astro permite <ReactChart client:load /> sin reescribir todo.

Actualización a Astro 5.0: Cuando salga (2025?), evaluar nuevas features (View Transitions API, etc.).