app/
  (group)/          ← Route groups (no URL segment)
    layout.tsx      ← Shared layout
    page.tsx        ← Route page (server component by default)
    loading.tsx     ← Suspense fallback
    error.tsx       ← Error boundary ('use client' required)
  api/
    route.ts        ← API routes (GET, POST, etc. as named exports)
components/
  ui/               ← Primitive UI: Button, Card, Badge, etc.
  feature/          ← Feature-specific composed components
lib/
  utils/            ← Pure utility functions (no React)
  types/            ← TypeScript type definitions
  actions/          ← Server Actions
hooks/              ← Custom React hooks (client-side)

// ✅ Always type function return values explicitly
async function getUser(id: string): Promise<User | null> { ... }

// ✅ Use `type` for unions/intersections, `interface` for object shapes
type Status = 'pending' | 'active' | 'archived'
interface UserProfile { id: string; email: string; }

// ✅ Never use `any` — use `unknown` and narrow
function parse(input: unknown): string {
  if (typeof input !== 'string') throw new Error('Expected string')
  return input
}

// ❌ Never
const data: any = response.json()

// ✅ Type API responses with Zod
const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() })
type User = z.infer<typeof UserSchema>

// app/api/users/route.ts
import { NextResponse } from 'next/server'
import { z } from 'zod'

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
})

export async function POST(request: Request) {
  const body = await request.json()
  const result = CreateUserSchema.safeParse(body)
  if (!result.success) {
    return NextResponse.json({ error: result.error.flatten() }, { status: 422 })
  }
  // ... proceed with result.data (fully typed)
}

// ✅ Server Component data fetching — no useEffect
export default async function UsersPage() {
  const users = await getUsers() // Direct async call in component
  return <UserList users={users} />
}

// ✅ Parallel fetching with Promise.all
const [user, posts] = await Promise.all([getUser(id), getPosts(id)])

// ✅ Use `cache` for request deduplication
import { cache } from 'react'
const getUser = cache(async (id: string) => { ... })

// ✅ Never throw in Server Components — use error.tsx
// app/(main)/error.tsx
'use client'
export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>
}

// ✅ API routes always return typed error shapes
return NextResponse.json({ error: 'Not found', code: 'USER_NOT_FOUND' }, { status: 404 })