Johann Stein

Abitur-Planer – technische Übersicht

Architektur, Datenflüsse, Regel-Engine und Deployment-Hinweise für die neue Abitur-Planungs-App.

1. Architektur

Frontend und Backend laufen innerhalb der bestehenden Next.js 14 App. Authentifizierung erfolgt über Firebase (Magic-Link). API-Routen werden mit einem Firebase-ID-Token geschützt und nutzen Firestore als persistenten Speicher. Integrationen wie Notion und die Regel-/Optimierungslogik leben in einer separaten Workspace-Library@johannstein/abitur-planner.


flowchart TD
  browser[Browser UI]
  api[Next.js API-Routen]
  notion[Notion API]
  firestore[(Firestore)]
  logic[@johannstein/abitur-planner]

  browser -->|REST + Firebase ID Token| api
  api --> logic
  api --> firestore
  api -->|optional Sync| notion
  logic --> firestore

2. Datenmodell

Die folgenden Strukturen werden in Firestore pro Nutzer gespeichert. Multi-Tenancy ergibt sich durch den Firebase-UID-Namespace. Secrets werden mit AES-256-GCM verschlüsselt (Schlüssel via PLANNER_ENCRYPTION_KEY).


CourseSelection {
  courseId: string
  isEnrolled: boolean
  isLeistungskurs: boolean
  examRole: 'LK1'|'LK2'|'PF3'|'PF4'|'PF5'|null
  isBilingual?: boolean
}

SemesterGrade {
  courseId: string
  semester: 'Q1'|'Q2'|'Q3'|'Q4'
  points: number | null
  source: 'notion' | 'manual' | 'autofill'
  locked: boolean
}

NotionSettings {
  enabled: boolean
  integrationTokenEncrypted?: string
  databaseIdEncrypted?: string
  lastSyncedAt?: string
}

3. Regel-Engine & Optimierer

  • Regel-Engine: deklarativ über TypScript-Definitionen mit Unit-Tests (Vitest) abgedeckt. Bewertet Kernpflichten (Deutsch/Mathe durchgehend, Naturwissenschaft, PF-Zuordnung etc.).
  • Optimierer: heuristische Auswahl der besten 24 GK-Halbjahre plus automatische Einbringung aller LKs und Deutsch. Rechnet den Punktschnitt in eine approximierte Abiturnote um und liefert Begründungen.
  • Autofillout: Projektion leerer Noten anhand bestehender Durchschnittswerte mit wählbarer Leistungs-Abweichung (–20 % bis +50 %).

4. Notion-Integration

  1. In Notion eine interne Integration anlegen, Token kopieren.
  2. Database-ID der Noten-Datenbank (Spalten: Kurs, Ø Q1–Ø Q4) ermitteln.
  3. Im Abitur-Planer Token & Database-ID eingeben, optional „Zugangsdaten speichern“ aktivieren.
  4. Synchronisation lädt alle Kurse (ausgenommen „Insgesamt“/„Organisation“), sperrt übernommene Werte und lässt leere Felder editierbar.
  5. Manuelle Noten bleiben erhalten; Überschreiben erfolgt nur nach Bestätigung.

Die API kommuniziert ausschließlich serverseitig mit Notion, Tokens verlassen den Server nie im Klartext.

5. Deployment

Build- und Start-Kommandos entsprechen dem bestehenden Setup (pnpm + pm2).


# .env.production
NEXT_PUBLIC_FIREBASE_API_KEY=…
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=…
NEXT_PUBLIC_FIREBASE_PROJECT_ID=…
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=…
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=…
NEXT_PUBLIC_FIREBASE_APP_ID=…
GOOGLE_SERVICE_ACCOUNT_KEY_B64=…
PLANNER_ENCRYPTION_KEY=32+ character secret

# pm2 ecosystem uses npm run start
pnpm install --frozen-lockfile
pnpm --filter web build
pm2 restart ecosystem.config.js --only web

6. Anwender-Workflow

  1. Login via Magic-Link, anschließend Abitur-Planer öffnen.
  2. Kursbelegung im Dialog prüfen und Rollen (LK/PF) setzen.
  3. Noten aus Notion synchronisieren oder manuell/über Autofillout ergänzen.
  4. Regel-Check beobachten, Verstöße per Button „Einbringen“ und Optimierer korrigieren.
  5. Optimale Einbringung speichern und für spätere Sessions wieder laden.