tessera-ctl/.planning/phases/04-marketplace-portal-navigation/04-CONTEXT.md

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_refs>

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

</canonical_refs>

<code_context>

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

</code_context>

## 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