guardian-framework 0.1.25 → 0.1.27

package/templates/pi/skills/nextjs-enterprise-codegen.md

@@ -1,383 +1,393 @@
 ---
 name: nextjs-enterprise-codegen
-description: Full reference for Next.js enterprise code generation with DDD + Clean Architecture. Covers module structure, server/client boundary, data fetching, state management, design system integration, error handling, testing, security, performance, and accessibility. Loaded on-demand via agents/nextjs-codegen.md skill.
+description: "Full reference for Next.js enterprise code generation with DDD + Clean Architecture. Every module uses 4 DDD layers: domain/, application/, infrastructure/, interfaces/. Covers User Intents, App Shell, design system, navigation philosophy, offline strategy, server/client boundary, and testing. Loaded on-demand via agents/nextjs-codegen.md skill."
 ---
 
 # Next.js Enterprise Code Generation — DDD + Clean Architecture
 
 > Canonical skill for generating production-grade Next.js code with DDD patterns.
-> All code MUST follow these patterns. Validators enforce compliance.
+> **Every module MUST follow the 4 DDD layers below.**
+> Validators enforce compliance.
 >
-> For design system and styling patterns, see: `.pi/skills/design-system-enterprise-codegen.md` — tokens, CSS adapters, theming, component API contracts
+> For design system and styling patterns, see: `.pi/skills/design-system-enterprise-codegen.md`
 
 ---
 
-## 1. Project Structure — DDD with Next.js App Router
+## 1. DDD Module Structure — The 4 Layers
+
+Every feature module uses exactly this structure:
 
 ```
 src/
-  module/                              # One bounded context
-    domain/                            # Pure business logic, zero framework imports
-      entity.ts                        # Domain entities with encapsulated state
-      value.ts                         # Immutable value objects
-      events.ts                        # Domain events
-      errors.ts                        # Typed error classes
-    application/                       # Application logic
-      store.ts                         # Zustand / Jotai state (client-only)
-      actions.ts                       # Server Actions (server-only)
-      queries.ts                       # React Query hooks for data fetching
-      dto.ts                           # Command/Query DTOs
-    infrastructure/                    # External adapters
-      api-client.ts                    # fetch wrapper, error handling, retry
-      auth.ts                          # Auth provider SDK wrapper
-      analytics.ts                     # Analytics SDK wrapper
-    interfaces/                        # UI layer
-      page.tsx                         # App Router page (default: Server Component)
-      component.client.tsx             # Client Component with 'use client'
-      layout.tsx                       # Layout wrapper
-  shared/                              # Cross-module shared code
-    ui/                                # Design system components
-      button/
-      card/
-      modal/
-    lib/                               # Shared utilities
-    hooks/                             # Shared React hooks
+  collaboration/                       # One bounded context / feature
+    domain/                            # Layer 1: Pure business logic
+      types.ts           #   Types, interfaces, enums (zero React)
+      errors.ts          #   Typed error classes
+      notification.ts    #   Domain value objects
+    application/                       # Layer 2: State + use cases
+      store.ts           #   Zustand store
+      actions.ts         #   Server Actions
+    infrastructure/                    # Layer 3: External adapters
+      api.ts             #   API client (fetch)
+    interfaces/                        # Layer 4: UI components
+      thread-panel.tsx                 #   React components
+      comment-list.tsx
 ```
 
-### Dependency Rule
+### Dependency Rule (Inward)
+
 ```
 domain → application → infrastructure → interfaces
-                  ↕
-            shared/ (no framework deps)
 ```
 
