Frontend Architecture

Frontend Architecture

Concept of the skill

Frontend architecture is the discipline of deciding, on purpose, where code lives, what is allowed to depend on what, who owns mutable state, and how runtime boundaries are reflected in the module graph. Its central insight is that the folder tree you see is only the surface; the architecture that actually governs changeability is the import graph beneath it.

The skill works at four structural layers. Module organization chooses an organizing model - feature-sliced (features/<feature>/{ui,model,api}), layered (components/, hooks/, services/, pages/), domain-driven (domains/<domain>/{ui,logic,data}), route-colocated, or package/workspace-based - and accepts its trade-offs as the codebase scales. Component layering separates pure primitives, feature-composed components, and connected or route-level components, watching the composed-to-connected boundary where most dependency tangles begin. State ownership decides location, normalization, derivation, write ownership, and cache ownership for each piece of state, keeping remote server state separate from ephemeral client state. Import-direction enforcement turns the desired structure into a checkable rule: shared modules do not import features, features do not import sibling features, features do not import route files, and clients do not pull server-only modules into the browser.

This is not a folder-naming skill. The goal is an import graph that makes change cheap: feature code is cohesive and removable, shared primitives are truly feature-agnostic, route files are thin orchestration or registration points, state has one owner, and public module APIs prevent consumers from depending on internal file layout.

Coverage

Boundary Triage

Before reorganizing, classify the decision:

Module Organization

The common organizing models each make a trade:

• Feature-sliced: code is grouped by user or domain capability, e.g. features/orders/{ui,model,api}. It maximizes removability and local reasoning. The risk is accidental feature-to-feature imports unless boundaries are enforced.
• Layered: code is grouped by technical kind, e.g. components/, hooks/, services/, pages/. It is easy at small scale and often degrades at large scale because one feature's logic is scattered across every layer.
• Domain-driven: code is grouped by durable business domain, e.g. domains/billing/{ui,logic,data}. It works when domain ownership is stable and teams need clear domain seams.
• Route-colocated: framework route folders colocate UI, loaders, actions, and tests near a URL segment (the metaframework default - Next.js App Router, Remix, SvelteKit). This improves locality but must not turn route files into giant connected components; route files should orchestrate feature modules and register routes, not become the only place domain logic can live. Route colocation and feature-slicing are not mutually exclusive: a common scaled shape keeps thin route entries (loader + page shell) in the route tree and imports the real UI and logic from features/.
• Package/workspace-based: larger products split vertical slices or shared libraries into packages. This gives stronger boundaries and build-time ownership, but costs more ceremony and versioning. At the far end this extends to micro-frontends / module federation, where boundaries become deployment boundaries across applications; that cross-application split is a heavier decision (independent deploys, runtime composition, versioned contracts between apps) than the single-application import graph this skill mostly targets - reach for it only when team and deploy independence, not just code organization, is the driver.

Feature-Sliced Design (FSD) is a formal version of the feature-sliced model. Its layer ladder - app -> pages -> widgets -> features -> entities -> shared - carries one load-bearing rule: code may import only from lower layers, never upward or sideways into another slice at the same layer. In FSD, entities are business domain models (e.g. User, Product, Order) - their types, domain logic, and the UI that represents the entity - while features own user actions and the interaction/data-fetching that performs them; do not mislabel entities as "data-fetching layers." Each slice should expose a public API (usually an index barrel) and consumers should import from that public entry, not from internal files. The public API rule matters as much as the folder names: without it, auto-imports and direct deep imports make refactors expensive because other features depend on internals.

Use the repo's existing model when it is coherent. Change models only when the current import graph proves the current model cannot support the next change.

Shared Promotion Rule

Code starts feature-local by default. Promote it to shared only when all of these are true:

• It has at least two independent consumers, OR it fills a clear platform role (app shell, design-system bridge, cross-cutting logging/analytics wrapper, framework adapter) whose home is the platform layer regardless of current consumer count. The default honest trigger is the second real consumer, not a guess that "this might be reused"; the platform-role case is the deliberate single-consumer exception for code whose owner is genuinely the platform, not a loophole for promoting speculative feature code.
• Its props, names, imports, tests, and state do not mention a feature-specific domain.
• It receives behavior through props, callbacks, slots, or composition rather than reading a feature store or API directly.
• It can be moved or versioned without moving feature policy with it.

