frontend-architect-skill

Frontend Architect Skill

Unified enterprise frontend architecture for Next.js 16 + React 19 + TypeScript 5 + Tailwind 4 + Zustand 5 + TanStack Query 5 + TanStack Table 8 + Better Auth.

Transforms feature requirements into production-grade, multi-tenant, component-driven frontend implementations.

Reference Files

File	What It Covers
SKILL.md	This file — 7-phase flow, patterns, checklists
folder-structure.md	Complete project layout with every directory
library-decisions.md	30+ locked library decisions + when NOT to use alternatives
table-reference.md	UnifiedDataTable API — props, columns, filters, persistence
wizard-reference.md	Multi-step wizard architecture from CSV import reference
migration-skill.md	How to migrate any legacy Next.js project to the correct architecture — 7-phase plan with diagnosis checklist, templates, and anti-pattern fixes

Current Platform Status

When migrating an existing Next.js project to this architecture, key production-grade assets should be preserved (not rewritten):

• UnifiedDataTable — if a headless TanStack Table wrapper exists with persistence, DnD, and filters, keep it and move to features/{name}/components/ui/
• Import Wizards — if multi-step import flows exist with auto-mapping and duplicate detection, preserve them in features/{name}/components/import/
• JSON data layer — if lib/data/*.ts files provide a file-based backend, keep for demo mode and wrap with fetchApi() adapter
• shadcn/ui components — always keep in components/ui/, never modify

See migration-skill.md for the generic 7-phase migration plan.

Immutable Stack (Locked Decisions)

Concern	Technology	Why
Framework	Next.js 16 (App Router + Turbopack)	SSR, routing, middleware, API routes
UI Library	React 19	Concurrent rendering, server components
Language	TypeScript 5 (strict)	Type safety, IDE support
Styling	Tailwind CSS 4 (OKLCH colors)	Utility-first, design tokens
Components	shadcn/ui (61+ components)	Radix primitives, customizable
Client State	Zustand 5	Lightweight, middleware, persist
Server State	TanStack Query 5	Caching, mutations, devtools
Data Tables	TanStack Table 8 + @dnd-kit	Headless, sortable, filterable
Forms	react-hook-form + Zod	Validation, performance
Auth	Better Auth	Session, OAuth, middleware
i18n	next-intl (5 locales + RTL)	Static rendering, type-safe
Icons	lucide-react	Tree-shakeable, consistent
Toasts	sonner	Beautiful, accessible
DnD	@dnd-kit/core + sortable	Column reorder, list sort

Seven-Phase Flow (Apply to Every Feature)

Phase 0: Types & Contracts

Before touching any component, define the data shape:

src/features/{feature}/types.ts

// Entity types
export interface Recipient {
  id: string
  email: string
  firstName: string
  lastName: string
  status: 'active' | 'inactive' | 'bounced'
  department?: string
  tags: string[]
  customFields: Record<string, unknown>
  createdAt: string
  updatedAt: string
}

// Filter types
export interface RecipientFilter {
  status?: string[]
  department?: string[]
  search?: string
  page?: number
  limit?: number
}

// Form types (Zod schemas)
export const CreateRecipientSchema = z.object({
  email: z.string().email(),
  firstName: z.string().min(1),
  lastName: z.string().min(1),
  status: z.enum(['active', 'inactive']).default('active'),
})
export type CreateRecipientInput = z.infer<typeof CreateRecipientSchema>

Rules:

• Types FIRST, components SECOND
• Zod schemas for ALL form inputs
• Export types from features/{name}/index.ts
• Shared types go in src/types/index.ts

Phase 1: Mock Data & API Service

Build the data layer before any UI:

src/features/{feature}/lib/api.ts          # API service
src/lib/api/mock/{feature}.ts              # Mock data + handler

API Service Pattern:

// src/features/recipients/lib/api.ts
import { fetchApi, buildQueryString } from '@/lib/api/client'
import type { Recipient, RecipientFilter, CreateRecipientInput } from '../types'

export const recipientsApi = {
  async list(filter?: RecipientFilter): Promise<Recipient[]> {
    const query = filter ? buildQueryString(filter) : ''
    return fetchApi<Recipient[]>(`/api/recipients${query}`)
  },

  async getById(id: string): Promise<Recipient> {
    return fetchApi<Recipient>(`/api/recipients/${id}`)
  },

  async create(payload: CreateRecipientInput): Promise<Recipient> {
    return fetchApi<Recipient>('/api/recipients', {
      method: 'POST',
      body: JSON.stringify(payload),
    })
  },

  async update(id: string, payload: Partial<CreateRecipientInput>): Promise<Recipient> {
    return fetchApi<Recipient>(`/api/recipients/${id}`, {
      method: 'PATCH',
      body: JSON.stringify(payload),
    })
  },

  async delete(id: string): Promise<void> {
    return fetchApi<void>(`/api/recipients/${id}`, { method: 'DELETE' })
  },

  async bulkDelete(ids: string[]): Promise<{ deleted: number }> {
    return fetchApi('/api/recipients/bulk-delete', {
      method: 'POST',
      body: JSON.stringify({ ids }),
    })
  },

  async import(recipients: CreateRecipientInput[], options?: { duplicateHandling: string }): Promise<{ imported: number; skipped: number }> {
    return fetchApi('/api/recipients/import', {
      method: 'POST',
      body: JSON.stringify({ recipients, ...options }),
    })
  },
}

Adapter Pattern (Mock/Real switching):

// fetchApi auto-detects mode from env/localStorage
// NEXT_PUBLIC_API_MODE=mock  → routes to handleMockRequest()
// NEXT_PUBLIC_API_MODE=real  → routes to fetch() with auth headers

// Mock handler: src/lib/api/mock/handler.ts
// Add your feature's routes to the router

Rules:

• API service is a plain object with async methods (NOT a class)
• Every method returns typed promises
• Mock data must be realistic (use real-world Indian names, departments, etc.)
• Mock handler simulates 300ms network delay
• ALWAYS build mock first, connect real API later

Phase 2: React Query Hooks

Wrap API service with caching and mutations:

src/features/{feature}/hooks/use-{feature}.ts

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { recipientsApi } from '../lib/api'
import type { RecipientFilter } from '../types'

// Query key hierarchy (MANDATORY pattern)
export const recipientKeys = {
  all: ['recipients'] as const,
  lists: () => [...recipientKeys.all, 'list'] as const,
  list: (filter?: RecipientFilter) => [...recipientKeys.lists(), filter] as const,
  details: () => [...recipientKeys.all, 'detail'] as const,
  detail: (id: string) => [...recipientKeys.details(), id] as const,
  metrics: () => [...recipientKeys.all, 'metrics'] as const,
}

// Query hooks
export function useRecipients(filter?: RecipientFilter) {
  return useQuery({
    queryKey: recipientKeys.list(filter),
    queryFn: () => recipientsApi.list(filter),
  })
}

export function useRecipient(id: string) {
  return useQuery({
    queryKey: recipientKeys.detail(id),
    queryFn: () => recipientsApi.getById(id),
    enabled: !!id,
  })
}

// Mutation hooks
export function useCreateRecipient() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: recipientsApi.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: recipientKeys.lists() })
      queryClient.invalidateQueries({ queryKey: recipientKeys.metrics() })
    },
  })
}

export function useUpdateRecipient() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: ({ id, payload }: { id: string; payload: Partial<CreateRecipientInput> }) =>
      recipientsApi.update(id, payload),
    onSuccess: (updated) => {
      queryClient.setQueryData(recipientKeys.detail(updated.id), updated)
      queryClient.invalidateQueries({ queryKey: recipientKeys.lists() })
    },
  })
}

export function useDeleteRecipient() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: recipientsApi.delete,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: recipientKeys.lists() })
      queryClient.invalidateQueries({ queryKey: recipientKeys.metrics() })
    },
  })
}

Rules:

• Query keys are ALWAYS hierarchical objects (not magic strings)
• onSuccess ALWAYS invalidates relevant queries
• enabled flag for conditional fetching
• Export from features/{name}/hooks/index.ts

Phase 3: Components

Build UI components using the established patterns:

src/features/{feature}/components/
  ├── {feature}-data-table.tsx      # UnifiedDataTable wrapper
  ├── {feature}-columns.tsx         # Column definitions
  ├── {feature}-form.tsx            # Create/edit form
  ├── {feature}-detail.tsx          # Detail sidepanel/page
  ├── {feature}-filters.tsx         # Filter components
  └── index.ts                      # Exports

Data Table Pattern (MANDATORY for any list view):

// Use UnifiedDataTable — never build a custom table from scratch
<UnifiedDataTable<Recipient, unknown>
  columns={columns}
  data={data}
  localStoragePrefix="recipients-table"
  enableRowSelection
  enableSearch
  searchPlaceholder="Search recipients..."
  columnDefaults={{
    pinned: { left: ['select'], right: ['actions'] },
    visibility: { /* hidden columns */ },
  }}
  filters={[
    { id: 'status', column: 'status', title: 'Status', options: statusOptions, defaultVisible: true },
    { id: 'department', column: 'department', title: 'Department', options: deptOptions },
  ]}
  bulkActions={[
    { id: 'delete', label: 'Delete', variant: 'destructive', onExecute: handleBulkDelete, confirm: { ... } },
  ]}
  tableMeta={{ onUpdateField, onViewDetails }}
