Expert Architecture Bot

Modern application architecture agent specializing in App Router patterns, server component strategies, and enterprise-scale frontend modernization.

When to Use This Agent

Choose this agent when you need to:

• Plan a migration from Pages Router to App Router in a Next.js application
• Design server component boundaries and data fetching strategies
• Architect nested layouts, parallel routes, and streaming patterns
• Evaluate rendering strategies (static, server, client) for different page types

Consider alternatives when:

• Your migration involves cloud infrastructure rather than frontend architecture (use Cloud Migration Pro)
• You need to modernize a non-JavaScript legacy backend system (use Specialist Legacy Modernizer)

Quick Start

Configuration

Copy
name: expert-architecture-bot
type: agent
category: modernization

Example Invocation

Copy
claude agent:invoke expert-architecture-bot "Design the App Router architecture for an e-commerce platform with product catalog, cart, and checkout"

Example Output

Architecture Plan: E-Commerce App Router
==========================================

Route Structure:
  app/
  ├── (marketing)/         # Static pages, ISR
  │   ├── page.tsx         # Homepage - static + revalidate 1h
  │   └── about/page.tsx   # Static generation
  ├── (shop)/              # Dynamic shopping experience
  │   ├── layout.tsx       # Cart context provider (client boundary)
  │   ├── products/
  │   │   ├── page.tsx     # Server component - direct DB query
  │   │   └── [slug]/
  │   │       └── page.tsx # generateStaticParams + ISR 30min
  │   └── cart/
  │       └── page.tsx     # Client component - real-time state
  ├── checkout/
  │   ├── layout.tsx       # Isolated layout, no nav
  │   └── page.tsx         # Server component + client form
  └── api/
      └── webhooks/
          └── route.ts     # Stripe webhook handler

Component Boundaries: 12 server, 5 client
Streaming: Suspense on product listings and recommendations
Caching: Static params for top 500 products, ISR for rest

Core Concepts

Rendering Strategy Overview

Aspect	Details
Static Generation	Marketing pages, product pages with ISR
Server Components	Data fetching, layout rendering, SEO content
Client Components	Interactive widgets, forms, real-time state
Streaming	Suspense boundaries for slow data sources
Edge Functions	Middleware for auth, geolocation, A/B testing
ISR	Incremental Static Regeneration for catalog pages

Component Boundary Architecture

┌─────────────┐     ┌─────────────┐
│  Root        │────▶│  Nested      │
│  Layout (SC) │     │  Layout (SC) │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Page        │────▶│  Interactive │
│  (Server)    │     │  (Client)    │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
routerType	enum	"app"	Target router: app or pages (for migration planning)
renderingDefault	enum	"server"	Default rendering: server, static, or client
revalidateInterval	number	3600	Default ISR revalidation interval in seconds
streamingEnabled	boolean	true	Enable Suspense-based streaming for slow queries
typescriptStrict	boolean	true	Enforce strict TypeScript in all generated components

Best Practices

1. Push Client Boundaries as Low as Possible Mark components with 'use client' only at the leaf level where interactivity is required. Keep layouts, pages, and data-fetching components as server components. Every unnecessary client component increases the JavaScript bundle shipped to browsers.

2. Use Route Groups to Organize Without Affecting URLs Parenthesized route groups like (marketing) and (shop) let you apply different layouts, loading states, and error boundaries to logical sections without adding path segments. This keeps URLs clean while enabling architectural separation.

3. Implement Suspense Boundaries Around Slow Data Sources Wrap server components that perform expensive database queries or external API calls in Suspense boundaries with meaningful skeleton loading states. This allows the page shell to render immediately while slow data streams in progressively.

4. Generate Static Params for High-Traffic Dynamic Routes Use generateStaticParams to pre-render your most visited product pages, blog posts, or category listings at build time. Combine with ISR to keep content fresh without sacrificing the performance benefits of static generation.

5. Isolate Third-Party Scripts in Client Component Wrappers Analytics, chat widgets, and ad scripts must run in client components. Create dedicated wrapper components with 'use client' that lazy-load these scripts. This prevents third-party code from blocking server-side rendering.

Common Issues

1. Server component accidentally imports a client-only library Libraries like framer-motion or recharts require browser APIs and fail during server rendering. Move the import into a dedicated client component file marked with 'use client' and import that wrapper from your server component.

2. Nested layouts cause unexpected full-page re-renders Layouts in the App Router are supposed to persist across navigation. If your layout re-renders on every route change, check whether you are passing dynamic props or using hooks at the layout level. Layouts should be static shells that delegate dynamic content to child pages.

3. API route handlers return HTML instead of JSON The route.ts file must export named HTTP method handlers (GET, POST) rather than default exports. Ensure you return NextResponse.json() rather than rendering JSX. API routes in the App Router do not support React components.