Guide Frontend Navigator

An agent that helps developers navigate complex frontend architectures, understand component hierarchies, trace data flows, and make informed decisions about frontend technology choices and patterns.

When to Use This Agent

Choose Frontend Navigator when:

• Understanding large frontend codebases with complex component trees
• Tracing data flow through state management, props, and context
• Evaluating frontend architecture patterns for specific use cases
• Navigating between different frontend frameworks and their ecosystems
• Making technology decisions about frontend tooling and libraries

Consider alternatives when:

• Writing specific frontend components (use a frontend development agent)
• Designing UI/UX without code (use a design agent)
• Building backend APIs for frontend consumption (use a backend agent)

Quick Start

Copy
# .claude/agents/guide-frontend-navigator.yml
name: Frontend Navigator
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a frontend architecture navigator. Help developers
  understand complex frontend codebases, trace data flows,
  evaluate patterns, and make informed technology decisions.
  Map component hierarchies and explain how pieces connect.

Example invocation:

Copy
claude --agent guide-frontend-navigator "Map the component
  hierarchy and data flow for our checkout page. Trace how
  cart state flows from the store through components to the
  payment form submission."

Core Concepts

Frontend Architecture Layers

Routing Layer     → URL-to-component mapping, code splitting
  ↓
Layout Layer      → Page structure, navigation, headers
  ↓
Feature Layer     → Business logic components, state management
  ↓
UI Component Layer → Reusable UI primitives (buttons, inputs, cards)
  ↓
Utility Layer     → Hooks, helpers, formatters, validators

State Management Patterns

Pattern	Scope	Best For	Examples
Component state	Single component	Form inputs, toggles	useState
Context	Component subtree	Theme, auth, locale	React Context
Global store	Entire application	Cart, user data	Redux, Zustand
Server state	Cache of remote data	API responses	React Query, SWR
URL state	Shareable state	Filters, pagination	Search params

Component Organization

src/
├── components/          # Reusable UI components
│   ├── ui/             # Primitives (Button, Input, Card)
│   └── layout/         # Layout components (Header, Sidebar)
├── features/           # Feature-specific components and logic
│   ├── auth/           # Login, signup, password reset
│   ├── checkout/       # Cart, payment, confirmation
│   └── dashboard/      # Dashboard views and widgets
├── hooks/              # Custom React hooks
├── stores/             # State management
├── utils/              # Pure utility functions
├── api/                # API client and query definitions
└── pages/              # Route-level page components

Configuration

Parameter	Description	Default
framework	Frontend framework	React
state_management	State management approach	Zustand + React Query
styling	CSS approach	Tailwind CSS
routing	Routing library	React Router / Next.js
bundler	Build tool	Vite
component_library	UI component library	None (custom)
testing	Testing tools	Vitest + Testing Library

Best Practices

1. Map the component tree before modifying unfamiliar code. Open the page in the browser, use React DevTools (or framework equivalent) to visualize the component hierarchy, and note which components manage state versus which receive props. Understanding the tree structure prevents changes that accidentally break data flow or render performance.

2. Separate server state from client state. API data (server state) and UI state (client state) have different lifecycles and should be managed differently. Use React Query or SWR for server state (caching, refetching, invalidation). Use Zustand or Context for client state (theme, sidebar open, form draft). Mixing them in a single store creates unnecessary complexity and cache invalidation bugs.

3. Co-locate code by feature, not by type. A feature folder containing its components, hooks, API calls, and tests is easier to navigate than searching across components/, hooks/, api/, and tests/ directories. When a feature is deleted, remove one folder instead of hunting through six directories. Feature co-location scales better as the application grows.

4. Trace data flow from source to render before debugging. When a component shows wrong data, trace backward: which prop or state variable renders it? Where does that value come from? What updates it? This systematic tracing finds bugs faster than random inspection. Use browser DevTools to set breakpoints in effects and state updates to watch data flow in real time.

5. Use the URL as the source of truth for shareable state. Filters, sort order, pagination, search queries, and selected tabs should live in URL search parameters. This makes states shareable (send a link), bookmarkable, and compatible with browser back/forward. Components read state from the URL and dispatch updates by modifying URL parameters.

Common Issues

Component re-renders cause performance issues. Use React DevTools Profiler to identify which components re-render and why. Common fixes: memoize expensive computations with useMemo, prevent unnecessary child re-renders with React.memo, move state closer to the components that use it, and split large context providers into smaller ones so updates don't re-render the entire tree.

State management becomes confusing with multiple overlapping stores. Establish clear rules: server data goes in React Query, form state stays local, global UI state (theme, auth) goes in Zustand, URL state goes in search params. When developers ask "where should this state live?" the rules should give a clear answer. State that doesn't fit the rules indicates a need to update the rules, not to create a new store.

Large bundle size causes slow initial page load. Implement code splitting at the route level so each page loads only its own code. Use dynamic import() for heavy features (chart libraries, editors) that aren't needed immediately. Audit dependencies with npx webpack-bundle-analyzer or npx vite-bundle-visualizer. A single unused import of a large library can add hundreds of KB to the bundle.