mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/NAVIGATION_IA_DESIGN_PRINCIPLES.md

Navigation & Informationsarchitektur – Designprinzipien (Extraktion)

Status: Analyse / Arbeitspapier
Stand: 2026-07-04
Geltungsbereich: App-Navigation, Bereichs-Shells, Admin-IA, Responsive Shell — keine Seiteninhalte oder Domänenlogik

Serie: Designprinzipien für Produktfamilie · Dokument 8 von n
Vorgänger: DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md

Kernkomponenten:

Bereich	Pfade
Hauptnavigation	frontend/src/config/appNav.js
Erfassung	frontend/src/config/captureNav.js, layouts/CaptureShell.jsx
Einstellungen	frontend/src/config/settingsNav.js, layouts/SettingsShell.jsx
Admin	frontend/src/config/adminNav.js, layouts/AdminShell.jsx, RequireAdmin.jsx
KI-Analyse (Kategorien)	frontend/src/config/analysisCategories.js, pages/Analysis.jsx
Routing	frontend/src/App.jsx
Desktop-Sidebar	frontend/src/components/DesktopSidebar.jsx
Responsive CSS	frontend/src/app.css (--nav-h, .bottom-nav, .analysis-split, .desktop-sidebar)
Abnahme-Doku	docs/issues/GUI_IA_ADMIN_NAV_2026-04-05.md
Responsive-Spec	.claude/docs/functional/RESPONSIVE_UI.md

---

Modul

Navigation & Informationsarchitektur (IA)

Schichtenmodell für die PWA: eine primäre Hauptnavigation (6–7 Bereiche), darunter Bereichs-Shells mit eigener Sub-Navigation, getrennte Admin-Realm, Auth-Gates und ein Breakpoint für Mobile vs. Desktop.

---

Fachliche Verantwortung

Das Modul übernimmt:

