Kursplattform Development Guidelines

Version: 1.0 Last Updated: 2025-11-02 Purpose: Enforce consistent development patterns for the Kursplattform project

Quick Reference

This skill ensures you follow the project's critical rules:

•✅ ALWAYS use translations (never hardcoded text)
•✅ ALWAYS use custom UI components (SelectPicker, DatePicker, Modal, etc.)
•✅ ALWAYS use theme system (activeTheme.primary)
•✅ ALWAYS use AdminPageTemplate for admin pages
•❌ NO emojis (unless explicitly requested)
•❌ NO window.confirm/alert (use ConfirmModal/Toast)

🚨 CRITICAL RULES

1. Translation System - NIEMALS HARDCODIERTE TEXTE!

Available Namespaces:

•common - Allgemeine Actions (save, cancel, delete)
•admin - Admin Dashboard
•modals - Modal-spezifische Texte
•dashboard - User Dashboard
•auth - Login/Register
•ui - UI Components
•studio - Studio-Seiten
•credits - Credit-System
•course - Kurse
•public - Öffentliche Seiten
•header - Header/Navigation
•tarif - Tarife/Preise
•chat - Chat/Nachrichten

Pattern:

typescript

// ❌ WRONG
<Button>Speichern</Button>

// ✅ RIGHT
const { t } = useTranslation('admin');           // Hauptnamespace
const { t: tCommon } = useTranslation('common'); // Common für Actions
const { t: tModals } = useTranslation('modals'); // Modal-Texte

<Button>{tCommon('actions.save')}</Button>

// Common actions sind VERSCHACHTELT unter 'actions':
tCommon('actions.save')     // "Speichern"
tCommon('actions.cancel')   // "Abbrechen"
tCommon('actions.delete')   // "Löschen"
tCommon('actions.edit')     // "Bearbeiten"
tCommon('actions.create')   // "Erstellen"

Neue Features IMMER mit Übersetzungen:

•Neue Keys in /lib/translations/[namespace]/de.ts hinzufügen
•NIEMALS Text direkt in JSX: <Button>Speichern</Button> ❌
•IMMER mit Translation: <Button>{tCommon('actions.save')}</Button> ✅

2. UI Components - ALWAYS Use Custom Components

typescript

// In Modals/Forms ALWAYS use:
✅ SelectPicker (NOT Select or <select>)
✅ DatePicker (NOT input type="date")
✅ Checkbox, Input, Button, Badge
✅ ConfirmModal (NOT window.confirm)
✅ Toast (NOT window.alert)
✅ Modal (with variant="standard" or "compact")

// ❌ WRONG
<select>
  <option>Option 1</option>
</select>

// ✅ RIGHT
<SelectPicker
  options={[
    { value: '1', label: 'Option 1' },
    { value: '2', label: 'Option 2' }
  ]}
  value={selectedValue}
  onChange={setSelectedValue}
  placeholder="Auswählen..."
/>

Buttons with Icons - ALWAYS use icon prop:

typescript

// ❌ WRONG
<Button variant="primary">
  <Icon className="w-4 h-4" />
  Button Text
</Button>

// ✅ RIGHT
<Button variant="primary" icon={Icon}>
  Button Text
</Button>

// With iconPosition (defaults to left):
<Button icon={Icon} iconPosition="right">
  Button Text
</Button>

3. Theme System

typescript

// Import
import { activeTheme } from '@/config/theme'

// ❌ WRONG: Hardcoded colors
<div className="bg-blue-500">...</div>
<div style={{ color: '#3B82F6' }}>...</div>

// ✅ RIGHT: Use theme
<div style={{ background: activeTheme.primary }}>...</div>
<div style={{ background: activeTheme.gradient }}>...</div>

// Available themes:
// trustBlue, blue, orange, purple, green, nature, ocean, aqua, premium, dark
// Current theme: trustBlue (can be changed in theme.ts)

4. AdminPageTemplate - For ALL Admin Pages

typescript

// ❌ WRONG: Manual layout
<div className="max-w-7xl mx-auto p-6">
  <div className="flex items-center justify-between mb-8">
    <H1>Title</H1>
    <Button>Action</Button>
  </div>
  {/* content */}
