Document: 14-frontend-architecture.md
Version: 1.0.0

Purpose

This document defines the frontend architecture used across all Rundown web projects.

It establishes how Next.js applications should be structured, how frontend responsibilities are organized, and how the frontend interacts with the remaining subsystems of the application.

The objective is to create a frontend architecture that is predictable, maintainable, performant, and reusable across all projects.

Frontend Philosophy

The frontend exists to present information and facilitate user interaction.

It should remain focused on:

• Rendering content

• Managing user interactions

• Composing reusable components

• Coordinating data from backend services

The frontend should not become the primary location for business rules or content management.

Responsibilities

The frontend owns:

• Page rendering

• Routing

• Layout composition

• User interface

• Client-side interactions

• Form presentation

• Navigation

• Accessibility implementation

• SEO rendering

• Animation orchestration

Non-Responsibilities

The frontend should not own:

• Content management

• Database design

• Media storage

• Authentication persistence

• Business calculations

• Infrastructure configuration

Whenever possible, the frontend should consume data rather than define it.

Application Structure

Every Rundown frontend should follow the standard project structure defined in:

05-project-structure.md

Frontend-specific logic should remain within:

app/
components/
features/
hooks/
styles/

Business logic should remain isolated from presentation wherever practical.

Rendering Strategy

Rundown applications should use the rendering strategy most appropriate for the content being delivered.

Static Site Generation (SSG)

Preferred for:

• Marketing pages

• Landing pages

• Portfolio pages

• Service pages

Server-Side Rendering (SSR)

Preferred for:

• User-specific content

• Dashboards

• Search results

• Authenticated experiences

Client Components

Should be used only when browser-side interactivity is required.

Examples include:

• Forms

• Interactive filters

• Animations

• Drag-and-drop interfaces

Prefer Server Components by default.

Component Architecture

Frontend components should be divided into:

Layout Components

Examples:

• Navbar

• Footer

• Sidebar

• Page Layout

Shared Components

Examples:

• Button

• Card

• Modal

• Input

• Badge

Feature Components

Examples:

• Product Grid

• Checkout Form

• Blog List

• Portfolio Gallery

Feature components should remain within their respective feature directories.

State Management

The frontend should prefer the simplest solution capable of meeting project requirements.

Recommended order:

1. React State

2. React Context

3. URL State

4. External state libraries (only when justified)

Global state should be introduced only when local state is no longer sufficient.

Data Fetching

Data should be fetched as close as possible to where it is required.

General principles:

• Prefer server-side data fetching.

• Avoid duplicate requests.

• Cache where appropriate.

• Keep client-side fetching to interactive scenarios.

Forms

Forms should:

• Validate user input.

• Provide meaningful feedback.

• Handle loading states.

• Display clear error messages.

• Remain accessible.

Submission logic should remain separate from presentation where practical.

Animations

Animations should improve usability rather than distract from content.

Standard libraries:

• GSAP

• Framer Motion

• Lenis

Animation principles:

• Purposeful

• Performant

• Accessible

• Optional where appropriate

Avoid animations that delay access to content or reduce usability.

Accessibility

Frontend development should prioritize accessibility.

Minimum requirements:

• Semantic HTML

• Keyboard navigation

• Focus management

• Screen reader support

• Appropriate ARIA usage

• Sufficient color contrast

Accessibility should be built into components rather than retrofitted later.

Performance

Frontend performance should prioritize:

• Minimal JavaScript

• Optimized images

• Lazy loading

• Efficient rendering

• Code splitting

• Font optimization

Performance decisions should support the Core Web Vitals objectives defined elsewhere in Rundown OS.

Error Handling

The frontend should gracefully handle:

• Missing content

• API failures

• Invalid routes

• Network interruptions

• Unexpected application errors

Error states should be informative without exposing implementation details.

Engineering Decision

Frontend Framework

Status: Accepted

Decision

Rundown standardizes on Next.js with React and TypeScript for all production frontend development.

Reasoning

This architecture provides:

• Excellent SEO

• Strong performance

• Mature ecosystem

• Flexible rendering strategies

• Long-term maintainability

• Excellent integration with Payload CMS

Frontend Checklist

Before completing frontend development, verify:

• Components are reusable.

• Business logic is appropriately separated.

• Accessibility requirements have been met.

• Performance has been considered.

• Animations are purposeful.

• Responsive behaviour has been verified.

• Data fetching follows Rundown standards.

Summary

The frontend architecture provides the user-facing layer of every Rundown application.

By maintaining a clear separation between presentation, business logic, and backend services, the frontend remains scalable, maintainable, and capable of supporting a wide variety of project types while delivering a consistent user experience.

Related Documents

• 05-project-structure.md

• 08-coding-standards.md

• 12-system-architecture.md

• 13-architecture-boundaries.md

Related ADRs

• ADR-001: Repository Structure