"Reusable" is not enough. Promoting too early produces a shared/ full of single-consumer code coupled to one feature's assumptions (a pre-emptive back-edge); promoting too late produces a copy-paste fork. A billing-specific CancelSubscriptionDialog that calls a billing mutation belongs in features/billing/. If reuse is real, split it into a shared props-only ConfirmDialog shell plus a billing-owned connected wrapper that passes onConfirm. If promotion would require the candidate to import anything feature-specific, it is not shared yet - keep it local or refactor the feature coupling out first.

Component Layering

Separate components by dependency and ownership, not by visual complexity:

The composed-to-connected boundary is the most common source of dependency tangles. A "shared" composed component that quietly imports a feature store creates a back-edge that breaks the graph. Extract the data-free shell; keep the connected wrapper at the feature or route boundary.

In stacks with React Server Components or similar server/client module splits, the connected layer also has a runtime seam. The architecture concern here is not the full RSC data/caching design; it is that server-only modules, client-only modules, and route orchestration must have import rules. A route may render a client island or a server component; a client island must not import server-only code; shared primitives should stay server-renderable unless they genuinely need hooks, event handlers, refs, or browser APIs. The reason to push 'use client' toward interactive leaves is mechanical: it marks the file as a client entry point and pulls the modules it imports, and their transitive dependencies, into the client side of the dependency tree. A broad page-level directive can turn otherwise server-renderable utilities and UI into client code by import reachability alone. The architectural shape this favors is a thin connected Server Component that fetches data and passes it into small Client Component islands - which inverts the old single-page-app default that every data-connected component is necessarily a client component. Load the server-components-design and client-server-boundary skills for the detailed boundary.

State Shape

State shape decisions span five axes:

React's own state guidance is architectural at scale: avoid contradictory state, redundant state, duplicated state, and deeply nested state. Those rules map directly to this skill's axes. A deeply nested dashboard object that every widget subscribes to will re-render unrelated widgets; normalize entities, select narrowly, and measure the representative interaction so the re-render path can be explained.

Server state (data fetched from an API or database, cache-managed, invalidated by remote writes) and client state (UI-only, ephemeral, local to interaction) are different problems. The load-bearing rule is one cache/read owner per data source: each remote resource is fetched, cached, deduplicated, and revalidated through a single mechanism, so exactly one place knows the data is stale. That owner is a framework server cache / RSC read path when the data is rendered on the server, or a client server-state library such as TanStack Query, SWR, or RTK Query when browser-side caching is appropriate. Note one trap when reaching for normalization here: RTK Query is a document cache keyed per query endpoint+args and deliberately does not normalize or de-duplicate entities across queries - two queries returning the same entity hold two independent copies. If you genuinely need a single normalized entity store shared across queries, that is the job of a normalized Redux slice (or a normalizing cache), not of RTK Query's built-in cache. Reserve global client stores such as Redux, Zustand, Jotai, or Context for genuinely cross-cutting UI state (theme, current user display state, route/session UI, feature flags), not as a hand-rolled server cache. Putting server data into that same global store - a second cache owner for one source - is the single most common cause of cache-invalidation bugs that present as rendering bugs.

React Compiler can reduce the need for manual useMemo, useCallback, and React.memo, but it does not fix broad state ownership, duplicated server data, or a store subscription that invalidates too much of the tree. Treat compiler optimization as performance assistance, not as an architecture substitute.

Import Direction

Import direction enforces the architecture. Write rules in the shape of the repo, for example:

• shared/ may not import from features/, pages/, routes/, or app-specific stores.
• A feature may import shared/ and its own internals, but not a sibling feature's internals.
• Cross-feature coordination goes through a route/registration point, event contract, shared abstraction, or backend/API contract, not direct imports.
• Route files may orchestrate feature modules, but feature modules may not import route files.
• Public module APIs are the only allowed cross-slice entry points; direct imports from another slice's internal folders are violations.
• Client-marked modules may not import server-only modules; server-only modules should be guarded by framework conventions or guard imports where available.

Use an enforcer that matches the repo:

Without enforcement, the structure degrades within months: one shortcut import becomes normal, then the dependency graph goes cyclic and features can no longer be removed in isolation.

Philosophy of the skill

