lemonspace_app/app/CLAUDE.md

app/ — Next.js Routing & Layouts

Next.js 16 App Router. Vor Änderungen: Relevante Guides in node_modules/next/dist/docs/ lesen — Breaking Changes gegenüber früheren Versionen möglich.

---

Route-Struktur

app/
├── layout.tsx                    ← Root Layout (Fonts, Providers, Sentry, Analytics)
├── page.tsx                      ← Landing / Redirect
├── globals.css                   ← Tailwind v4 + Design-Tokens
├── (app)/                        ← Authentifizierte App-Routen
│   ├── canvas/[canvasId]/        ← Canvas-Editor
│   │   ├── page.tsx              ← SSR-Auth/ID-Validation, rendert dann `CanvasShell`
│   │   └── error.tsx             ← Error Boundary für Canvas
│   └── settings/
│       └── billing/              ← Billing-Einstellungen
├── auth/                         ← Auth-Routen (Better Auth)
│   ├── [path]/                   ← Catch-all für Better Auth Flows
│   ├── sign-in/
│   └── sign-up/
├── api/
│   ├── auth/[...all]/            ← Better Auth API Handler
│   └── pexels-video/             ← Pexels Video Proxy
└── dashboard/                    ← Dashboard nach Login

---

Root Layout (layout.tsx)

Server Component. Initialisiert:

1. Font: Manrope via next/font/google → CSS-Variable --font-sans
2. Auth: getToken() + getAuthUser() für SSR-seitigen Convex-Token
3. Sentry: Sentry.setUser() direkt im Layout (serverseitig)
4. Analytics: Rybbit-Script via <script> Tag (rybbit.matthias.lol)
5. Providers: <Providers initialToken={...}> — Convex + Theme + Auth
6. InitUser: <InitUser /> — Ruft api.credits.initBalance beim ersten Login auf

Provider-Pattern:

// components/providers.tsx
<ConvexProvider client={convex}>
  <ThemeProvider>
    <AuthProvider>
      {children}
    </AuthProvider>
  </ThemeProvider>
</ConvexProvider>

initialToken wird server-seitig aus Better Auth ausgelesen und an Convex übergeben — verhindert einen Auth-Flash beim ersten Render. Mit initialToken springt isAuthenticated sofort auf true ohne Loading-Phase.

---

Auth-Flow

Better Auth (self-hosted, open-source). Konfiguration in lib/auth.ts (Server) und lib/auth-client.ts (Client).

• Server-Helper: getAuthUser(), getToken() aus lib/auth-server.ts
• Client-Helper: authClient aus lib/auth-client.ts
• Convex-Integration: convex/auth.config.ts + convex/auth.ts
• Trusted Origins: https://app.lemonspace.io, http://localhost:3000
• Sign-In unterstützt email+password und magic link (authClient.signIn.magicLink)
• Dashboard-Route (app/dashboard/page.tsx) redirectet bei fehlender Session explizit nach /auth/sign-in, damit kein permanenter Loading-State entsteht

---

Route Groups

(app)/ — Klammer-Gruppen teilen kein eigenes Layout-Segment, ermöglichen aber eigene layout.tsx für Auth-Guards. Alle eingeloggten Routen liegen hier.

---

API-Routen

• api/auth/[...all] — Better Auth catch-all Handler. Nicht anfassen ohne Better Auth Docs zu lesen.
• api/pexels-video — Server-seitiger Proxy für Pexels-Video-Anfragen (API-Key bleibt serverseitig).

---

env-Variablen (Next.js-Seite)

BETTER_AUTH_SECRET
BETTER_AUTH_URL
NEXT_PUBLIC_CONVEX_URL

---

Canvas Route (app/(app)/canvas/[canvasId]/)

Server Component (page.tsx):

1. Auth-Check (SSR): getAuthUser() ruft Dashboard zurück, wenn nicht authentifiziert
2. Canvas-Existenz-Check: api.canvases.get prüft ob Canvas existiert und gehört zum User
3. Rendering: Wenn alles ok → CanvasShell rendern
4. Error Boundary: error.tsx fängt Fälle ab, wo Canvas-Daten fehlen

Client Component (CanvasShell):

• Injiziert über useEffect nach SSR, um Hydration-Sync sicherzustellen
• Verwaltet Canvas-Sync-Kontext (CanvasSyncContext)
• Responsive Resizing Sidebar/Main-Layout
• Rail-Mode Unterstützung (collapsible Sidebar)

---

Konventionen

• Alle Server Components zuerst prüfen ob sie User-Daten brauchen (getAuthUser())
• Alle Client Components mit "use client" markieren
• Auth-Queries über useAuthQuery (aus hooks/use-auth-query.ts) statt useQuery, um Auth-Races zu vermeiden
• Fehlerbehandlung immer mit Error Boundaries und Toasts
• SEO-Optimierung für Landing-Page (page.tsx)