/>

Column Definition Pattern:

// Always define columns in a separate file
export const columns: ColumnDef<Recipient>[] = [
  // 1. Select column (pinned left)
  { id: 'select', size: 40, enableHiding: false, header: SelectAllCheckbox, cell: SelectRowCheckbox },

  // 2. Data columns with sorting
  {
    accessorKey: 'email',
    header: ({ column }) => <SortButton column={column}>Email</SortButton>,
    cell: ({ row }) => <code>{row.original.email}</code>,
  },

  // 3. Editable columns
  {
    accessorKey: 'department',
    cell: ({ row, table }) => (
      <EditableCell
        value={row.original.department}
        onSave={(val) => table.options.meta?.onUpdateField(row.original.id, 'department', val)}
      />
    ),
  },

  // 4. Multi-select filter columns
  {
    accessorKey: 'status',
    filterFn: (row, id, values: string[]) => !values?.length || values.includes(row.getValue(id)),
  },

  // 5. Actions column (pinned right)
  { id: 'actions', enableHiding: false, cell: ActionsDropdown },
]

Form Pattern:

const form = useForm<CreateRecipientInput>({
  resolver: zodResolver(CreateRecipientSchema),
  defaultValues: { email: '', firstName: '', lastName: '', status: 'active' },
})

const createMutation = useCreateRecipient()

