gh-hopeoverture-worldbuilding-app-skills-plugins-nextjs-fullstack-scaffold/skills/nextjs-fullstack-scaffold/references/stack-architecture.md

Stack Architecture Reference

Technology Stack

Core Framework

• Next.js 16 (App Router) - React framework with built-in routing, server components, and API routes
• React 19 - UI library with Server Components support
• TypeScript - Type safety across the entire stack

Styling

• Tailwind CSS v4 - Utility-first CSS framework
• shadcn/ui - Accessible component system built on Radix UI
• CSS Variables - For theming and dark mode support

Backend & Database

• Supabase - Auth provider + PostgreSQL hosting
• Prisma ORM - Type-safe database client
• Server Actions - Next.js server-side mutations

Forms & Validation

• React Hook Form - Performant form management
• Zod - Runtime type validation and schema definition
• @hookform/resolvers - Bridge between RHF and Zod

Developer Experience

• ESLint v9 - Code linting with flat config
• Prettier - Code formatting
• Husky - Git hooks for pre-commit checks
• lint-staged - Run linters on staged files only

Testing

• Vitest - Unit test runner
• React Testing Library - Component testing
• Playwright - E2E browser testing

Utilities

• Sonner - Toast notifications
• lucide-react - Icon library
• clsx + tailwind-merge - Conditional CSS class utilities

Architecture Patterns

App Router Structure

Route Groups

Use route groups to organize routes without affecting URL structure:

app/
  (auth)/          # Public authentication routes
    login/
    signup/
  (protected)/     # Protected routes requiring authentication
    dashboard/
    profile/
    settings/

Layouts

• Root layout (app/layout.tsx) - Wraps entire app
• Group layouts - Shared UI for route groups
• Nested layouts - Inherited down the tree

Server vs Client Components

Server Components (Default)

• Data fetching
• Database queries
• Server-side logic
• No interactivity needed

Client Components ("use client")

• Interactivity (onClick, onChange, etc.)
• React hooks (useState, useEffect, etc.)
• Browser APIs
• Third-party libraries requiring client-side code

Data Fetching Patterns

Server Components

async function getData() {
  const data = await prisma.table.findMany()
  return data
}

export default async function Page() {
  const data = await getData()
  return <div>{/* render */}</div>
}

Server Actions

'use server'

export async function createItem(formData: FormData) {
  const validated = schema.parse(formData)
  await prisma.item.create({ data: validated })
  revalidatePath('/items')
}

Authentication Flow

Supabase SSR Setup

1. Create Supabase client for server (cookies-based)
2. Create Supabase client for client (storage-based)
3. Middleware to refresh tokens
4. Protected route groups

Auth Flow

1. User submits login form
2. Server Action validates credentials
3. Supabase sets secure cookies
4. Middleware verifies on subsequent requests
5. Redirect to dashboard

Database Layer

Prisma Schema

• Define models matching Supabase tables
• Use @db.Uuid for UUID types
• Add indexes for performance
• Include relations

Migrations

npx prisma migrate dev --name init
npx prisma generate
npx prisma db push

Form Handling Pattern

const form = useForm<FormData>({
  resolver: zodResolver(schema),
  defaultValues: {...}
})

async function onSubmit(data: FormData) {
  const result = await serverAction(data)
  if (result.success) {
    toast.success('Success!')
  }
}

Testing Strategy

Unit Tests

• Utility functions
• Validation schemas
• Helper functions

Integration Tests

• Component behavior
• Form submissions
• User interactions

E2E Tests

• Critical user flows
• Authentication
• Data mutations

File Naming Conventions

• Components: PascalCase (UserProfile.tsx)
• Utilities: camelCase (formatDate.ts)
• Server Actions: camelCase (createUser.ts)
• Route Segments: lowercase (dashboard, profile)
• API Routes: lowercase (route.ts)

Configuration Files

TypeScript (tsconfig.json)

• Strict mode enabled
• Path aliases (@/*)
• Next.js plugin

ESLint (eslint.config.mjs)

• Flat config format (v9)
• Next.js rules
• TypeScript rules
• Custom rules for unused vars

Tailwind (tailwind.config.ts)

• CSS variables for theming
• Dark mode support
• Custom color palette
• shadcn/ui compatible

Prisma (prisma/schema.prisma)

• PostgreSQL datasource
• Shadow database for migrations
• Supabase connection pooling

Environment Variables

Required variables:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
DATABASE_URL (connection pooling)
DIRECT_URL (direct connection)

Deployment

Vercel Setup

1. Connect GitHub repository
2. Set environment variables
3. Configure build settings (auto-detected)
4. Deploy

Build Command

npm run build

• Runs Prisma generate
• Builds Next.js app
• Type checks
• Lint checks

Best Practices

Performance

• Use Server Components by default
• Minimize client-side JavaScript
• Implement proper caching strategies
• Use React Suspense for loading states

Security

• Validate all inputs with Zod
• Use Server Actions for mutations
• Implement Row Level Security in Supabase
• Never expose secrets to client

Accessibility

• Use shadcn/ui components (built on Radix)
• Include ARIA labels
• Ensure keyboard navigation
• Test with screen readers

Type Safety

• Define Zod schemas for all forms
• Use Prisma for database queries
• Type all API responses
• Avoid any types