# ADR-005: Frontend Framework

## STATUS
PROPOSED (2026-02-13)

## CONTEXT
LLMHosts needs a web dashboard with: chat interface (streaming), model catalog, compute fleet visualization, real-time metrics (WebSocket), cost savings dashboard with gamification, admin panel, responsive design. Must be modern, fast, and maintainable.

## OPTIONS EVALUATED

### Option A: Next.js + TailwindCSS + shadcn/ui
- **Pros**: React ecosystem (largest community), server-side rendering for SEO/performance, shadcn/ui provides beautiful accessible components, TailwindCSS for rapid styling, excellent TypeScript support, Vercel deployment option, massive component ecosystem
- **Cons**: React learning curve, larger bundle than alternatives, framework complexity
- **Best For**: Full-featured web applications with rich UI

### Option B: SvelteKit
- **Pros**: Smaller bundle size, simpler mental model, excellent performance, less boilerplate
- **Cons**: Smaller ecosystem, fewer ready-made component libraries, smaller hiring pool
- **Best For**: Performance-critical applications

### Option C: Vue/Nuxt
- **Pros**: Good balance of simplicity and features, growing ecosystem
- **Cons**: Smaller than React ecosystem, fewer enterprise examples
- **Best For**: Progressive enhancement, gradual adoption

## DECISION
**Next.js 15+ (App Router) + TailwindCSS + shadcn/ui**

### Key Component Libraries
- **shadcn/ui**: Base component system (accessible, customizable)
- **Recharts** or **Tremor**: Dashboard charts and metrics visualization
- **Tanstack Query**: Server state management and caching
- **Zustand**: Client state management
- **Socket.io** or native WebSocket: Real-time compute metrics

## RATIONALE
- React/Next.js has the largest ecosystem for the complex UI LLMHosts needs
- shadcn/ui provides production-ready, beautiful components out of the box
- TailwindCSS enables rapid iteration on design
- Server-side rendering improves initial load performance
- TypeScript provides type safety across frontend/backend boundary
- Extensive charting libraries available for metrics dashboards
- Large talent pool for future team growth

## CONSEQUENCES
- Node.js required in deployment stack
- Larger initial bundle than SvelteKit alternative
- React/Next.js patterns must be followed consistently
- Need to manage server/client component boundaries (App Router)