const onSubmit = (data: CreateRecipientInput) => {
  createMutation.mutate(data, {
    onSuccess: () => {
      toast.success('Recipient created')
      form.reset()
    },
    onError: (err) => toast.error(err.message),
  })
}

Rules:

• ALWAYS use UnifiedDataTable for list views (never raw TanStack Table)
• Columns in separate file from the data table component
• Forms use react-hook-form + Zod (ALWAYS)
• Toast notifications for all mutations (success + error)
• Sidepanel for details (not separate pages, unless complex)

Phase 4: Pages

Wire everything together in App Router pages:

src/app/[locale]/(workspace)/{feature}/
  ├── page.tsx          # List page
  ├── [id]/page.tsx     # Detail page (if needed)
  └── layout.tsx        # Feature layout (if needed)

// src/app/[locale]/(workspace)/recipients/page.tsx
'use client'

import { useRecipients } from '@/features/recipients/hooks'
import { RecipientsDataTable } from '@/features/recipients/components'
import { PageHeader } from '@/components/common'

export default function RecipientsPage() {
  const { data: recipients, isLoading } = useRecipients()

  return (
    <div className="flex flex-col gap-6 p-6">
      <PageHeader
        title="Recipients"
        description="Manage your recipient list"
        actions={<Button onClick={() => setShowCreate(true)}>Add Recipient</Button>}
      />
      <RecipientsDataTable data={recipients ?? []} isLoading={isLoading} />
    </div>
  )
}

Rules:

• Pages are thin wrappers (fetch data → render components)
• Use 'use client' for pages with hooks/state
• Use PageHeader component for consistent page headers
• Loading states handled by component (skeleton/spinner)

Phase 5: Wizard Patterns (Complex Features)

For multi-step workflows (import, create campaign, onboarding):

