Project Structure

.
├── apps/
│   └── boilerplate/              # Main SaaS application (Next.js)
│       ├── prisma/               # Database schema and migrations
│       │   └── schema.prisma     # Prisma schema definition
│       ├── public/               # Static assets (favicons, images, manifests)
│       ├── src/                  # All application source code
│       │   ├── app/              # Routes, pages, layouts, and API endpoints
│       │   ├── components/       # Reusable UI components
│       │   ├── config/           # Application configuration
│       │   ├── emails/           # React Email templates
│       │   ├── hooks/            # Custom React hooks
│       │   ├── lib/              # Core business logic and utilities
│       │   ├── middleware.ts     # Request pipeline (auth + security)
│       │   ├── mocks/           # MSW API mock handlers
│       │   ├── providers/       # React context providers
│       │   └── styles/themes/   # Color theme CSS files
│       ├── e2e/                  # Playwright end-to-end tests
│       ├── .env.example          # Environment variable template
│       ├── docker-compose.yml    # Local PostgreSQL setup
│       ├── next.config.mjs       # Next.js configuration
│       ├── tailwind.config.js    # Tailwind CSS configuration
│       ├── tsconfig.json         # TypeScript configuration
│       ├── vitest.config.ts      # Unit test configuration
│       └── playwright.config.ts  # E2E test configuration
├── packages/
│   ├── ui/                       # Shared UI components (@nextsaas/ui)
│   ├── utils/                    # Shared utilities (@nextsaas/utils)
│   ├── email-templates/          # Email templates (@nextsaas/email-templates)
│   ├── blog/                     # Blog package (@nextsaas/blog)
│   ├── docs/                     # Documentation package (@nextsaas/docs)
│   └── marketing-utils/          # Marketing utilities (@nextsaas/marketing-utils)
├── package.json                  # Root workspace configuration
├── pnpm-workspace.yaml           # Workspace definitions
└── turbo.json                    # Build pipeline configuration

apps/boilerplate/src/app/
├── (auth)/           # Authentication pages (login, register)
├── (dashboard)/      # Dashboard pages (protected routes)
├── (dev)/            # Development-only pages
├── (legal)/          # Legal pages (privacy, terms, imprint)
├── api/              # API route handlers
├── logout/           # Logout flow
├── payment/          # Payment flow pages
├── layout.tsx        # Root layout (providers, fonts, theme)
├── page.tsx          # Homepage
├── globals.css       # Global styles and theme imports
├── llms.txt/         # llms.txt for AI crawlers (llmstxt.org)
├── robots.ts         # robots.txt generation
└── sitemap.ts        # sitemap.xml generation

apps/boilerplate/src/components/
├── ai/               # AI chat, image generation, and content generator components
├── auth/             # Login forms, auth guards, user menus
├── credits/          # Credit balance displays, bonus toggle, purchase flows
├── dashboard/        # Dashboard layout, sidebar, stats cards
├── demo/             # Demo mode banner and mock data UI
├── modals/           # Modal dialogs and confirmation prompts
├── payments/         # Pricing cards, checkout, billing history
├── shared/           # Cross-feature utilities (loading, errors)
├── test/             # Test-specific wrapper components
└── upload/           # File upload components

apps/boilerplate/src/lib/
├── ai/               # AI provider config, RAG pipeline, embeddings, image gen, content gen
├── api/              # API response helpers, error handling
├── auth/             # Auth config, test user, helpers
├── config/           # Feature flags and app constants
├── credits/          # Credit balance, consumption, tracking
├── db/               # Database client (Prisma) and query helpers
├── db.ts             # Database connection singleton
├── demo/             # Demo mode logic and mock data
├── email/            # Email sending, templates, queue
├── metadata.ts       # SEO metadata helpers
├── navigation/       # Route definitions and navigation config
├── payments/         # Lemon Squeezy integration, subscription logic
├── permissions/      # Role and permission checks
├── pricing/          # Pricing config, plan definitions, validation
├── query/            # TanStack Query keys and fetch functions
├── security/         # Rate limiting, CORS, CSP, input sanitization
├── services/         # Service layer (user, subscription, credit)
├── storage/          # Vercel Blob storage helpers
├── stores/           # Zustand client-side stores
├── utils/            # General utility functions
├── validations/      # Zod schemas for API validation
└── webhooks/         # Webhook verification and processing