-- **domain/** — zero React/Next.js imports. Pure TypeScript.
-- **application/** — imports from domain. May import from `shared/lib/`.
-- **infrastructure/** — imports from domain + application. Wraps external SDKs.
-- **interfaces/** — imports from application. Contains all React/Next.js code.
+- `domain/` — **ZERO React/Next.js imports.** Pure TypeScript. No `'use client'`.
+- `application/` — imports from `domain/`. Stores, actions, server actions.
+- `infrastructure/` — imports from `domain/` and `application/`. API clients, SDK wrappers.
+- `interfaces/` — imports from `application/`. **Only this layer has React components.**
+
+### What goes where — specific rules
+
+| DO put in `domain/` | DO NOT put in `domain/` |
+|--------------------|------------------------|
+| TypeScript interfaces and types | React components |
+| Error classes (`class NotFoundError`) | Zustand stores |
+| Value objects (`class Money`) | `useState`, `useEffect` |
+| Enum definitions (`enum Status`) | Server Actions (`'use server'`) |
+| Pure functions (no side effects) | API fetch calls |
+| Constants and configuration | CSS, Tailwind classes |
+
+| DO put in `application/` | DO NOT put in `application/` |
+|-------------------------|------------------------------|
+| Zustand stores | React components |
+| Server Actions (`'use server'`) | API fetch implementation |
+| React Query hooks | UI state like `isOpen`, `isVisible` |
+| Command/Query DTOs | JSX markup |
+
+| DO put in `infrastructure/` | DO NOT put in `infrastructure/` |
+|----------------------------|--------------------------------|
+| API client functions (`fetch`, `axios`) | React components |
+| localStorage/cookie wrappers | Store logic |
+| Auth provider SDK wrappers | Domain types (import them) |
+| Analytics SDK wrappers | UI state |
+
+| DO put in `interfaces/` | DO NOT put in `interfaces/` |
+|------------------------|-----------------------------|
+| Page components (`page.tsx`) | API fetch calls |
+| Client components (`*.client.tsx`) | Domain types (import them) |
+| Layout components | Business logic |
+| UI state (`useState` for modals) | Server Actions (call them, don't define) |
 
 ---
 
-## 2. Server/Client Boundary
-
-This is the most critical architectural decision in Next.js. Get it wrong and you lose the benefits of both paradigms.
+## 2. Domain Layer — Pure Business Logic
 
-### What goes where
+The domain layer has zero framework dependencies. It defines the types, errors, and value objects that the rest of the module uses.
 
-| Layer | Renders on | 'use client'? | Can use |
-|-------|-----------|---------------|---------|
-| `interfaces/page.tsx` | Server | No | `async`, `cookies()`, `headers()`, direct DB |
-| `interfaces/*.client.tsx` | Client | Yes | `useState`, `useEffect`, `onClick`, browser APIs |
-| `application/store.ts` | Client | Depends | Zustand, Jotai |
-| `application/actions.ts` | Server | No | `'use server'`, `revalidatePath()` |
-| `application/queries.ts` | Client | Yes | React Query, SWR |
-| `domain/`, `infrastructure/` | Both | No | Pure TS, fetch |
-
-### Pattern: Island Architecture
+```typescript
+// collaboration/domain/types.ts
+export interface Thread {
+  id: string;
+  knowledgeNodeId: string;
+  title: string;
+  createdAt: string;
+  createdBy: User;
+  replyCount: number;
+  lastActivityAt: string;
+}
 
+export interface Comment {
+  id: string;
+  threadId: string;
+  body: string;
+  mentions: string[];
+  createdAt: string;
+  createdBy: User;
+}
 ```
-┌─────────────────────────────────────────┐
-│ page.tsx (Server Component)             │
-│  <header>Static header</header>         │
-│  <ProductList>                           │
-│    {products.map(p => <ProductCard/>)}  │  ← Server-rendered
-│  </ProductList>                          │
-│  <CheckoutButton.client.tsx>            │  ← Client island
-│    <AddToCartButton/>                   │
-│    <PriceSummary/>                      │
-│  </CheckoutButton.client.tsx>           │
-└─────────────────────────────────────────┘
-```
-
-### Rules
-- ✅ Default to Server Components. Add `'use client'` only when you need interactivity.
-- ✅ Push client state DOWN to the leaf components that need it.
-- ✅ Use Server Actions for mutations, client handlers for optimistic updates.
-- ❌ Never put `'use client'` on a page wrapper — only on interactive islands.
-- ❌ Never import server-only code (actions, DB queries) in client components.
-
----
-
-## 3. Data Fetching Patterns
-
-### Server Component Fetch (Default)
 
 ```typescript
-// interfaces/products/page.tsx — Server Component, async
-import { ProductService } from '../../application/actions';
+// collaboration/domain/errors.ts
+export class CommentError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly retriable: boolean = false,
+  ) {
+    super(message);
+    this.name = 'CommentError';
+  }
 
-export default async function ProductsPage() {
-  const products = await ProductService.list();  // Direct call, no API route
+  static saveFailed(): CommentError {
+    return new CommentError('SAVE_FAILED', 'Failed to save comment', true);
+  }
 
-  return (
-    <div>
-      {products.map(p => (
-        <ProductCard key={p.id} product={p} />   // Server-rendered
-      ))}
-    </div>
-  );
+  static notFound(id: string): CommentError {
+    return new CommentError('NOT_FOUND', `Comment ${id} not found`);
+  }
 }
 ```
 
-### Client Data Fetching (React Query)
+---
+
+## 3. Application Layer — Stores and Actions
 
 ```typescript
-// application/queries.ts
-import { useQuery } from '@tanstack/react-query';
-import { apiClient } from '../infrastructure/api-client';
-
-export function useProducts() {
-  return useQuery({
-    queryKey: ['products'],
-    queryFn: () => apiClient.get('/api/products'),
-    staleTime: 30_000,           // 30s before refetch
-    gcTime: 5 * 60 * 1000,       // 5min cache
-  });
+// collaboration/application/store.ts
+import { create } from 'zustand';
+import type { Thread, Comment } from '../domain/types';
+
+interface CollaborationState {
+  threads: Thread[];
+  activeThreadId: string | null;
+  isLoading: boolean;
+  error: string | null;
+  
+  setThreads: (threads: Thread[]) => void;
+  setActiveThread: (id: string) => void;
+  optimisticallyAddComment: (comment: Comment) => void;
+  rollbackComment: (commentId: string) => void;
 }
 
-// interfaces/product-list.client.tsx
-'use client';
-export function ProductList() {
-  const { data, isLoading } = useProducts();
-  if (isLoading) return <Skeleton />;
-  return data.map(p => <ProductCard key={p.id} product={p} />);
-}
+export const useCollaborationStore = create<CollaborationState>((set) => ({
+  threads: [],
+  activeThreadId: null,
+  isLoading: false,
+  error: null,
+  
+  setThreads: (threads) => set({ threads }),
+  setActiveThread: (id) => set({ activeThreadId: id }),
+  optimisticallyAddComment: (comment) => set((state) => ({
+    threads: state.threads.map(t =>
+      t.id === comment.threadId
+        ? { ...t, replyCount: t.replyCount + 1 }
+        : t
+    ),
+  })),
+  rollbackComment: (commentId) => set((state) => ({
+    threads: state.threads.map(t =>
+      t.id === commentId
+        ? { ...t, replyCount: t.replyCount - 1 }
+        : t
+    ),
+  })),
+}));
 ```
 
-### Server Actions (Mutations)
-
 ```typescript
-// application/actions.ts
+// collaboration/application/actions.ts
 'use server';
 import { revalidatePath } from 'next/cache';
-import { Cart } from '../domain/entity';
-
-export async function addToCart(productId: string, quantity: number) {
-  const cart = await loadCart();
-  cart.addItem(productId, quantity);
-  await saveCart(cart);
-  revalidatePath('/cart');       // Revalidate without full page reload
-  return { success: true };
+import type { Comment } from '../domain/types';
+
+export async function createComment(
+  nodeId: string,
+  body: string,
+  mentions: string[],
+): Promise<Comment> {
+  // Server Action — calls backend API
+  const res = await fetch(`/api/nodes/${nodeId}/comments`, {
+    method: 'POST',
+    body: JSON.stringify({ body, mentions }),
+  });
+  if (!res.ok) throw new Error('Failed to create comment');
+  const comment = await res.json();
+  revalidatePath(`/nodes/${nodeId}`);
+  return comment;
 }
 ```
 
-### Rules
-- ✅ Server Components for initial data — zero client JS for the first render
-- ✅ React Query for client-side data that needs realtime/stale-while-revalidate
-- ✅ Server Actions for mutations — no API route boilerplate
-- ❌ Never fetch in Server Components for data that needs realtime updates
-- ❌ Never use `useEffect` for data fetching — use React Query or Server Actions
-
 ---
 
-## 4. State Management
-
-| State type | Tool | Location |
-|-----------|------|----------|
-| Server state (data) | React Query / SWR | `application/queries.ts` |
-| Client state (UI) | Zustand / Jotai | `application/store.ts` |
-| URL state (filters, page) | `useSearchParams` | `interfaces/*.client.tsx` |
-| Form state | React Hook Form + Zod | `interfaces/*.client.tsx` |
-| Server mutations | Server Actions | `application/actions.ts` |
+## 4. Infrastructure Layer — API Clients
 
 ```typescript
-// application/store.ts — Zustand store
-import { create } from 'zustand';
-import { devtools } from 'zustand/middleware';
-import { Cart } from '../domain/entity';
-
-interface CartState {
-  cart: Cart | null;
-  isOpen: boolean;  // UI state — cart drawer toggle
-  addItem: (productId: string, qty: number) => Promise<void>;
-  toggleCart: () => void;
+// collaboration/infrastructure/api.ts
+import type { Thread, Comment } from '../domain/types';
+import { CommentError } from '../domain/errors';
+
+export async function fetchThreads(nodeId: string): Promise<Thread[]> {
+  const res = await fetch(`/api/nodes/${nodeId}/threads`);
+  if (!res.ok) throw new CommentError('FETCH_FAILED', 'Failed to load threads', true);
+  return res.json();
 }
 
-export const useCartStore = create<CartState>()(
-  devtools(
-    (set) => ({
-      cart: null,
-      isOpen: false,
-      addItem: async (productId, qty) => {
-        // Call Server Action, update local state optimistically
-      },
-      toggleCart: () => set(s => ({ isOpen: !s.isOpen })),
-    }),
-    { name: 'cart-store' },
-  ),
-);
+export async function saveComment(
+  nodeId: string,
+  threadId: string,
+  body: string,
+): Promise<Comment> {
+  const res = await fetch(`/api/nodes/${nodeId}/threads/${threadId}/comments`, {
+    method: 'POST',
+    body: JSON.stringify({ body }),
+  });
+  if (!res.ok) throw CommentError.saveFailed();
+  return res.json();
+}
 ```
 
-### Rules
-- ✅ Separate server state (React Query) from client state (Zustand)
-- ✅ Keep UI-only state (modals, toggles) local with `useState` when possible
-- ✅ Use Zustand slices for complex domains
-- ❌ Don't put server data in Zustand — that's what React Query is for
-
 ---
 
-## 5. Design System & CSS Architecture
-
-### Structure
+## 5. Interfaces Layer — React Components
 
-```
-shared/
-  ui/                                    # Design system components
-    tokens/                              # Design tokens
-      colors.ts
-      typography.ts
-      spacing.ts
-    button/
-      button.tsx                         # Component
-      button.module.css                  # Styles
-      button.test.tsx                    # Tests
-    card/
-    modal/
-    form/
-      input.tsx
-      select.tsx
-```
+```typescript
+// collaboration/interfaces/thread-panel.tsx
+'use client';
+import { useCollaborationStore } from '../application/store';
+import { fetchThreads } from '../infrastructure/api';
+import { CommentList } from './comment-list';
 
-### Styling Strategy
+export function ThreadPanel({ nodeId }: { nodeId: string }) {
+  const { threads, activeThreadId, setActiveThread, setThreads } = useCollaborationStore();
 
-| Approach | When to use |
-|----------|-------------|
-| CSS Modules (`*.module.css`) | Component-scoped styles in design system |
-| Tailwind utility classes | Layout, spacing, one-off adjustments |
-| CSS Variables (`var(--color-primary)`) | Design tokens, theming |
-| `clsx` / `tailwind-merge` | Conditional class composition |
+  useEffect(() => {
+    fetchThreads(nodeId).then(setThreads);
+  }, [nodeId]);
 
-```typescript
-// shared/ui/button/button.tsx
-import { type VariantProps, cva } from 'class-variance-authority';
-import { cn } from '../../lib/utils';
-
-const buttonVariants = cva(
-  'inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors',
-  {
-    variants: {
-      variant: {
-        primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
-        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
-        ghost: 'hover:bg-accent hover:text-accent-foreground',
-        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
-      },
-      size: {
-        sm: 'h-9 px-3',
-        md: 'h-10 px-4 py-2',
-        lg: 'h-11 px-8',
-      },
-    },
-    defaultVariants: { variant: 'primary', size: 'md' },
-  },
-);
-
-interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {}
-
-export function Button({ className, variant, size, ...props }: ButtonProps) {
-  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+  return (
+    <div>
+      {threads.map(thread => (
+        <button key={thread.id} onClick={() => setActiveThread(thread.id)}>
+          {thread.title} ({thread.replyCount})
+        </button>
+      ))}
+      {activeThreadId && <CommentList threadId={activeThreadId} />}
+    </div>
+  );
 }
 ```
 
-### Design System Rules
-- ✅ Design tokens in `shared/ui/tokens/` — single source of truth for colors, spacing, typography
-- ✅ Components use `cva` (class-variance-authority) for variant props
-- ✅ CSS Modules for component styles, Tailwind for layout
-- ✅ Dark mode via `class` strategy on `<html>` element
-- ❌ No inline styles (`style={{}}`) except for dynamic values (animations, transforms)
-- ❌ No CSS-in-JS libraries (styled-components, emotion) — they break Server Components
-
 ---
 
-## 6. Error Handling
+## 6. Server/Client Boundary
 
-```typescript
-// domain/errors.ts — Typed domain errors
-export class DomainError extends Error {
-  constructor(
-    public readonly code: string,
-    message: string,
-    public readonly status: number = 400,
-  ) {
-    super(message);
-    this.name = 'DomainError';
-  }
+| Layer | 'use client'? | 'use server'? | Can use hooks? |
+|-------|--------------|---------------|----------------|
+| `domain/` | No | No | No |
+| `application/` | No (except stores) | Yes (actions) | No |
+| `infrastructure/` | No | No | No |
+| `interfaces/` | Yes | No | Yes |
 
-  static notFound(id: string) {
-    return new DomainError('NOT_FOUND', `Resource ${id} not found`, 404);
-  }
-}
+---
 
-// interfaces/error.tsx — Next.js error boundary
-'use client';
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
-  return (
-    <div role="alert">
-      <h2>Something went wrong</h2>
-      <button onClick={() => reset()}>Try again</button>
-    </div>
-  );
-}
+## 7. Shared Code — When Something Spans Multiple Modules
 
-// interfaces/not-found.tsx — Next.js 404 boundary
-export default function NotFound() {
-  return <div>Page not found</div>;
-}
+Not everything belongs inside a module. The `shared/` directory holds cross-cutting code that multiple modules need. But it has strict rules.
+
+### What goes in `shared/` vs `module/`
+
+```
+src/
+  shared/                            # Cross-cutting, NOT a bounded context
+    domain/                          # Shared domain concepts (Anti-Corruption Layer)
+      user.ts                        #   User type used by multiple contexts
+      team.ts                        #   Team type used by multiple contexts
+      pagination.ts                  #   Generic pagination types
+    hooks/                           # Generic React hooks (zero business logic)
+      use-debounce.ts
+      use-media-query.ts
+      use-intersection-observer.ts
+    lib/                             # Pure utilities
+      date-utils.ts                  #   Date formatting
+      string-utils.ts                #   Slug generation
+      api-client.ts                  #   Base fetch wrapper (not domain-specific)
+    ui/                              # Design system (framework-agnostic)
+      button/
+      card/
+      modal/
+  collaboration/                     # Bounded context
+    domain/
+      thread.ts                      #   Business-specific concept
+      comment.ts
+    application/
+      store.ts
+    infrastructure/
+      api.ts
+    interfaces/
+      thread-panel.tsx
 ```
 
----
+### The rules
 
-## 7. Testing Patterns
+| Goes in `shared/` | Goes in `module/` |
+|------------------|-------------------|
+| `useDebounce` (generic hook) | `useCollaborationStore` (domain-specific) |
+| `apiClient.fetch()` (generic HTTP) | `collaborationApi.fetchThreads()` (domain-specific) |
+| `formatDate()` (utility) | `calculateThreadActivity()` (domain logic) |
+| `Button`, `Card` (design system) | `ThreadPanel`, `CommentList` (domain components) |
+| `User`, `Team` (shared kernel) | `Thread`, `Comment` (domain entities) |
 
-| Test type | Tool | What to test |
-|-----------|------|-------------|
-| Unit | Vitest | `domain/` entities, value objects |
-| Component | Vitest + Testing Library | `interfaces/` components |
-| Integration | Vitest + MSW | API client with mocked server |
-| E2E | Playwright | Full user flows |
+### The critical rule: `shared/` must NOT contain business logic
 
 ```typescript
-// domain/entity.test.ts — Pure unit test, no React
-import { Cart } from './entity';
-
-describe('Cart', () => {
-  it('adds item', () => {
-    const cart = new Cart();
-    cart.addItem({ id: '1', name: 'Test', price: 100 }, 2);
-    expect(cart.total).toBe(200);
-  });
-});
+// ❌ BAD — business logic in shared/
+shared/lib/thread-utils.ts
+  export function calculateThreadPriority(thread: Thread): number { }
+
+// ✅ GOOD — business logic in the module
+collaboration/domain/thread.ts
+  export function calculateThreadPriority(thread: Thread): number { }
 ```
 
----
+```typescript
+// ✅ GOOD — generic infrastructure in shared/
+shared/lib/api-client.ts
+  export class ApiClient {
+    async get<T>(path: string): Promise<T> { }
+  }
+
+// ✅ GOOD — domain-specific API in module infrastructure
+collaboration/infrastructure/api.ts
+  import { ApiClient } from '@/shared/lib/api-client';
+  const api = new ApiClient();
+  export async function fetchThreads(nodeId: string): Promise<Thread[]> {
+    return api.get(`/nodes/${nodeId}/threads`);
+  }
+```
 
-## 8. Anti-Patterns — NEVER DO
+### When the same concept appears in multiple domains (Shared Kernel)
 
 ```typescript
-// ❌ Business logic in components
-export default function Page() {
-  const [cart, setCart] = useState([]);  // BAD — belongs in domain/
+// shared/domain/user.ts — User is a shared concept
+// Shared kernel: multiple domains reference the same User
+export interface User {
+  id: string;
+  name: string;
+  email: string;
 }
 
-// ❌ Data fetching in client components without React Query
-useEffect(() => { fetch('/api/data').then(setData); }, []);  // BAD
+// collaboration/domain/thread.ts — imports shared User, doesn't redefine it
+import { User } from '@/shared/domain/user';
+export interface Thread {
+  id: string;
+  title: string;
+  createdBy: User;  // References shared type, not duplicated
+}
+```
 
-// ❌ 'use client' on the entire page
-'use client';  // BAD — only add to interactive islands
+### File naming convention
 
-// ❌ Inline styles
-<div style={{ marginLeft: '16px' }}>  // BAD — use Tailwind or CSS Modules
+Files are named by their **concept**, not prefixed with the module name:
 
-// ❌ Mixing server/client concerns
-import { cookies } from 'next/headers';  // BAD in client component
+| Wrong | Right |
+|-------|-------|
+| `collaboration-types.ts` | `types.ts` (or `thread.ts`, `comment.ts`) |
+| `collaboration-errors.ts` | `errors.ts` |
+| `collaboration-store.ts` | `store.ts` |
 
-// ❌ Global CSS for component styles
-h1 { color: blue; }  // BAD — use CSS Modules or Tailwind
-```
+The directory path `collaboration/domain/thread.ts` already tells you which module it belongs to.
+
+---
+
+## 8. Testing by Layer
+
+| Layer | Test type | Framework | What to test |
+|-------|-----------|-----------|-------------|
+| `domain/` | Unit | Vitest | Types, errors, pure functions |
+| `application/` | Unit | Vitest | Store logic, action validation |
+| `infrastructure/` | Integration | Vitest + MSW | API calls with mocked server |
+| `interfaces/` | Component | Vitest + Testing Library | Render, user events, accessibility |
 
 ---
 
-*Version: 1.1.0*
+*Version: 1.2.0*
 *Last updated: 2026-07-03*