project-root/
├── app/                        # Next.js App Router
│   ├── (site)/                 # Published content routes
│   ├── (draft)/                # Preview routes
│   └── api/                    # API routes
├── components/
│   ├── block/                  # Content block components
│   ├── content-area/           # Content area mapper
│   ├── draft/                  # Draft mode components
│   ├── layout/                 # Header, Footer
│   ├── ui/                     # Radix UI components
│   └── visual-builder/         # Visual Builder wrapper
├── lib/
│   ├── optimizely/
│   │   ├── fetch.ts            # GraphQL client
│   │   ├── queries/            # GraphQL queries
│   │   ├── types/
│   │   │   ├── generated.ts    # Auto-generated (DO NOT EDIT)
│   │   │   ├── block.ts        # Block base types
│   │   │   ├── experience.ts   # Visual Builder types
│   │   │   └── typeUtils.ts    # Type helpers
│   │   └── utils/
│   │       └── language.ts     # Locale utilities
│   └── utils/                  # General utilities
├── public/                     # Static assets
├── .claude/                    # Claude skills
└── docs/                       # Documentation

// Use @ alias for root imports
import { optimizely } from '@/lib/optimizely/fetch'
import { cn } from '@/lib/utils'
import { HeroBlock } from '@/components/block/hero-block'

// 1. React/Next.js imports
import { Suspense } from 'react'
import { Metadata } from 'next'

// 2. Third-party imports
import { cva } from 'class-variance-authority'

// 3. Internal imports (@ alias)
import { optimizely } from '@/lib/optimizely/fetch'
import { cn } from '@/lib/utils'

// 4. Types
import type { BlockBase } from '@/lib/optimizely/types/block'

// Server component - async data fetching
export default async function PageComponent({
  params,
}: {
  params: Promise<{ locale: string }>
}) {
  const { locale } = await params
  const { data } = await optimizely.GetStartPage({ locales: locale })

  return <div>{/* render */}</div>
}

'use client'

import { useState, useEffect } from 'react'

export default function ClientComponent({ data }: Props) {
  const [state, setState] = useState()

  return <div>{/* interactive */}</div>
}

// Use cn() for conditional classes
import { cn } from '@/lib/utils'

<div className={cn(
  'container mx-auto px-4',
  isFirst && 'pt-20',
  className
)} />

import { cva } from 'class-variance-authority'

const buttonVariants = cva('inline-flex items-center', {
  variants: {
    variant: {
      default: 'bg-primary text-white',
      outline: 'border border-input',
    },
    size: {
      default: 'h-10 px-4',
      sm: 'h-9 px-3',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
})

// Always import from generated types
import { HeroBlock as HeroBlockProps } from '@/lib/optimizely/types/generated'
import { Locales } from '@/lib/optimizely/types/generated'

import { BlockBase } from '@/lib/optimizely/types/block'

type ExtendedProps = GeneratedProps & BlockBase

import { castContent, SafeContent } from '@/lib/optimizely/types/typeUtils'

const item = castContent<NavItem>(content as SafeContent, 'NavItem')
if (!item) return null

const { data, errors } = await optimizely.getPageByURL({...})

if (errors) {
  console.error(errors)
  return notFound() // or handle appropriately
}

if (!data?.CMSPage?.item) {
  return notFound()
}

try {
  const response = await fetch(endpoint, {...})
  const result = await response.json()
  return result
} catch (e) {
  if (isVercelError(e)) {
    throw { status: e.status || 500, message: e.message }
  }
  throw { error: e }
}

// Default: force-cache for published content
cache: 'force-cache'

// Preview: no-store for draft content
cache: 'no-store'

// Cache tags for granular invalidation
next: { tags: ['optimizely-content', 'optimizely-header'] }

import { revalidatePath, revalidateTag } from 'next/cache'

// Revalidate by path
await revalidatePath(urlWithLocale)

// Revalidate by tag
await revalidateTag('optimizely-header')

# Required
OPTIMIZELY_API_URL=https://cg.optimizely.com/content/v2
OPTIMIZELY_SINGLE_KEY=your-api-key

# Preview/Draft Mode
OPTIMIZELY_PREVIEW_SECRET=your-preview-secret

# Revalidation Webhook
OPTIMIZELY_REVALIDATE_SECRET=your-webhook-secret

# Optional
OPTIMIZELY_START_PAGE_URL=/start-page  # For hierarchical URL normalization

feat: add new block component
fix: resolve caching issue in draft mode
docs: update README
refactor: simplify content area mapper