// Provider Hierarchy (TOP → BOTTOM):
  // 1. ClerkProvider - MUST wrap <html> and <body> (Clerk requirement)
  // 2. MSWProvider - Mock Service Worker for API interception (dev/test)
  // 3. QueryProvider - MUST be top-level for SSR/hydration safety
  // 4. ThemeProvider - Theme context (dark/light mode)
  // 5. DemoProvider - Demo mode context (passthrough when demo disabled)
  //
  // CRITICAL FIX: ClerkProvider now wraps <html> and <body> tags
  // This fixes the "useAuth can only be used within ClerkProvider" error
  // Reference: https://clerk.com/docs/nextjs/reference/components/clerk-provider
  //
  // Color Theme System:
  // - data-theme attribute applies color scheme to entire application
  // - Configured via COLOR_THEME environment variable
  // - Supports 9 themes: default, ocean, forest, sunset, midnight, coral, slate, aurora, crimson
  //

const content = (
    <html lang="en" suppressHydrationWarning data-theme={colorTheme}>
      <body className={`${inter.className} ${jetbrainsMono.variable}`}>
        <MSWProvider>
          <QueryProvider>
            <ThemeProvider
              attribute="class"
              defaultTheme="system"
              enableSystem
              disableTransitionOnChange
            >
              <DemoProvider>
                  {children}
                  <Toaster richColors position="top-center" duration={8000} />
                  {process.env.VERCEL_ENV === 'production' && <Analytics />}
                  {process.env.VERCEL_ENV === 'production' && <SpeedInsights />}
              </DemoProvider>
            </ThemeProvider>
          </QueryProvider>
        </MSWProvider>
      </body>
    </html>
  )

apps/boilerplate/src/hooks/
├── use-ai.ts                    # AI chat state and streaming actions
├── use-chat-rag.ts              # RAG chat with knowledge base
├── use-rag-chat.ts              # RAG chat hook with SSE streaming
├── use-image-gen.ts             # Image generation hook with session history
├── use-content-generator.ts     # Content generator hook with SSE streaming
├── use-audio-recorder.ts        # Audio recording hook (MediaRecorder API)
├── use-pricing-config.ts        # Access current pricing configuration
├── use-subscription-actions.ts  # Subscription management actions
├── use-user-tier.ts             # Current user's subscription tier
├── use-is-in-demo-mode.ts       # Check if demo mode is active
├── use-safe-query-client.ts     # Safe TanStack Query client access
└── ai-hooks.ts                  # Shared AI hook utilities

export const AVAILABLE_THEMES = [
  'default',
  'ocean',
  'forest',
  'sunset',
  'midnight',
  'coral',
  'slate',
  'aurora',
  'crimson',
] as const

export const siteConfig = {
  /** Your brand/product name */
  name: 'nextsaas.ai Kit',

  /** Short description for the homepage title tag */
  tagline: 'AI-Native Next.js SaaS Boilerplate',

  /** Name used for blog article title tags */
  blogName: 'nextsaas.ai Blog',

  /** Separator between page name and brand (En-dash is professional standard) */
  separator: '–',

  /** Base URL for metadata */
  url: process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000',

  /** Default description for pages without custom description */
  description:
    'Production-ready Next.js boilerplate with authentication, database, and modern UI components.',

  /** Author information */
  author: {
    name: 'Jon Doe',
    twitter: '@jondoe',
  },
} as const

export type SiteConfig = typeof siteConfig

"paths": {
      "@/*": ["./src/*"]
    }

import { siteConfig } from '@/config/site'
import { Button } from '@/components/ui/button'
import { prisma } from '@/lib/db'