stammtisch-hersbruck/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Kurbeler (bis 2026-09-08 „stammtisch-hersbruck.de"; Domain und Repository-Verzeichnis heißen weiterhin so) is a SvelteKit 5 application using Svelte 5's new runes syntax ($state, $props, etc.) with PocketBase as the backend. The app manages events, stages, riders, times and teams for a motorsport/cycling event organization.

The repository is a monorepo: the SvelteKit app lives in frontend/, the PocketBase instance in backend/.

Development Commands

Alle Frontend-Befehle laufen aus frontend/:

cd frontend

# Start development server (runs on http://stammtisch-hersbruck.de.localhost:31337)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type-check Svelte files
npm run check

# Type-check with watch mode
npm run check:watch

# Generate TypeScript types from the schema migration in backend/pb_migrations
# (no running instance, no token, no network access needed)
npm run generate-pocketbase-types

Backend (PocketBase) aus backend/:

cd backend

# PocketBase lokal starten (Admin-UI auf http://127.0.0.1:8090/_/)
docker compose up -d --build

# Stoppen
docker compose down

Architecture

Backend Integration (PocketBase)

• API Base URL: konfigurierbar über PUBLIC_PB_URL in frontend/.env. Default ist die produktive Instanz https://api.stammtisch-hersbruck.de; für das lokale Backend aus backend/ auf http://127.0.0.1:8090 umstellen.
• Schema: versioniert als Migration in backend/pb_migrations/, kommt per COPY ins Image (kein Bind-Mount — der würde das Image-Verzeichnis überdecken). Im Admin-UI erzeugte Migrationen liegen deshalb zunächst nur im Container und müssen mit docker compose cp ins Repo geholt werden; siehe backend/README.md.
• Type-safe client: The PocketBase client is typed using auto-generated types in frontend/src/lib/types.d.ts
• Collections: users, teams, team_invites, events, stages, riders, times, trails, trail_versions, trail_flags, trail_markers, trail_comments, event_participants, event_series, notification_prefs, notifications
• Regeln: Jede Zugriffsregel, die @request.auth.id erwähnt, beginnt mit @request.auth.id != "" && (…). Ohne diesen Vorspann ist eine leere Relation gleich dem leeren @request.auth.id einer anonymen Anfrage — ein Team ohne Admins stünde damit offen im Netz. Siehe backend/pb_migrations/1754501700_rules_require_login.js.
• Hooks: backend/pb_hooks/ enthält serverseitiges JS für das, was keine Collection-Regel abbilden kann — die öffentlichen Routen der Einladungslinks, den Uhrenabgleich, GET /api/directory/users (Benutzerverzeichnis des Superadmins), POST /api/team-invites/send (Einladungsmail) und die Benachrichtigungen. Jeder Route- und Event-Handler läuft in einer eigenen JS-Laufzeit; was neben routerAdd/onRecord… im Dateiscope steht, sieht der Handler nicht. Gemeinsamer Code gehört in ein Modul und wird per require(`${__hooks}/…`) im Handler geholt. Details in backend/README.md.
• Mails: SMTP im Admin-UI; dazu APP_URL (Adresse des Frontends, für die Links) und optional APP_NAME. Vorlagen liegen in backend/pb_hooks/views/ und werden mit $template.loadFiles(…).render(…) gefüllt.
• Benachrichtigungen: Kein Auslöser verschickt eine Mail — alle legen einen Eintrag in notifications, ein Cron-Job macht daraus eine Zusammenfassung pro Konto und Tag (6 Uhr). Voreinstellungen stehen doppelt, in notifications_lib.js und notificationPrefs.svelte.ts; beide Listen müssen zusammenpassen.
• Authentication: Handled through src/lib/stores/pocketbase.svelte.ts with the AuthStore class
• File handling: Use getFileURL(record, file, options) helper for PocketBase file URLs

State Management Pattern

The app uses Svelte 5 runes for state management with a custom store pattern:

1. Global stores in src/lib/stores/:

   • pocketbase.svelte.ts: PocketBase client, auth, and collection operations
   • app.svelte.ts: Global app state (theme, navigation, confirm dialogs, hotkeys)
   • teams.svelte.ts: Example of collection-specific store pattern

2. Collection store pattern:

   • Each collection has a context-based store (see teams.svelte.ts as template)
   • Use setTeamContext() in parent and getTeamContext() in children
   • Stores provide: records, refresh(), create(), edit(), remove()
   • The collections helper in pocketbase.svelte.ts provides reusable CRUD operations

3. Auth flow:

   • Auth state lives in auth store from pocketbase.svelte.ts
   • Cookie-based persistence available via auth.cookie flag
   • Auth store syncs with PocketBase authStore.onChange()

UI Components

• UI Library: Using shadcn-svelte components (bits-ui based)
• Component path alias: @/components/ui/* maps to $lib/components/ui/*
• Styling: Tailwind CSS 4.x with custom configuration
• Dark mode: Handled by mode-watcher package, toggle with toggleMode()
• Tooltips: Global tooltip action available from app.svelte.ts using tippy.js

Important Patterns

Svelte 5 Runes: This project uses Svelte 5 syntax exclusively:

• $state() for reactive state (not let with $:)
• $props() for component props
• $derived() for computed values
• {@render children?.()} for slot content

Type Generation: After modifying the schema migration in backend/pb_migrations/, run npm run generate-pocketbase-types to update frontend/src/lib/types.d.ts. The script reads the collections array straight out of the migration (frontend/scripts/schema-to-json.mjs) — schema and types come from the same versioned source and cannot drift apart. Commit the regenerated file.

Async Data Loading: Root layout (src/routes/+layout.svelte) shows pattern:

{#await load()}
  <!-- loading state -->
{:then _}
  <!-- main content -->
{/await}

Confirm Dialogs: Use app.confirm.request() for user confirmations (see events.svelte.ts remove pattern).

Hotkeys: Use app.hotkey(event, condition, callback) which auto-ignores input fields and contenteditable elements.

Tooltips: Never use the title attribute for tooltips — appwide. <Button> takes a tooltip="…" prop (it also becomes the aria-label, so icon-only buttons keep an accessible name); every other element uses the action: use:tooltip={{ content: '…' }} from app.svelte.ts. Both render through tippy.js, which the action initializes, updates and destroys.

Project Configuration

• Repo-Struktur: Monorepo mit frontend/ (SvelteKit) und backend/ (PocketBase). Ein einziges Git-Repo im Root.
• Dev server port: 31337 (strict mode, custom domain: stammtisch-hersbruck.de.localhost)
• Path alias: @/* resolves to ./src/lib/* (configured in frontend/svelte.config.js)
• Adapter: @sveltejs/adapter-node — Deployment läuft über Coolify mit node build. adapter-auto erkennt Coolify nicht und erzeugt kein build/.
• Node: engines verlangt ^20.19 || ^22.12 || >=24; mit engine-strict=true (.npmrc) bricht npm ci sonst mit EBADENGINE ab.
• Deployment-Env: PUBLIC_PB_URL muss dort gesetzt sein — sie wird zur Buildzeit eingesetzt, und die lokale .env ist gitignored.

File Structure Notes

• Routes are in src/routes/ following SvelteKit conventions. Routennamen immer auf Englisch (/invite/[token], nicht /einladung/[token]) — Oberflächentexte sind deutsch, Pfade nicht.
• Der Menüpunkt Team (/dashboard/team) führt Team und Kader an einer Stelle: Kennzahlen, Teamdaten, Einladungslinks und die Fahrerliste samt der Verwaltungsknöpfe der Teamleitung. Unter Einstellungen steht nur noch, was einen selbst betrifft (Profil, Benachrichtigungen, Flag-Typen) — dazu für Superadmins der Reiter Benutzer, das appweite Kontoverzeichnis.
• Konten löscht die Teamleitung nicht. Im Kader gibt es genau einen Eingriff an einer fremden Person: „Zugang zum Team entziehen" (teams.removeMember). Fahrer, Teilnahmen und Zeiten bleiben dabei stehen — sie sind die Geschichte des Teams, nicht die des Logins. Ein Konto löscht allein sein Inhaber (Einstellungen → Profil) oder der Superadmin (Einstellungen → Benutzer); users.deleteRule erzwingt das. Ein „Fahrer löschen" gibt es bewusst nicht mehr.
• Ein Fahrer, ein Name, eine Richtung: Ein Konto entsteht immer am Fahrer — die Teamleitung lädt per Mail ein (POST /api/team-invites/send), das Passwort setzt der Eingeladene selbst. Ein Passwort im Kader zu vergeben gibt es nicht mehr. Verknüpft wird der Fahrer beim Einlösen der Einladung; es gibt kein Verknüpfen bestehender Konten und kein Lösen. Angezeigt wird ausschließlich der Fahrername — der Kontoname wäre eine zweite Wahrheit, die niemand geradeziehen könnte, weil users.updateRule nur den Kontoinhaber selbst ändern lässt.
• Reusable components in src/lib/components/
• Stores use .svelte.ts extension for Svelte 5 runes
• Static assets in static/
• components.json configures shadcn-svelte CLI

When Working with This Codebase

• Always use Svelte 5 runes syntax, never legacy Svelte syntax
• Use the official Svelte MCP server to validate Svelte code
• Collection stores should follow the pattern in teams.svelte.ts
• PocketBase operations go through the collections helper for consistency
• UI components should use the shadcn-svelte imports from @/components/ui/