The Frontend Architecture Review I Actually Use

Architecture review sounds grand until you are staring at a pull request that mostly changes routes, hooks, and a few components with suspiciously broad props.

The review I actually use is intentionally practical. It asks whether the change will be understandable, operable, and safe to extend after the happy-path demo is over.

Before opening files, I want a plain-language map of the change:

• What route or surface is changing?
• What data does it need?
• Which components own layout versus behavior?
• What state crosses boundaries?
• What can fail in production?

Routing decisions become architecture decisions quickly. A route determines data dependencies, loading boundaries, metadata, caching strategy, and error states.

I check whether each route has a clear owner:

• The page composes the experience.
• Layout components handle shared chrome.
• Feature components own specific product behavior.
• Leaf components stay reusable and boring.

 1  ## Route review
 2  - Does this route fetch only the data it needs?
 3  - Are loading and empty states visible in the tree?
 4  - Are metadata and canonical links handled?
 5  - Can the route be tested without mocking the whole app?

Data loading is where polished demos often hide risk. I look for duplicated requests, unclear caching, missing empty states, and errors that will become blank screens.

The review question is not "does it work locally?" It is "what happens when the service is slow, stale, empty, or wrong?"

State should live where the decision is made. If a value only controls a local disclosure, it should not become app-level state. If a value changes the URL, cache key, or product workflow, it probably needs a more durable boundary.

I scan for state that crosses too many layers:

• Props passed through components that do not use them.
• Context added before there are multiple real consumers.
• Client components wrapping server-only content.
• Derived state stored separately from its source.

type StateReviewQuestion =
  | "Who creates this state?"
  | "Who can update it?"
  | "What URL or server data should it sync with?"
  | "What breaks if it resets?";

Good component boundaries make the next change smaller. I look for components that mix too many jobs: fetching data, deciding layout, formatting content, managing interaction, and rendering presentation all at once.

A useful split is often simple:

• Container: gets data and chooses variants.
• Section: arranges a meaningful slice of the page.
• UI component: renders a reusable primitive.

Building components in isolation with Storybook makes this separation obvious. If a component only makes sense inside a specific data context, it is probably a feature component, not a reusable primitive.

Frontend architecture includes operations. I review anything that affects deploy confidence, observability, accessibility, and rollback safety.

My final pass checks:

1. Can the build catch broken content or imports?
2. Are important links generated from source data instead of typed by hand?
3. Do errors have enough context to debug?
4. Are expensive client-side dependencies justified?
5. Can this change be rolled back cleanly?

 1  # Frontend architecture review
 2  
 3  ## Routing
 4  - Clear route ownership
 5  - Metadata and canonical behavior handled
 6  - Loading, empty, and error states present
 7  
 8  ## Data
 9  - Fetching happens at the right boundary
10  - Caching assumptions are explicit
11  - Slow, empty, and failed responses are considered
12  
13  ## State
14  - State lives near the decision it supports
15  - URL state is represented in the URL
16  - Context is justified by real consumers
17  
18  ## Components
19  - Layout, behavior, and presentation are separated where useful
20  - Reusable components use design-system primitives
21  - Variants are explicit and typed
22  
23  ## Operations
24  - Links come from source data when possible
25  - Build verifies content and routes
26  - Accessibility and rollback risks are named

The checklist is not there to slow a team down. It is there to keep the expensive mistakes visible while the code is still cheap to change.