src/features/{feature}/components/
  ├── {feature}-wizard.tsx          # Wizard container + state
  ├── steps/
  │   ├── step-upload.tsx           # Step 1
  │   ├── step-configure.tsx        # Step 2
  │   └── step-review.tsx           # Step 3
  └── utils/
      ├── auto-mapper.ts            # Complex logic (separate file)
      └── chunked-processor.ts      # Performance utilities

Wizard State Pattern (from CSV import reference):

interface WizardState {
  step: 1 | 2 | 3
  // Step 1 data
  file: File | null
  parsedData: Record<string, string>[]
  // Step 2 data
  fieldMappings: FieldMapping[]
  duplicateHandling: 'skip' | 'update'
  // Step 3 data
  isImporting: boolean
  importProgress: number
}

// Single source of truth — passed to all steps via props
function Wizard() {
  const [state, setState] = useState<WizardState>(initialState)
  const updateState = (partial: Partial<WizardState>) => setState(prev => ({ ...prev, ...partial }))

  return state.step === 1 ? <StepUpload state={state} updateState={updateState} /> :
         state.step === 2 ? <StepConfigure state={state} updateState={updateState} /> :
         <StepReview state={state} updateState={updateState} />
}

Chunked Processing (for large datasets):

// MANDATORY for >1000 rows — prevents UI freezing
async function processInChunks<T, R>(config: {
  data: T[]
  chunkSize: number
  processor: (chunk: T[], startIndex: number) => R[]
  onProgress: (percent: number) => void
}): Promise<R[]> {
  const results: R[] = []
  for (let i = 0; i < config.data.length; i += config.chunkSize) {
    const chunk = config.data.slice(i, i + config.chunkSize)
    results.push(...config.processor(chunk, i))
    config.onProgress(Math.round(((i + chunk.length) / config.data.length) * 100))
    await new Promise(resolve => setTimeout(resolve, 0)) // Yield to UI thread
  }
  return results
}

Rules:

• Wizard state is a SINGLE object (not scattered useState calls)
• Each step is its own component receiving state + updateState
• Complex logic (auto-mapping, duplicate detection) in separate utils files
• Chunked processing for any operation on >1000 items
• Progress tracking for long operations

Phase 6: Polish & Quality

Before considering any feature "done":

Checklist:

• Types defined in types.ts (no any anywhere)
• Mock data is realistic (Indian names, real departments, proper dates)
• API service covers all CRUD + bulk operations
• React Query hooks with proper key hierarchy
• UnifiedDataTable with: search, filters, bulk actions, column persistence
• Forms with Zod validation + proper error messages
• Toast notifications for all mutations
• Loading states (skeleton/spinner) for async data
• Empty states for no data
• Error states for failed fetches
• Responsive design (works on mobile)
• Keyboard accessible (tab navigation, enter to submit)
• No console errors/warnings

State Management Decision Tree

Is this data from an API?
├── YES → TanStack Query (useQuery/useMutation)
│         Never put API data in Zustand.
│
└── NO → Is it shared across many components?
         ├── YES → Zustand store (with persist if needed)
         │         Examples: sidebar state, user preferences, active workspace
         │
         └── NO → Is it form state?
                  ├── YES → react-hook-form (useForm)
                  │
                  └── NO → React useState/useReducer
                           Examples: modal open, local filter, wizard step

Feature Module Template

src/features/{name}/
├── index.ts                    # Barrel exports
├── types.ts                    # Entity types + Zod schemas
├── lib/
│   ├── api.ts                  # API service (recipientsApi)
│   └── index.ts
├── hooks/
│   ├── use-{name}.ts           # React Query hooks
│   └── index.ts
└── components/
    ├── {name}-data-table.tsx    # Table wrapper
    ├── {name}-columns.tsx       # Column definitions
    ├── {name}-form.tsx          # Create/edit form
    ├── {name}-detail.tsx        # Detail view
    └── index.ts

MSSP / Multi-Tenant Frontend Patterns

Every frontend feature must work for three customer types. Use progressive complexity — UC1 users see a simple UI, UC3 users see the full feature set.

Workspace Context (Required for UC3)

// Zustand store — persists active workspace
interface WorkspaceState {
  activeWorkspaceId: string | null
  activeCompanyId: string | null
  workspaces: Workspace[]
  setActiveWorkspace: (id: string) => void
}

