# Phase 4: Marketplace & Portal Navigation - Context
**Gathered:** 2026-06-22
**Status:** Ready for planning
## Phase Boundary
Kategorisierter Marketplace zum Browsen aller verfuegbaren Module, Aktivierung/Deaktivierung pro Mandant durch Super-Admin via Mandanten-Kontext-Wechsel, dynamische Sidebar-Integration aktivierter Module mit Suche/Filter, und Modul-Detail-Ansicht. Kein Dashboard, kein Payment, keine volle Impersonation — nur Mandanten-Kontext-Selector im Marketplace-/Modul-Bereich fuer Super-Admin.
## Implementation Decisions
### Marketplace-Layout
- **D-01:** Marketplace als Karten-Grid (wie VS Code Extensions / App Store). Jede Karte zeigt Icon, Name, Kurzbeschreibung, Kategorie-Badge, Aktivierungs-Status.
- **D-02:** Suchleiste + Kategorie-Filter oben auf Marketplace-Seite. Live-Filter waehrend Tippen. Kategorie-Chips oder Dropdown.
- **D-03:** Empty State: Freundliche Illustration + Text ("Noch keine Module verfuegbar").
### Aktivierungs-Flow
- **D-04:** Super-Admin bekommt leichtgewichtigen Mandanten-Kontext-Selector im Marketplace-Bereich (Dropdown zur Mandanten-Auswahl). Aktivierung/Deaktivierung erfolgt aus Perspektive des gewaehlten Mandanten. Kein volles Impersonation-System — nur Kontext-Wechsel fuer Modul-Management (volle Impersonation bleibt v2: FEAT-V2-04).
- **D-05:** Regulaerer Admin aktiviert Module direkt fuer seinen eigenen Mandanten (kein Kontext-Wechsel noetig).
### Claude's Discretion
- Marketplace Filter/Status-Unterscheidung: Tab-Ansicht vs. Badge-System vs. Kombination — basierend auf UX Best Practices
- Bestaetigungs-Dialog bei Aktivierung: Dialog vs. sofortige Aktion mit Undo-Toast — UX-Entscheidung
- Visuelles Feedback nach Aktivierung: Toast + Badge-Update vs. Animation — passend zum existierenden Design
- Sidebar Kategorien-Darstellung: Bestehendes Accordion beibehalten vs. flache Liste mit Gruppen-Header — basierend auf Modul-Anzahl und UX
- Sidebar collapsed Modus: Modul-Icons anzeigen vs. nur Haupt-Navigation — basierend auf existierender Sidebar-Logik
- Sidebar Suchfeld: Im Kategorien-Bereich vs. globale Header-Suche vs. beides — basierend auf PRTAL-05 und Komplexitaet
- Modul-Detail-Ansicht Tiefe: Ausfuehrlich (App-Store-Stil) vs. kompakt — passend fuer v1 Modul-Anzahl
- Marketplace-Detail vs. Modul-Nutzung Navigation: Separate Seiten vs. Tabs vs. anderes Pattern — basierend auf App Router Architektur
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Projekt-Kontext
- `.planning/PROJECT.md` — Gesamtprojekt, Core Value, Constraints
- `.planning/REQUIREMENTS.md` — Phase-4-Requirements: MRKT-01..04, PRTAL-02, PRTAL-03, PRTAL-05
- `.planning/ROADMAP.md` — Phase-Ziel und Success Criteria
### Vorherige Phasen
- `.planning/phases/01-foundation-portal-shell/01-CONTEXT.md` — Design-Entscheidungen, OKLCH Tokens, Sidebar-Verhalten (D-01..D-06), Header (D-07..D-09), Farbschema
- `.planning/phases/02-authentication-multi-tenancy/02-CONTEXT.md` — Auth, Rollen (D-12: Super-Admin/Admin/User), Mandanten-Modell (D-08..D-11), RLS
- `.planning/phases/03-module-system-domaincheck/03-CONTEXT.md` — Module SDK, Registry, Kategorien (D-04..D-09), ModuleCard Pattern, Lazy Loading
### Research
- `.planning/research/STACK.md` — Technologie-Stack (NestJS 11, Prisma 7, Next.js 16, shadcn/ui)
- `.planning/research/ARCHITECTURE.md` — Architektur-Patterns
## Existing Code Insights
### Reusable Assets
- `apps/web/src/components/layout/sidebar.tsx` — Sidebar mit Kategorie-Accordion, fetcht `/modules/active`, zeigt Module gruppiert nach Kategorie. Muss erweitert werden fuer Suche/Filter.
- `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx` — Bestehende ModuleCard Komponente, wiederverwendbar fuer Marketplace-Grid.
- `apps/web/src/app/(portal)/modules/[category]/page.tsx` — Kategorie-Seite mit Modulen, Pattern fuer Marketplace-Seite.
- `apps/api/src/module-registry/module-registry.controller.ts` — REST API: GET /modules (alle), GET /modules/active (aktive pro Tenant), POST activate/deactivate. Komplett vorhanden.
- `apps/api/src/module-registry/module-registry.service.ts` — Service mit findAll, findActiveForTenant, activateForTenant, deactivateForTenant, seedModule.
- `apps/api/prisma/schema.prisma` — Module Model (slug, name, version, category, description JSON, icon, isSystem) + TenantModuleActivation (tenantId, moduleId, isActive).
### Established Patterns
- NestJS Module mit Controller + Service + DTOs
- Next.js App Router Route Groups: `(auth)` fuer Login, `(portal)` fuer authentifizierte Seiten
- Zustand Stores fuer Client-State (sidebar-store, auth-store)
- next-intl fuer alle UI-Strings
- Fetch mit `credentials: 'include'` fuer API-Aufrufe
- Rollen-basierte UI-Sichtbarkeit (isAdmin, isSuperAdmin Checks in Sidebar)
### Integration Points
- Marketplace-Seite braucht Route `/marketplace` im `(portal)` Route Group
- Sidebar-Suche muss bestehendes Accordion-System erweitern
- Tenant-Kontext-Selector fuer Super-Admin braucht Tenant-Liste API (existiert evtl. ueber admin/tenants)
- Aktivierungs-Buttons muessen bestehende POST /modules/:id/activate API nutzen
- Module Description ist JSON (mehrsprachig) — Marketplace muss richtige Sprache anzeigen
## Specific Ideas
- Mandanten-Kontext-Selector: Dropdown in Marketplace-Header-Bereich, nur fuer Super-Admin sichtbar. Zeigt aktuell gewaehlten Mandanten. Wechsel aktualisiert Aktivierungs-Status aller Modul-Karten.
- Marketplace-Route: `/marketplace` als Hauptseite, `/marketplace/[slug]` fuer Modul-Detail
- Karten-Grid responsive: 1 Spalte mobile, 2 Spalten Tablet, 3-4 Spalten Desktop
## Deferred Ideas
- **FEAT-V2-04: Volle Admin-Impersonation** — Komplettes "Als Mandant agieren"-Feature kommt in v2. Phase 4 baut nur leichtgewichtigen Kontext-Selector fuer Modul-Management.
---
*Phase: 4-Marketplace & Portal Navigation*
*Context gathered: 2026-06-22*