1. Hauptnav-SSoT — Reihenfolge, Labels, Icons, Admin-Sichtbarkeit (getMainNavItems).
2. Routing-Struktur — Welche URL gehört zu welchem Bereich (Übersicht, Erfassen, Verlauf, Ziele, Analyse, Einstellungen, Admin).
3. Sub-Navigation pro Bereich — Capture-Hub, Settings-Tabs, Admin-Gruppen, Analyse-Kategorien.
4. Layout-Muster — Bottom-Nav (mobil), Sidebar (Desktop), analysis-split für tiefe Bereiche.
5. Zugriffskontrolle (UI) — RequireAdmin, Admin-Link nur bei role === 'admin'.
6. Active-State — Nested Routes (Erfassung unter /capture, Admin unter /admin/*).
7. PWA-Tauglichkeit — Safe Area, Scrollbare Bottom-Nav, Content-Padding.

Es übernimmt nicht:

• Backend-Autorisierung (→ AUTH_SESSION_DESIGN_PRINCIPLES.md)
• Feature-Entitlements in der Nav (Tier-Gates an Endpoints/Widgets, nicht an jedem NavLink)
• Inhaltliche Tab-Logik innerhalb von Verlauf/Analyse (Seiten concern)

IA-Modell (Nutzerperspektive)

Ebene	Mental Model	Beispiel-Routen
Primär	Wo bin ich in der App?	/, /capture, /history, /goals, /analysis, /settings
Sekundär (Shell)	Was mache ich in diesem Bereich?	/weight, /admin/g/features, /settings/dashboard-layout
Tertiär (Seite)	Tabs/Filter innerhalb einer Maske	Verlauf-Tabs, Analyse-Kategorien

Strategisch vs. taktisch (Ziele)

Ebene	Ort	Zweck
Strategisch	/goals (Hauptnav)	Ziele definieren, Prioritäten, Focus Areas
Taktisch	/custom-goals (Erfassung)	Tägliche Ist-Werte für eigene Ziele
Auswertung	/history	Trends, Charts, Vergleiche

---

Administrierte vs. code-definierte Konfiguration

Konfiguration	Speicherort	Wer pflegt?
Hauptnav-Reihenfolge & Labels	appNav.js	Entwickler
Erfassungs-Kacheln & Shell-Nav	captureNav.js	Entwickler
Admin-Gruppen & Hub-Karten	adminNav.js	Entwickler
Settings-Subnav	settingsNav.js	Entwickler
Analyse-Kategorie-Reihenfolge	analysisCategories.js	Entwickler
KI-Prompt-Kategorien (Runtime)	DB ai_prompts.category	Admin (Prompts)
React-Routes	App.jsx	Entwickler (muss zu Nav-Configs passen)

---

Designprinzipien

1. Eine Quelle für die Hauptnavigation

Prinzip	getMainNavItems(isAdmin) liefert dieselbe Item-Liste für Bottom-Nav und Desktop-Sidebar — keine parallelen Hardcodings.
Begründung	Reihenfolge und Labels bleiben synchron; Admin-Conditional an einer Stelle.
Quelle	appNav.js, App.jsx, DesktopSidebar.jsx
Tragfähigkeit	hoch
Einschränkung	Active-State-Logik ist in zwei Dateien dupliziert (navItemActive / sidebarLinkActive).

2. Feste primäre IA-Reihenfolge (Produkt-Story)

Prinzip	Übersicht → Erfassen → Verlauf → Ziele → Analyse → Einstellungen → [Admin] — spiegelt Nutzerfluss: sehen → eingeben → auswerten → steuern → interpretieren → konfigurieren.
Begründung	Ziele als eigener Hauptpunkt (nicht unter Analyse versteckt); klare Trennung Capture vs. History vs. Analysis.
Quelle	GUI_IA_ADMIN_NAV_2026-04-05.md; appNav.js
Tragfähigkeit	hoch
Einschränkung	Produkt-spezifisch; andere Apps können andere Reihenfolge brauchen.

3. Config-Dateien pro Bereich (Nav-as-Data)

Prinzip	Sub-Navigation lebt in dedizierten Config-Modulen (captureNav, adminNav, settingsNav, analysisCategories) — Shell-Komponenten iterieren nur.
Begründung	Neue Erfassungsmaske = Eintrag in Config + Route; kein Nav-HTML in jeder Page.
Quelle	captureNav.js Kommentar „Pfade müssen mit Routes übereinstimmen“
Tragfähigkeit	hoch
Einschränkung	Kein Build-Time-Check Config ↔ Routes.

4. Bereichs-Shells für tiefe Navigation

Prinzip	Capture, Settings und Admin nutzen Shell-Layouts mit <Outlet />; Nutzer wechselt Sub-Bereiche ohne Hauptnav zu verlassen.
Begründung	Erfassung hat 12+ Masken — wären als Hauptnav-Einträge unbrauchbar.
Quelle	CaptureShell, SettingsShell, AdminShell
Tragfähigkeit	hoch
Einschränkung	Verlauf und Analyse haben eigene Tab-Muster (kein gemeinsames Shell-Config).

5. Wiederverwendbares analysis-split-Layout

Prinzip	Admin, Settings und KI-Analyse teilen CSS-Muster: mobil horizontale Chips, Desktop linke Spalte + __main für Inhalt.
Begründung	Ein visuelles Muster für „Kategorie links, Arbeit rechts“; weniger UI-Drift.
Quelle	AdminShell.jsx, SettingsShell.jsx, Analysis.jsx, app.css
Tragfähigkeit	hoch
Einschränkung	Capture nutzt eigenes capture-shell (Emoji-Icons, Hub-Kacheln).

6. Admin: Gruppen in der Shell, Seiten über Hub

Prinzip	Shell-Nav zeigt nur Admin-Gruppen (+ Übersicht); konkrete Seiten als Karten auf /admin/g/:groupId.
Begründung	Skaliert bei wachsender Admin-Oberfläche; keine 20er-Sidebar.
Quelle	adminNav.js (ADMIN_GROUPS, getAdminShellNavEntries)
Tragfähigkeit	hoch
Einschränkung	Ein Klick mehr als flache Nav; bewusster Trade-off.

7. Admin als eigener Realm

Prinzip	/admin/* hinter RequireAdmin; kein Admin-Block mehr in Einstellungen; Profil-Anlage nur Admin → Benutzerverwaltung.
Begründung	Trennung Nutzer- vs. Betreiber-Kontext; weniger Verwechslung.
Quelle	RequireAdmin.jsx, GUI_IA_ADMIN_NAV_2026-04-05.md
Tragfähigkeit	hoch
Einschränkung	UI-Guard ersetzt nicht Backend-require_admin auf APIs.

8. Route-Guard mit Nutzer-Feedback

Prinzip	Nicht-Admin auf /admin → Redirect / mit state.adminDenied; Dashboard zeigt Hinweis.
Begründung	Stilles Scheitern vermeiden; klare Erwartung.
Quelle	RequireAdmin.jsx, Dashboard.jsx
Tragfähigkeit	hoch
Einschränkung	—

9. Nested Active-State für Section-Prefixes

Prinzip	Custom Active-Logik: /capture aktiv bei allen Erfassungs-Pfaden; /admin bei gesamten Admin-Baum; /goals mit end: true (exakt).
Begründung	React-Router end allein reicht für Section-Gruppen nicht.
Quelle	navItemActive, adminShellEntryIsActive
Tragfähigkeit	hoch
Einschränkung	Neue Section-Prefixes brauchen explizite Regel.

10. Erfassungs-Hub + direkte Deep-Links

Prinzip	/capture = Kachel-Hub; jede Maske auch direkt erreichbar (/weight, …); Shell-Nav immer sichtbar.
Begründung	Onboarding über Hub; Power-User/Dashboard-Links springen direkt.
Quelle	CaptureHub, CAPTURE_HUB_TILES
Tragfähigkeit	hoch
Einschränkung	Hub und Shell-Nav listen dieselben Ziele (Doppelpflege).

11. Einstellungen: nur aktives Profil

Prinzip	Settings = Self-Service für aktives Profil (Name, E-Mail, Avatar, Quality-Filter); keine Profil-Liste für Endnutzer.
Begründung	Multi-Profil-Verwaltung ist Admin-Aufgabe; reduziert Komplexität.
Quelle	SettingsPage.jsx, IA-Doku
Tragfähigkeit	hoch
Einschränkung	Session-bound Profile-Id-Schwäche bleibt Backend-Thema.

12. Settings-Subnav für Layout & Export

Prinzip	Konfiguration schwerer Features (Dashboard-Layout, PDF-Berichte, Referenzwerte) als eigene Settings-Routen unter Shell — nicht in „Allgemein“ verstecken.
Begründung	Entspricht DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md (Nutzer-Konfigurator).
Quelle	settingsNav.js
Tragfähigkeit	hoch
Einschränkung	Admin-Dashboard-Default liegt unter /admin/... (getrennte Rolle).

13. KI-Analyse: Ergebnis im Hauptspalt

Prinzip	Neue Analyse-Ergebnisse rendern in analysis-split__main, nicht in der Kategorie-Nav — Nav bleibt wählbar.
Begründung	Lange Ergebnisse verdrängen sonst die Prompt-Auswahl (Mobile).
Quelle	GUI_IA_ADMIN_NAV_2026-04-05.md, Analysis.jsx
Tragfähigkeit	hoch
Einschränkung	—

14. Ein Breakpoint Mobile / Desktop (1024px)

Prinzip	< 1024px: Bottom-Nav + Mobile-Header; ≥ 1024px: Desktop-Sidebar, Bottom-Nav ausgeblendet, breiterer Content. Kein separates Tablet-Layout.
Begründung	Einfache Spec, PWA-first; iPad im Portrait = Mobile-Verhalten.
Quelle	RESPONSIVE_UI.md, app.css
Tragfähigkeit	hoch
Einschränkung	Große Phones und kleine Tablets identisch behandelt.

15. PWA Safe Area für Bottom-Navigation

Prinzip	--nav-h, --nav-pad-top, env(safe-area-inset-bottom) auf .bottom-nav; Content-padding-bottom inkl. Nav-Höhe; horizontal scrollbare Nav bei vielen Items.
Begründung	iPhone Home-Indicator und Notch — kein Clipping, kein verdeckter Content.
Quelle	app.css, IA-Doku
Tragfähigkeit	hoch
Einschränkung	Safe Area nur auf Nav/Content-Padding, nicht global überall.

16. Auth-Routen außerhalb der App-Shell

Prinzip	Login, Register, Verify, Reset-Password rendern ohne Bottom-Nav/Sidebar — minimale Vollbild-Cards.
Begründung	Keine Navigation ohne Session; klarer Fokus.
Quelle	App.jsx (early returns vor AppShell)
Tragfähigkeit	hoch
Einschränkung	Public Routes nicht zentral in einer Route-Config.

17. Rollen-sichtbare Nav-Einträge (UI only)

Prinzip	Admin-Link erscheint nur wenn isAdmin; Backend schützt APIs separat.
Begründung	Progressive disclosure; normale Nutzer sehen keinen toten Link.
Quelle	getMainNavItems(isAdmin)
Tragfähigkeit	hoch
Einschränkung	Security nicht durch Ausblenden ersetzt.

18. Deep-Link-State für Verlauf

Prinzip	Nav zu /history setzt optional state: { tab: 'overview' } — konsistenter Einstieg von Hauptnav.
Begründung	Verlauf merkt sich Tabs; Hauptnav soll nicht zufälligen alten Tab öffnen.
Quelle	App.jsx, DesktopSidebar.jsx, History.jsx
Tragfähigkeit	mittel
Einschränkung	Nur für History implementiert, nicht app-weit.

---

Nicht übernehmen

1. Hauptnav an mehreren Stellen hardcoden — immer appNav.js.

2. Admin-Funktionen in Einstellungen — eigener /admin-Bereich.

3. Alle Erfassungsmasken in die Bottom-Nav — Shell + Hub skaliert.

4. Alle Admin-Seiten in der Shell-Sidebar — Hub-Gruppen-Muster beibehalten.

5. Nav-Config ohne Route-Pflege — jeder neue Pfad: Config + App.jsx + ggf. Active-State.

6. UI-Admin-Guard ohne Backend-Guard — RequireAdmin ist UX, APIs brauchen require_admin.

7. Zwei Tablet-/Desktop-Breakpoints — Mitai: ein Cut bei 1024px.

8. Safe Area ignorieren — PWA auf iOS bricht sonst an Bottom-Nav.

9. Profil-Liste für Endnutzer in Settings — Multi-Profil = Admin.

10. Feature-Tier-Logik in Nav-Komponenten — Entitlements an Widgets/APIs (FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md).

11. Inkonsistente Layout-Muster pro Bereich — wo analysis-split passt, nicht neues Ad-hoc-Layout erfinden.

12. Orphan-Routes ohne Nav-Ergänzung — z. B. /subscription, /workflow-editor/:id existieren außerhalb Haupt-IA; bewusst dokumentieren, nicht unkontrolliert multiply.

13. Active-State nur per Router-Default — Section-Prefixes (/capture/*, /admin/*) brauchen explizite Regeln.

14. Analyse-Ergebnisse in der Nav-Spalte — verdrängt Prompt-Auswahl auf Mobile.

---

Modul-Inventar (Ist-Stand)

frontend/src/config/
├── appNav.js              # Hauptnav (6 + Admin)
├── captureNav.js          # Erfassungs-Hub + Shell
├── settingsNav.js         # Settings-Subnav
├── adminNav.js            # ADMIN_GROUPS, Shell-Entries
└── analysisCategories.js  # KI-Analyse-Gruppen

frontend/src/layouts/
├── CaptureShell.jsx
├── SettingsShell.jsx
├── AdminShell.jsx
└── RequireAdmin.jsx

frontend/src/components/
└── DesktopSidebar.jsx

frontend/src/App.jsx       # Routes + Bottom-Nav + Auth-Gates
frontend/src/app.css       # Shell, split, safe-area, 1024px breakpoint

Hauptnav (7 Einträge mit Admin): Übersicht · Erfassen · Verlauf · Ziele · Analyse · Einstellungen · Admin

Admin-Gruppen (8): users · features · subscription · training · goals · prompts · system

---

Verwandte Dokumentation

• Abnahme-Stand: GUI_IA_ADMIN_NAV_2026-04-05.md
• Responsive-Spec: RESPONSIVE_UI.md
• Auth/Session: AUTH_SESSION_DESIGN_PRINCIPLES.md
• Dashboard-Konfigurator: DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md
• Gitea #30 (Responsive UI, teilweise erledigt)

---

Geplante Folgedokumente (Serie)

#	Modul	Status
1–7	…	✅
8	Navigation / IA	✅ dieses Dokument
9	Migration & Deploy	✅