// Every fetchApi() call includes workspace header automatically
headers: { 'x-workspace-id': useWorkspaceStore.getState().activeWorkspaceId }

Rules:

• Workspace selector in top nav (HIDDEN when company has only 1 workspace)
• "All Workspaces" option for Company Admins (read-only aggregated view)
• Switching workspace refreshes ALL React Query caches: queryClient.invalidateQueries()

Domain Tabs (Required for UC2+)

// Domain tabs above data table — NOT a cosmetic filter
<DomainTabs
  domains={workspaceDomains}        // Fetched from /api/domains
  activeDomainId={activeDomainId}   // null = "All Domains"
  onSelect={(domainId) => setActiveDomainId(domainId)}
/>

// Passes domainId to API: /api/recipients?domainId=xxx

Rules:

• HIDDEN when workspace has only 1 domain (UC1)
• Shows recipient count per domain
• "All Domains" tab shows combined (with Person de-dup count)

Person Column (Required for UC2+)

// In column definitions
{
  id: 'person',
  header: 'Person',
  cell: ({ row }) => {
    const linkCount = row.original.personLinkCount
    return linkCount > 1
      ? <Badge variant="outline">{linkCount} identities</Badge>
      : <span className="text-muted-foreground">Single</span>
  },
  // HIDDEN when workspace has only 1 domain (UC1)
}

Bulk Operations Domain Breakdown (Required for UC2+)

// When selecting across domains, show breakdown in toolbar
<BulkActionsToolbar>
  <span>5 from tatasteel.com, 3 from tatasteel.co.in selected</span>
  {hasSyncProtectedFields && (
    <Alert variant="warning">
      3 recipients have sync-protected fields. Changes may revert on next sync.
    </Alert>
  )}
</BulkActionsToolbar>

Settings Inheritance UI (Required for UC3)

// Each settings field shows its source
<SettingsField
  label="Track Email Opens"
  value={settings.trackOpens}
  source={fieldSources.trackOpens}  // 'company' | 'workspace' | 'override'
  onOverride={() => /* unlock field for workspace-level edit */}
  onReset={() => /* reset to company default */}
/>

// Badges: COMPANY (green, locked) | WORKSPACE (blue) | OVERRIDE (yellow, unlockable)

Progressive Complexity Rule

// In any component that has UC3-specific features:
const { workspaces } = useWorkspaceStore()
const { domains } = useDomainsForWorkspace(activeWorkspaceId)

const showWorkspaceSelector = workspaces.length > 1
const showDomainTabs = domains.length > 1
const showPersonColumn = domains.length > 1 || workspaces.length > 1
const showCompanyLibrary = workspaces.length > 1
const showBlueprintFeatures = workspaces.length > 1
const showSettingsInheritance = workspaces.length > 1

// UC1 user sees NONE of these. UC3 sees ALL.

MSSP Frontend Checklist

• Workspace selector exists (hidden for UC1)
• Domain tabs exist (hidden when 1 domain)
• Person column exists (hidden when 1 domain)
• fetchApi() sends x-workspace-id header automatically
• Switching workspace invalidates all React Query caches
• "All Workspaces" view is read-only for Company Admin
• Bulk ops show domain breakdown
• Sync-protected field warnings for synced recipients
• Import wizard asks for target domain (hidden when 1 domain)
• Settings show COMPANY/WORKSPACE/OVERRIDE badges
• Progressive complexity: UC1 sees simple UI, UC3 sees full

Master Checklist — Run Before Shipping

Types & Data:

• All types in types.ts (no inline types)
• Zod schemas for all form inputs
• API service with typed methods
• Mock data handler added to router

State:

• React Query for server state (NEVER Zustand for API data)
• Query keys follow hierarchical pattern
• Mutations invalidate correct queries
• Zustand only for client-only state (UI prefs, sidebar)

Components:

• UnifiedDataTable for all list views
• Columns in separate file
• Forms use react-hook-form + Zod
• Editable cells for inline editing
• Bulk actions with confirmation dialogs

UX:

• Loading skeletons (not spinners)
• Empty states with action buttons
• Error states with retry
• Toast on every mutation
• Optimistic updates where appropriate

Performance:

• Chunked processing for >1000 items
• No any types
• No unnecessary re-renders (memo where needed)
• Images use next/image