Ausführliche Dokumentation der Struktur, Bereiche und Technologiestack des Projekts.

Projektübersicht

Dieses Dokument fasst den aktuellen Stand der Web-Frontend-Anwendung für das St. Georg App zusammen. Es beschreibt die Benutzerbereiche (Admin, TZ, Sternsinger, Messdiener, Pfadfinder, Jugendgottesdienst), deren Navigation sowie wichtige technische Aspekte für Entwickler:innen. Die Beispiele orientieren sich an der tatsächlichen Projektstruktur unter apps/web/src.

Inhaltsverzeichnis

Bereiche und Seitenstruktur

Die Anwendung folgt einem Bereichskonzept, bei dem je nach aktiver Organisation unterschiedliche Menüs geladen werden. Die Organisationen sind derzeit:

Admin

Hauptseite: /admin – innerhalb der Route apps/web/src/routes/_authenticated/admin/index.tsx werden Basisinformationen der Admin-Oberfläche gerendert.
Unterseiten: Benutzerverwaltung (/admin/organizations, /admin/users) – siehe Komponenten unter apps/web/src/routes/_authenticated/admin und apps/web/src/server/users.ts.
Zugriff: Administrationsbereich ist über TanStack Router unter /admin/* eingebunden. Die Navigation zur Erstellung neuer Organisationen erfolgt über apps/web/src/components/form/create-organization-form.tsx, die authClient.organization.create benutzt.

Messdiener

Route: /messdiener mit entsprechendem Entry in apps/web/src/routes/_authenticated/messdiener/index.tsx.
Navigation: Gruppen wie „Übersicht“, „Cloud“, „Gruppen“, „Shop“, „Stationsspiel“, „Film“ und „Sonderurlaubsanträge“ liegen im JSON-Feld metadata.navigation.groups der aktiven Organisation (Beispiel in der Benutzerdatenbank).
Unterseiten:
- /messdiener/gruppen
- /messdiener/shop mit Unterpunkten /teilnehmer, /produkte, /statistik
- /messdiener/karte und /messdiener/fragebogen
- /messdiener/songs, /messdiener/shop, /messdiener/urlaub
Komponenten: Navigation wird von apps/web/src/components/layout/nav-main.tsx erzeugt, liest metadata.navigation und unterstützt external-Links (öffnen neuen Tab mit Lucide Icon SquareArrowUpRight).

Pfadfinder

Route: /pfadfinder (siehe apps/web/src/routes/_authenticated/pfadfinder/index.tsx).
Navigation: analog über aktives Organisation-Metadata gesteuert. Menüs adaptieren sich je nach gespeicherten Gruppen und Untersektionen.

Sternsinger

Route: /sternsinger (apps/web/src/routes/_authenticated/sternsinger/index.tsx).
Navigation: Imseinverhältnis zu Messdiener, greift ebenfalls auf metadata.navigation zurück.
Besonderheit: Sharesmap? (weitere Module können analog angehängt werden).

TZ

Route: /tz (apps/web/src/routes/_authenticated/tz/index.tsx).
Verwendung: Bereich für „Technische Zeit“ (TZ), ebenfalls dynamisch über Navigation-Metadaten gesteuert.

Jugendgottesdienst

Route: /jugendgottesdienst (apps/web/src/routes/_authenticated/jugendgottesdienst/index.tsx).
Navigation: Basiert auf gleicher Struktur.

Technische Architektur

Technologie-Stack

Frontend: Bun + TanStack Router + React 19 + shadcn/ui + Tailwind CSS.
Authentifizierung: better-auth mit Client-Hook authClient (siehe apps/web/src/lib/auth-client.ts).
Routing: TanStack React Router mit createFileRoute, generiert apps/web/src/routeTree.gen.ts.
Serverfunktionen: @tanstack/react-start für createServerFn, z. B. getUser, getOrganizations, getActivOrganization in apps/web/src/server.
Navigation: Wird über Organisations-Metadaten (metadata.navigation.groups) gesteuert. Das JSON-Format enthält label, sections, items und optional external für externe Links.
UI: Shadcn-Komponenten (Dropdown, Sidebar, Skeleton, Avatar etc.) mit Icons von lucide-react.

Layout

Root-Document: apps/web/src/routes/__root.tsx baut SidebarProvider, AppSidebar, SidebarInset und Outlet auf. Der Loader befüllt den Kontext mit Session, Organisationen und Navigationsgruppen, sodass SSR und Hydration passen.
Sidebar: apps/web/src/components/layout/app-sidebar.tsx orchestriert TeamSwitcher, NavMain, NavUser.
Navbar Skeletons: Werden aus apps/web/src/components/ui/skeleton.tsx aktiviert, so dass sowohl Team-Switcher als auch Nav die passende Größe behalten.

Der Loader ruft getActivOrganization() ab, filtert metadata.navigation via parseNavigationGroups (in apps/web/src/lib/navigation.ts).
NavMain akzeptiert die serverseitig erstellten Gruppen als Prop und überwacht authClient.useActiveOrganization() für Aktualisierungen nach dem Team-Wechsel.
TeamSwitcher benutzt authClient.useListOrganizations() und authClient.organization.setActive, zeigt Ladezustände mit Skeletons.

Entwicklung

Entwicklungsumgebung

Lokales Starten: bun dev oder turbo dev für das Webpaket, turbo -F @stgeorg-app/db db:start etc.
Code-Generierung: apps/web/src/routeTree.gen.ts vom TanStack Router automatisch erzeugt.
Typisierung: TypeScript 5+, strict-Modus. Pfade über tsconfig mit @/*.
UI: Shadcn + Tailwind mit tailwind.config analog. Radix-Layouts (Sidebar, Dropdown etc.) sind im Ordner apps/web/src/components/ui.

Dev-Flow

Änderungen im Layout/Navigation → apps/web/src/components/layout/ (Sidebar, Navigation, TeamSwitcher).
Neue Server-Endpunkte → apps/web/src/server/* via createServerFn plus zusätzliche Routes.
Auth-Handling → apps/web/src/lib/auth-client.ts (basiert auf better-auth, organizationClient).
Testdaten & Migrationen → packages/db/src/schema/auth.ts.

Best Practices

Navigation lebt in den Organisation-Metadaten (siehe metadata.navigation). Neue Links werden in der Datenbank ergänzt und erscheinen automatisch, weil NavMain diese Struktur direkt nutzt.
TeamSwitcher verwendet authClient.useListOrganizations + setActive. Nach einem Wechsel ruft NavMain die aktualisierte Organisation (via Hook) ab.
Bei Änderungen am Layout: immer apps/web/src/components/ui anpassen (Buttons, Skeletons, Sidebar-Styles).
Entwickler:innen: authClient agiert als zentrale API-Schicht, alles was Nutzer/Organisationen betrifft, passiert über diesen Client.

Weiteres

Admin-Tools: apps/web/src/components/form/create-organization-form.tsx, apps/web/src/routes/_authenticated/admin/*.
Navigation mit externem Link: Das Flag external fügt im Menü rechts das Icon SquareArrowUpRight hinzu und öffnet den Link mit target="_blank".
Skeletons: apps/web/src/components/ui/skeleton.tsx wird für alle Ladezustände verwendet (TeamSwitcher, NavMain).
Zusätzliche Bereiche: Alle Organisationen wie Pfadfinder, TZ, Sternsinger greifen auf dieselbe Meta-Struktur; neue Bereiche brauchen nur entsprechende Datensätze und ggf. Routen unter apps/web/src/routes/_authenticated.

Projektübersicht St. Georg