UI Architecture Patterns

Examine the structural patterns that keep large front end codebases organised, testable, and maintainable as teams and feature counts multiply — and learn to recognise when each pattern earns its complexity cost.

The Codebase That Grew Without a Plan

Linear — the project management tool that became an industry benchmark for fast, polished software — published a technical retrospective describing a moment in their early growth where their front end codebase had accumulated what they called "architectural debt at the structural level." Individual components were clean. Tests passed. But the relationships between components — who owned what state, which files knew about which other files, where business logic lived — had grown organically into a structure nobody had explicitly chosen.

The symptom was specific: adding a new feature required touching eight files across five directories, with no obvious place for any of the new code. Engineers spent more time deciding where to put things than writing them. That friction is not a productivity problem — it's an architecture problem. And it almost always has the same root cause: the team built components without patterns, and patterns without principles, until the codebase became a collection of local decisions that made global sense to nobody.

UI architecture patterns exist to prevent that specific failure. Not by making the codebase rigid, but by making it legible — so that any engineer can navigate it, any feature can find its place, and any change can be made with confidence about what it will and won't affect.

Container / Presenter — Separating What From How

The most widely-taught UI architecture pattern is also the most misunderstood. Dan Abramov introduced the Container/Presenter separation (also called Smart/Dumb or Stateful/Stateless) in a 2015 Medium article that was read by nearly every React developer of that era. He later wrote a follow-up partially walking it back — not because the idea was wrong, but because teams were applying it mechanically, splitting every component into two regardless of whether the split added clarity.

The core idea is sound and worth understanding. A container component is responsible for what data is shown — it fetches data, manages state, handles side effects, and passes results down as props. A presenter component is responsible for how that data looks — it accepts props and renders UI, with no knowledge of where those props came from. The presenter is a pure function of its inputs. It can be tested by passing any props — no mocking, no store setup, no API.

The PixelForge Frontend team's convention: container components live in a /containers subdirectory alongside their presenter siblings. But they only create a container when the data logic is complex enough to warrant isolation — simple data-fetching lives in a custom hook inside the component file. The rule is not "always split" — it's "split when the complexity earns it."

Compound Components — Flexible APIs Without Prop Explosion

Every component library eventually produces a component so complex that a flat prop API can't express all its valid configurations without becoming unwieldy. A Select dropdown with grouped options, icons, custom option rendering, multi-select, clearable, and searchable behaviour would require dozens of props if designed naively — and every combination of those props creates a new implicit behaviour the author must test and document.

Compound components solve this by distributing the API across multiple cooperating components that share implicit state through React context. Instead of a single <Select options={...} groups={...} renderOption={...}>, you get:

The compound component pattern uses React context internally to share state between the parent and its sub-components — without exposing that context to consumers. The <Select> root manages which option is selected. <Select.Option> reads the selected state from context and renders the appropriate visual. The consumer never touches the context — they just compose the sub-components they need in the order they want.

Radix UI's entire component library is built on the compound component pattern. A DropdownMenu is composed from DropdownMenu.Root, DropdownMenu.Trigger, DropdownMenu.Content, and DropdownMenu.Item. Each is independently styleable. The shared behaviour — keyboard navigation, focus management, open/close state — is handled by the Root, invisibly. The PixelForge Design Systems team uses this exact pattern for their ContextMenu, Tabs, and Accordion components — all built on Radix primitives with PixelForge token-based styles applied on top.

Feature-Sliced Design — Organising by What, Not How

Most front end projects organise their files by technical type: a /components folder, a /hooks folder, a /utils folder, a /store folder. This feels natural at the start. At 500 files it becomes a liability — the /components folder contains 200 files with no obvious relationship to each other, and finding everything related to the "Comments" feature requires hunting across five directories.

Feature-Sliced Design (FSD) is an architectural methodology that inverts this. Files are primarily organised by business domain — by what they do in the product — not by what type of code they contain. A slice called canvas contains everything related to the canvas feature: its components, its hooks, its store slice, its API calls, its types, and its tests. Everything about canvas is together. Deleting the canvas feature means deleting one directory.

The critical rule in FSD is unidirectional dependencies: layers can only import from layers below them, never above. A feature can import from entities and shared. A page can import from widgets, features, and entities. Nothing in shared/ can import from features/. This constraint eliminates circular dependencies — the class of import error that is genuinely difficult to debug and almost always indicates a structural problem in the codebase.

Event-Driven UI — Decoupling Components That Don't Know About Each Other

State management and props cover most inter-component communication — but there's a class of communication that neither handles cleanly. Two components that need to react to the same event but have no parent-child relationship, no shared context, and no reason to be wired directly together. In a monolith this might be two widgets in completely different parts of the tree that both need to respond when a user's session expires.

The Observer pattern — or event bus — solves this. A centralised event emitter allows any part of the application to publish events, and any other part to subscribe to them, without either side knowing the other exists. The publisher doesn't know who's listening. The subscriber doesn't know who published. They're decoupled by the event contract alone.

The PixelForge Platform team implemented an internal event bus using the browser's native CustomEvent API and a thin typed wrapper that enforces event name and payload contracts in TypeScript. Their event catalogue — a TypeScript union type listing every valid event name and its payload shape — serves as the application's communication contract. Any module can publish or subscribe to typed events without importing anything except the event bus singleton and the shared type definitions.

Render Strategies as Architecture — Islands, Streaming, and Partial Hydration

The rendering model choices from Lesson 3 — CSR, SSR, SSG, ISR — operate at the page level. But as front end architecture has matured, a new set of patterns has emerged that operate at the component level, allowing different parts of the same page to use different render strategies. These patterns are among the most significant architectural advances in front end engineering in the last five years.

Astro popularised the Islands Architecture: a page is predominantly static HTML (fast, no JavaScript cost) with isolated "islands" of interactivity hydrated independently. Each island is a separate React, Vue, or Svelte component that loads and hydrates only when needed — the rest of the page has no JavaScript overhead at all. This is how Astro powers documentation sites and content-heavy pages with near-zero JavaScript bundle costs while still supporting interactive components where the product requires them.

React Server Components — introduced in Next.js 13 and stabilised in Next.js 14 — represent the most significant change to React's component model since hooks. A Server Component renders on the server, can directly await database queries and file system reads, and ships pure HTML to the client with zero JavaScript in the bundle for that component. Client Components — marked with 'use client' — work exactly as before and can be nested inside Server Components. The architecture allows you to compose server-rendered data-fetching with client-rendered interactivity at the component level rather than the page level.

Choosing an Architecture — The Questions That Matter

Every architecture pattern in this lesson has a place. None of them should be adopted wholesale without asking whether their complexity cost is justified by the problem they solve. A five-person team building a startup's first product does not need Feature-Sliced Design. A team of forty with five independent product squads probably does. An event bus is powerful for cross-cutting concerns and dangerous for everything else.

The question is never "which pattern is best?" — it's "which problems do I currently have, which of these patterns solves them, and what new complexity does adopting the pattern introduce?" Architecture is a trade-off, not a truth. The best front end architects are not the ones who know the most patterns. They're the ones who introduce the right pattern at the right moment and resist introducing it before the problem it solves is actually present.

The patterns in this lesson — Container/Presenter, Compound Components, Feature-Sliced Design, Event Bus, Islands/Server Components — are not a menu to order from. They're tools with specific appropriate uses. Knowing them all is the prerequisite. Knowing when each one earns its place is the skill. And that skill develops through the practice of naming pains specifically, solving them with the minimum complexity required, and resisting the architecture astronaut instinct to solve tomorrow's problems before today's are understood.

Quiz