# FRONTEND.md - Frontend Architecture

**Authority:** guidance (frontend patterns, performance, and user experience)
**Layer:** Guides
**Binding:** No
**Scope:** frontend architecture, performance optimization, and UX patterns
**Non-goals:** specific framework tutorials, visual design guidelines

---

## 1. Frontend Architecture Principles

### 1.1 Performance is User Experience
**Core Web Vitals are engineering requirements:**
- **LCP (Largest Contentful Paint):** < 2.5s
- **FID (First Input Delay):** < 100ms
- **CLS (Cumulative Layout Shift):** < 0.1

**Every 100ms delay = 1% conversion drop.**

### 1.2 Progressive Enhancement
- **Baseline:** Works without JavaScript
- **Enhancement:** Add interactivity progressively
- **Resilience:** Graceful degradation
- **Accessibility:** Works for all users

### 1.3 Mobile First
- Design for constraints first
- Progressive enhancement for desktop
- Touch-friendly targets (44px minimum)
- Responsive images and layouts

### 1.4 Accessibility (a11y)
**Not optional. Legal and ethical requirement.**
- Semantic HTML
- Keyboard navigation
- Screen reader support
- Color contrast (WCAG AA minimum)
- Focus management

### 1.5 Production Mindset
The frontend is not a layer — it is the product. Every decision that degrades the user experience degrades the product itself:

- **Time-to-interactive is a revenue metric:** A bloated JavaScript bundle has a direct, measurable impact on conversion and retention. Every new dependency must justify its payload weight. If a library costs 200KB to format a date, replace it with 5 lines.
- **Framework stability over novelty:** Rewriting the frontend every time a new framework trends is a net loss. Choose a mature, well-supported ecosystem and hold it. Innovation belongs in the user experience and product capability, not the build toolchain.
- **Accessibility is a correctness requirement, not a backlog item:** If a core flow cannot be completed with a keyboard and screen reader, the feature is defective. This is both an ethical and legal obligation, and it must be verified before any flow is marked complete.
- **Standardized components over bespoke CSS:** A consistent, accessible component library is a force multiplier. Custom widget implementations for standard patterns (buttons, modals, selects) accumulate accessibility debt and design drift. Use and maintain a shared system.
- **State locality reduces complexity:** The largest source of frontend complexity is state that lives farther from its use site than necessary. Reach for global state only when multiple disconnected components strictly require synchronization. Local and URL state should be the defaults.
- **Choose the rendering model for the use case:** SSR and SSG are the correct defaults for content-heavy pages and SEO-critical surfaces. Pay the cost of a full SPA only when the interface genuinely requires app-level interactivity that cannot be achieved otherwise.
- **Server-state libraries are the standard:** Manual `useEffect` for data fetching is error-prone and widely superseded. Libraries like React Query and SWR handle caching, deduplication, background refresh, and error states correctly. Use them.
- **Monitor bundle size as a first-class metric:** Tree-shaking must be verified, not assumed. Bundle analysis should run in CI. Size regressions are caught at PR review, not discovered when performance degrades in production.

---

## 2. Rendering Strategies

### 2.1 Static Site Generation (SSG)
**When to use:**
- Content that changes infrequently
- Blogs, documentation, marketing sites
- Maximum performance

**Benefits:**
- CDN cacheable
- Fastest load times
- No server required

**Examples:** Next.js SSG, Gatsby, 11ty

### 2.2 Server-Side Rendering (SSR)
**When to use:**
- Dynamic content
- SEO requirements
- Personalized content

**Benefits:**
- Fast initial load
- SEO friendly
- Dynamic data at request time

**Examples:** Next.js SSR, Nuxt, SvelteKit

### 2.3 Client-Side Rendering (SPA)
**When to use:**
- Highly interactive applications
- After initial page load
- Dashboards, admin panels

**Benefits:**
- Smooth interactions
- Reduced server load
- App-like experience

**Trade-offs:**
- Slower initial load
- SEO challenges
- More JavaScript

### 2.4 Incremental Static Regeneration (ISR)
**When to use:**
- Mostly static with some dynamic data
- High traffic pages
- Stale-while-revalidate pattern

**How it works:**
1. Serve cached static page
2. Trigger background regeneration
3. Next request gets updated page

### 2.5 Islands Architecture
**When to use:**
- Content-heavy sites
- Minimal JavaScript
- Progressive enhancement

**Concept:**
- Static HTML by default
- Interactive "islands" hydrate separately
- Reduced JavaScript footprint

**Examples:** Astro, Fresh, Eleventy + Alpine

---

## 3. State Management

### 3.1 Local State
- **useState (React):** Component-specific
- **Signals (Solid/Vue):** Fine-grained reactivity
- **When to use:** UI-only state, form inputs

### 3.2 Global State
**Options by complexity:**
- **Context API (React):** Simple, prop drilling alternative
- **Zustand:** Lightweight, no boilerplate
- **Redux:** Complex, time-travel, devtools
- **MobX:** Observable, OOP style

**When to use:**
- User authentication
- Theme preferences
- Shopping cart
- Cross-component data

### 3.3 Server State
**Libraries:**
- **React Query (TanStack Query):** Caching, synchronization
- **SWR:** Stale-while-revalidate
- **Apollo Client:** GraphQL

**Benefits:**
- Automatic caching
- Background refetching
- Optimistic updates
- Error handling

