Frontend Architecture & UX

Stack

• •Next.js App Router
• •React 19
• •React Query (the only remote state manager)
• •shadcn/ui + Tailwind CSS

Core Architecture Rules

Rendering Model

• •Server Components by default
• •Client Components only for interactivity
• •No Client Component by convenience
• •Client Components must be explicitly justified

Client Component Boundaries

Client Components must not:

• •Import Server Components
• •Access environment variables
• •Perform direct data fetching
• •Contain business or domain logic

Client Components may only:

• •Handle user interaction
• •Manage local UI state
• •Consume hooks
• •Render presentation logic

Layered Responsibilities

• •

  UI Components

  • •Pure presentation
  • •No business rules
  • •No data normalization
• •

  Hooks

  • •Compose UI state
  • •Integrate React Query
  • •No business decisions
• •

  Domain / Services

  • •Business rules
  • •Decision making
  • •Data validation
• •

  API Layer

  • •HTTP adaptation
  • •Contract enforcement
  • •Error translation

Data & State Management

• •React Query is the only remote state manager
• •No direct data mutations without React Query
• •No fetch calls outside the API layer

React Query Rules

• •Every query must have a stable queryKey
• •Mutable objects are forbidden in queryKey
• •All mutations must explicitly invalidate or update cache
• •refetchOnWindowFocus is disabled by default
• •Errors must always be handled explicitly
• •Silent failures are forbidden

UX Best Practices

Accessibility

• •Accessibility first
• •ARIA roles where applicable
• •Full keyboard navigation support
• •Respect prefers-reduced-motion

Visual Consistency

• •Clear visual hierarchy
• •Consistent spacing and typography
• •Design tokens must be respected
• •Avoid layout shifts (CLS)

States Handling

Every async interaction must define:

• •Loading state (prefer skeletons over spinners)
• •Error state (user-friendly, not technical)
• •Empty state (intentional, not accidental)

Technical errors must never be shown directly to users.

Performance Rules

• •Minimize client-side JavaScript
• •Memoize only when measured or clearly justified
• •Defensive memoization is forbidden
• •Avoid unnecessary re-renders
• •Lazy-load non-critical components only
• •Dynamic imports must not affect critical rendering paths

Developer Experience (DX)

• •Reusable components over duplication
• •Clear, explicit naming
• •Prefer composition over configuration
• •Avoid deep prop drilling

Props Discipline

• •More than 5 props requires design reconsideration
• •Boolean explosion is forbidden (isA, isB, isC)
• •Prefer explicit components over conditional flags

Non-Negotiables

• •No business logic in UI
• •No direct backend calls from components
• •No architectural shortcuts
• •Predictability over flexibility

Architectural violations are treated as bugs.