</div>

// ✅ RIGHT: Use AdminPageTemplate
import AdminPageTemplate from '@/components/templates/AdminPageTemplate'

<AdminPageTemplate
  title="Page Title"
  subtitle="Page description"
  icon={IconComponent}
  stats={statsArray}  // Optional stats cards
  statsLoading={loading}
  breadcrumbs={[
    { label: 'Admin', href: '/admin' },
    { label: 'Current Page' }
  ]}
  actions={
    <Button variant="primary" icon={Plus}>
      Action Button
    </Button>
  }
>
  {/* Page content here */}
</AdminPageTemplate>

5. Modal Development Pattern

typescript

// First Modal: variant="standard" (full width)
// Nested Modal: variant="compact" (narrower)

// Multi-Tab Footer Pattern:
footer={
  <>
    <Button variant="secondary" onClick={onCancel}>
      {tCommon('actions.cancel')}
    </Button>
    <div className="flex gap-3">
      {!isFirstTab && (
        <Button onClick={handlePrevious}>Zurück</Button>
      )}
      {!isLastTab ? (
        <Button onClick={handleNext}>Weiter</Button>
      ) : (
        <Button variant="primary" onClick={handleSubmit}>
          {tCommon('actions.create')}
        </Button>
      )}
    </div>
  </>
}

6. Database Queries Pattern

typescript

// ALWAYS check active status
const kurse = await supabase
  .from('kurse')
  .select('*')
  .eq('aktiv', true)
  .eq('abgesagt', false)

// Use service role for bypassing RLS (when needed)
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

🎯 Common Patterns

Booking System

•Use database functions: book_course(), cancel_course_booking()
•Service: /src/services/booking.service.ts
•FIFO Credit-Management
•Konfigurierbare Stornofrist

Email Sending

•Provider: All-Inkl SMTP (Nodemailer)
•Templates in database (email_templates)
•Service: EmailService.sendTemplatedEmail()

Authentication

•Supabase Auth with RLS
•Middleware: /src/utils/supabase/middleware.ts
•Context: /src/lib/auth-context.tsx

📁 Project Structure

code

src/
├── app/                    # Pages (App Router)
│   ├── admin/             # Admin dashboard pages
│   ├── dashboard/         # User dashboard
│   └── api/stripe/        # Stripe webhooks
├── components/            # Reusable components
│   ├── ui/               # UI Components (ALWAYS use these!)
│   │   ├── Button.tsx
│   │   ├── Modal.tsx
│   │   ├── SelectPicker.tsx
│   │   ├── DatePicker.tsx
│   │   ├── ConfirmModal.tsx
│   │   └── Toast.tsx
│   ├── layout/
│   │   ├── Header.tsx
│   │   └── AdminHeader.tsx
│   ├── templates/
│   │   └── AdminPageTemplate.tsx
│   └── modals/           # Feature-specific modals
├── lib/
│   ├── translations/     # German translations
│   │   ├── common/de.ts
│   │   ├── admin/de.ts
│   │   └── modals/de.ts
│   └── hooks/
│       └── useTranslation.ts
├── services/             # Business logic
│   ├── email.service.ts
│   ├── credits.service.ts
│   └── booking.service.ts
└── config/
    └── theme.ts          # Theme configuration

✅ Checklist Before Creating Code

Before writing any component, modal, or page, check:

• Are translations used? (NO hardcoded text!)
• Are custom UI components used? (SelectPicker, DatePicker, etc.)
• Is theme system used? (activeTheme.primary)
• Is AdminPageTemplate used? (for admin pages)
• Are Button icons using icon prop?
• No emojis? (unless requested)
• No window.confirm/alert?

🔧 Tech Stack

•Next.js 14 (App Router)
•TypeScript
•Tailwind CSS
•Supabase (Database & Auth)
•Stripe (Payments)
•All-Inkl SMTP (Email)
•German UI with i18n support

When This Skill Activates

This skill should be loaded when:

•Creating or editing components (especially modals)
•Working on admin pages
•Implementing forms
•Adding translations
•Working with the theme system
•Database queries
•Any frontend development

Remember: Consistency is key! Follow these patterns for every piece of code.