The folder structure is not the architecture; the import graph is. A pretty folder tree with cyclic imports between features is architecturally worse than a flat folder with strict one-way dependencies. Optimize for "where would I look for this" and "what changes together stays together" over imposed taxonomy.

Code should become shared later than teams think. Premature shared code is often feature code wearing a generic name. Promote only the stable, data-free, feature-agnostic shell - or code whose owner is genuinely the platform; leave policy, fetching, mutations, and permissions near the feature that owns them.

Server state and client state are different problems. Mixing them in a single global store creates cache-invalidation bugs that look like rendering bugs. Use the same cache owner for fetching, caching, and revalidating server data; reserve global client state for genuinely cross-cutting UI concerns.

Boundaries are kept by machines, not intentions. Any architectural rule a human is expected to remember at review time will be broken under deadline. The rules that survive are the ones a linter, graph check, or package boundary makes cheaper to obey than to violate - architecture is the set of constraints you have made cheaper to obey than to violate.

Verification

• An import-boundary linter or dependency graph check is configured and CI fails on violations; the linter config asserts the rules below, not just that some plugin is installed.
• The rules cover at least shared-to-feature, feature-to-feature, route-to-feature direction, public-API-only cross-slice imports, and client-to-server-only imports where the stack has split runtimes.
• Every feature folder can be removed without touching code outside it, except a single registration point such as a route table, feature flag map, app shell, or package export.
• A new developer can name where any given piece of code lives within thirty seconds of being told the feature name and the kind of thing (UI, model/state, data/read, mutation/write, route registration, test).
• Shared primitives contain no feature-specific names in props, tests, imports, or story examples; a grep for feature names in shared/ returns nothing intentional.
• Cross-slice consumers import from public API barrels/entry points, not another slice's internal file paths; a grep for deep imports past a slice's index from outside that slice returns nothing.
• Server state is owned by one cache/read mechanism per data source; client code does not maintain several manual copies of the same remote entity - counting fetch call sites in client code returns roughly the number of distinct endpoints, not multiples per endpoint.
• Derived values are computed from source state rather than stored in parallel; duplicated or deeply nested state has an explicit reason.
• TypeScript type-only imports are marked import type so the enforced runtime import graph is not muddied by false-positive circularities from type references.
• Re-render counts on a representative interaction can be measured and explained; broad invalidation is traced to state ownership or subscription granularity, not patched with blind memoization.
• In React Server Components or similar stacks, "use client" sits at intentional interactive boundaries, not at broad page/layout roots by default; a grep for the directive does not land at the top of large files that contain no interactivity. Detailed RSC/security/cache review is delegated to server-components-design and client-server-boundary.
• Tests follow the layering: primitives tested in isolation, feature-composed components tested near the feature, connected/route components tested with mocked data or server-state layer, and no test reaches across feature internals directly.

Do NOT Use When

• The decision is visual rather than structural: color, type, spacing, motion. Use visual-design-foundations, color-system-design, or typography-system.
• The work is publishing or versioning a shared component library across multiple applications. Use design-system-architecture.
• The problem is the public API of a reusable component module: compound components, slots, headless APIs, render props, polymorphic as/asChild, or accessibility wiring. Use design-module-composition and a11y as needed.
• The task is choosing or migrating a specific framework, styling tactic, or build tool. This skill can keep boundaries invariant across that choice, but it does not pick React vs Solid, Webpack vs Vite, or Tailwind vs CSS-in-JS.
• The task is choosing a rendering model such as SSR, SSG, ISR, CSR, RSC, streaming SSR, edge rendering, or PPR. Use rendering-models.
• The task is detailed React Server Component read-path design, Suspense placement, data security, DTO filtering, or cache/freshness planning. Use server-components-design.
• The problem is what values can cross the server/client boundary, what is serialized, what is trusted, or whether secrets/raw records leak into the client. Use client-server-boundary.
• The decision is where state lives, how it propagates, or URL-as-state across the app generally (state placement), or the tactical state-update mechanism (Redux vs Zustand). Use state-management for placement/propagation; tactical library choice is a non-architectural call this skill does not make.
• You are designing the backend API the frontend consumes. Use api-design or system-interface-contracts.
• The work is behavior-preserving restructuring of existing code with no new architecture decision. Use refactor, and verify with this skill only if module boundaries are the refactor target.