### 3.4 URL State
- **Use for:** Shareable views, filters, pagination
- **Benefits:** Bookmarkable, back button works
- **Implementation:** Query parameters, hash routing

---

## 4. Performance Optimization

### 4.1 Bundle Optimization
**Code splitting:**
- Route-based splitting
- Component lazy loading
- Dynamic imports

**Tree shaking:**
- ES modules
- Side-effect-free imports
- Dead code elimination

**Bundle analysis:**
- webpack-bundle-analyzer
- Import cost (VSCode)
- Lighthouse bundle analysis

### 4.2 Loading Strategies
**Priority:**
- **Critical:** Render-blocking, above fold
- **Important:** Needed for interactivity
- **Deferred:** Below fold, non-critical

**Techniques:**
- `preload` for critical resources
- `prefetch` for next navigation
- `lazy` for images
- `async/defer` for scripts

### 4.3 Image Optimization
- **Formats:** WebP, AVIF for modern browsers
- **Responsive:** `srcset` for different sizes
- **Lazy loading:** Native or library
- **CDN:** Image optimization services
- **Dimensions:** Always specify width/height (prevent CLS)

### 4.4 Caching Strategies
- **Service Workers:** Offline support, caching
- **Cache API:** Programmatic cache control
- **HTTP caching:** Cache-Control headers
- **Stale-while-revalidate:** Fresh data, fast loads

---

## 5. Component Architecture

### 5.1 Atomic Design
- **Atoms:** Basic building blocks (buttons, inputs)
- **Molecules:** Groups of atoms (search bar)
- **Organisms:** Complex components (header)
- **Templates:** Page layouts
- **Pages:** Specific instances

### 5.2 Container/Presentational Pattern
- **Containers:** Data fetching, business logic
- **Presentational:** Pure UI, props in, events out
- **Benefits:** Separation of concerns, testability

### 5.3 Compound Components
- Related components that share state
- Flexible composition
- Example: `<Tabs>`, `<Tab>`, `<TabPanel>`

### 5.4 Render Props vs Hooks
- **Render props:** Component injection
- **Hooks:** Logic reuse without components
- **Modern preference:** Hooks for most cases

---

## 6. API Integration

### 6.1 REST Integration
- **Fetch API:** Native, promises
- **Axios:** Interceptors, timeouts, wider browser support
- **Error handling:** Global and local
- **Loading states:** Skeletons, spinners

### 6.2 GraphQL Integration
- **Apollo Client:** Caching, optimistic UI
- **Relay:** Facebook's GraphQL client
- **urql:** Lightweight alternative

**Benefits:**
- Precise data fetching
- Single endpoint
- Strong typing

### 6.3 Real-Time
- **WebSockets:** Bidirectional, persistent
- **SSE (Server-Sent Events):** Server to client
- **Polling:** Simple, less efficient
- **Subscriptions:** GraphQL real-time

---

## 7. Testing

### 7.1 Unit Testing
- **Jest:** JavaScript testing framework
- **Vitest:** Fast, Vite-native
- **React Testing Library:** User-centric testing

**What to test:**
- Pure functions
- Component rendering
- User interactions
- Edge cases

### 7.2 Integration Testing
- **Cypress:** E2E testing
- **Playwright:** Cross-browser E2E
- **Testing Library:** Component integration

**What to test:**
- User flows
- API integration
- State management

### 7.3 Visual Testing
- **Storybook:** Component development
- **Chromatic:** Visual regression
- **Percy:** Screenshot comparison

### 7.4 Performance Testing
- **Lighthouse:** Automated audits
- **WebPageTest:** Real device testing
- **React Profiler:** Component performance

---

## 8. Build and Deployment

### 8.1 Build Tools
- **Vite:** Fast, modern
- **Webpack:** Mature, configurable
- **esbuild:** Go-based, extremely fast
- **Turbopack:** Rust-based, Webpack successor

### 8.2 TypeScript
- **Benefits:** Type safety, IDE support, documentation
- **Strict mode:** Catch more errors
- **Gradual adoption:** jsdoc, allowJs

### 8.3 CI/CD
- **Linting:** ESLint, Prettier
- **Type checking:** tsc --noEmit
- **Testing:** Unit, integration, e2e
- **Building:** Production optimizations
- **Deployment:** Vercel, Netlify, Cloudflare Pages

---

## 9. Anti-Patterns

- **Giant bundles:** No code splitting
- **Prop drilling:** Deep component nesting
- **No error boundaries:** Crash entire app
- **Synchronous blocking:** Main thread hogging
- **Memory leaks:** Unsubscribed listeners
- **No loading states:** Blank screens
- **Layout shift:** No dimensions on images
- **Blocking CSS/JS:** Render-blocking resources
- **No accessibility:** Missing ARIA, keyboard nav
- **Over-engineering:** Complex solutions for simple problems

---

## Links

- [ARCHITECTURE](../methodology/ARCHITECTURE.md) - binding architecture doctrine
- [WEB](WEB.md) - Web architecture
- [CACHING](CACHING.md) - Caching strategies
- [SECURITY](SECURITY.md) - Frontend security
- [PERFORMANCE](PERFORMANCE.md) - Performance patterns

### Parent Docs
- [DECAPOD](../core/DECAPOD.md) - Router and navigation charter
- [INTERFACES](../core/INTERFACES.md) - Interface contracts
- [INTENT](../specs/INTENT.md) - Intent specification
