nextjs-16-architecture

# Next.js 16 Architecture

Architecture patterns for Next.js 16 with Cache Components and feature-based organization.

## Core Philosophy

1. **Dynamic by default, cache what you choose** - Use `"use cache"` explicitly
2. **Fetch in smallest possible component** - Don't prop-drill data
3. **Keep everything static, stream only dynamic** - Use Suspense for dynamic parts
4. **Suspense boundaries high** - Place in pages/layouts, not feature components

## Quick Reference

### Feature Folder Structure
```
features/{feature}/
├── components/
│   ├── server/       # Async data-fetching components
│   ├── client/       # 'use client' interactive components
│   └── skeletons/    # Loading states for Suspense
├── data/             # Database queries (SELECT, INSERT, UPDATE, DELETE)
├── actions/          # Server Actions ('use server' + cache invalidation)
├── types/            # TypeScript types (1 file = 1 type)
├── schemas/          # Zod schemas (1 file = 1 schema)
├── hooks/            # Client-side hooks
└── lib/              # Feature-specific utilities
```

### File Naming
| Type | Pattern | Example |
|------|---------|---------|
| Server component | `kebab-case.tsx` | `agent-header.tsx` |
| Client component | `kebab-case.tsx` | `login-form.tsx` |
| Skeleton | `{name}-skeleton.tsx` | `agent-header-skeleton.tsx` |
| GET query | `get-{entity}.ts` | `get-agent.ts` |
| GET multiple | `get-{entities}.ts` | `get-agents.ts` |
| CREATE | `create-{entity}.ts` | `create-agent.ts` |
| DELETE | `delete-{entity}.ts` | `delete-agent.ts` |
| Server Action | `{verb}-{entity}-action.ts` | `delete-agent-action.ts` |

### Cache Pattern
```typescript
// Data file (SELECT with cache)
export async function getEntity(id: number) {
  "use cache";
  cacheTag(`entity-${id}`);
  cacheLife("hours");
  return await db.select()...
}

// Server Action (mutation + invalidation)
"use server";
export async function deleteEntityAction(id: number) {
  await deleteEntity(id);
  updateTag(`entity-${id}`);