Projektstruktur

.
├── apps/
│   └── boilerplate/              # Haupt-SaaS-Anwendung (Next.js)
│       ├── prisma/               # Datenbankschema und Migrationen
│       │   └── schema.prisma     # Prisma-Schema-Definition
│       ├── public/               # Statische Assets (Favicons, Bilder, Manifeste)
│       ├── src/                  # Gesamter Anwendungs-Quellcode
│       │   ├── app/              # Routen, Seiten, Layouts und API-Endpunkte
│       │   ├── components/       # Wiederverwendbare UI-Komponenten
│       │   ├── config/           # Anwendungskonfiguration
│       │   ├── emails/           # React Email Templates
│       │   ├── hooks/            # Custom React Hooks
│       │   ├── lib/              # Kerngeschäftslogik und Hilfsfunktionen
│       │   ├── middleware.ts     # Request-Pipeline (Auth + Sicherheit)
│       │   ├── mocks/           # MSW API-Mock-Handler
│       │   ├── providers/       # React Context Provider
│       │   └── styles/themes/   # Farbthema-CSS-Dateien
│       ├── e2e/                  # Playwright End-to-End-Tests
│       ├── .env.example          # Vorlage für Umgebungsvariablen
│       ├── docker-compose.yml    # Lokales PostgreSQL-Setup
│       ├── next.config.mjs       # Next.js-Konfiguration
│       ├── tailwind.config.js    # Tailwind-CSS-Konfiguration
│       ├── tsconfig.json         # TypeScript-Konfiguration
│       ├── vitest.config.ts      # Unit-Test-Konfiguration
│       └── playwright.config.ts  # E2E-Test-Konfiguration
├── packages/
│   ├── ui/                       # Gemeinsame UI-Komponenten (@nextsaasai/ui)
│   ├── utils/                    # Gemeinsame Hilfsfunktionen (@nextsaasai/utils)
│   ├── email-templates/          # E-Mail-Templates (@nextsaasai/email-templates)
│   └── blog/                     # Blog-Paket (@nextsaasai/blog)
├── package.json                  # Root-Workspace-Konfiguration
├── pnpm-workspace.yaml           # Workspace-Definitionen
└── turbo.json                    # Build-Pipeline-Konfiguration

apps/boilerplate/src/app/
├── (auth)/           # Authentifizierungsseiten (Login, Registrierung)
├── (dashboard)/      # Dashboard-Seiten (geschützte Routen)
├── (dev)/            # Nur-Entwicklung-Seiten
├── (legal)/          # Rechtliche Seiten (Datenschutz, AGB, Impressum)
├── api/              # API-Route-Handler
├── logout/           # Logout-Ablauf
├── payment/          # Zahlungsseiten
├── layout.tsx        # Root-Layout (Provider, Schriften, Theme)
├── page.tsx          # Startseite
├── globals.css       # Globale Styles und Theme-Imports
├── llms.txt/         # llms.txt für KI-Crawler (llmstxt.org)
├── robots.ts         # robots.txt-Generierung
└── sitemap.ts        # sitemap.xml-Generierung

apps/boilerplate/src/components/
├── ai/               # KI-Chat-, Bildgenerierungs- und Content-Generator-Komponenten
├── auth/             # Login-Formulare, Auth Guards, Benutzermenüs
├── credits/          # Credit-Guthaben-Anzeigen, Bonus-Toggle, Kaufabläufe
├── dashboard/        # Dashboard-Layout, Sidebar, Statistik-Cards
├── demo/             # Demo-Modus-Banner und Mock-Daten-UI
├── modals/           # Modal-Dialoge und Bestätigungsabfragen
├── payments/         # Pricing Cards, Checkout, Abrechnungsverlauf
├── shared/           # Feature-übergreifende Hilfsmittel (Laden, Fehler)
├── test/             # Test-spezifische Wrapper-Komponenten
└── upload/           # Datei-Upload-Komponenten

apps/boilerplate/src/lib/
├── ai/               # KI-Provider-Konfiguration, RAG-Pipeline, Embeddings, Bildgenerierung, Content Gen
├── api/              # API-Antwort-Hilfsmittel, Fehlerbehandlung
├── auth/             # Auth-Konfiguration, Testbenutzer, Hilfsfunktionen
├── config/           # Feature Flags und App-Konstanten
├── credits/          # Credit-Guthaben, Verbrauch, Tracking
├── db/               # Datenbank-Client (Prisma) und Query-Hilfsmittel
├── db.ts             # Datenbankverbindungs-Singleton
├── demo/             # Demo-Modus-Logik und Mock-Daten
├── email/            # E-Mail-Versand, Templates, Warteschlange
├── metadata.ts       # SEO-Metadaten-Hilfsmittel
├── navigation/       # Routendefinitionen und Navigationskonfiguration
├── payments/         # Lemon Squeezy Integration, Abonnement-Logik
├── permissions/      # Rollen- und Berechtigungsprüfungen
├── pricing/          # Pricing-Konfiguration, Plan-Definitionen, Validierung
├── query/            # TanStack Query Keys und Fetch-Funktionen
├── security/         # Rate Limiting, CORS, CSP, Eingabe-Sanitierung
├── services/         # Service-Layer (Benutzer, Abonnement, Credits)
├── storage/          # Vercel Blob Storage Hilfsmittel
├── stores/           # Zustand Client-seitige Stores
├── utils/            # Allgemeine Hilfsfunktionen
├── validations/      # Zod-Schemas für API-Validierung
└── webhooks/         # Webhook-Verifikation und -Verarbeitung

// 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>
                <TooltipProvider>
                  {children}
                  <Toaster
                    richColors
                    position="top-center"
                    duration={8000}
                    toastOptions={{
                      classNames: {
                        icon: '!self-start !mt-0.5',
                        description: '!whitespace-pre-line',
                      },
                    }}
                  />
                  <FilteredAnalytics />
                </TooltipProvider>
              </DemoProvider>
            </ThemeProvider>
          </QueryProvider>
        </MSWProvider>
      </body>
    </html>
  )

apps/boilerplate/src/hooks/
├── use-ai.ts                    # KI-Chat-Zustand und Streaming-Aktionen
├── use-chat-rag.ts              # RAG-Chat mit Knowledge Base
├── use-rag-chat.ts              # RAG-Chat-Hook mit SSE-Streaming
├── use-image-gen.ts             # Bildgenerierungs-Hook mit Sitzungsverlauf
├── use-content-generator.ts     # Content-Generator-Hook mit SSE-Streaming
├── use-audio-recorder.ts        # Audio-Aufnahme-Hook (MediaRecorder API)
├── use-pricing-config.ts        # Zugriff auf aktuelle Pricing-Konfiguration
├── use-subscription-actions.ts  # Abonnementverwaltungs-Aktionen
├── use-user-tier.ts             # Abonnement-Tier des aktuellen Benutzers
├── use-is-in-demo-mode.ts       # Prüfen, ob Demo-Modus aktiv ist
├── use-safe-query-client.ts     # Sicherer TanStack Query Client Zugriff
└── ai-hooks.ts                  # Gemeinsame KI-Hook-Hilfsmittel

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'