423 lines
14 KiB
Markdown
423 lines
14 KiB
Markdown
# Phase 4: Marketplace & Portal Navigation - Pattern Map
|
|
|
|
**Mapped:** 2026-06-22
|
|
**Files analyzed:** 12 new/modified files
|
|
**Analogs found:** 12 / 12
|
|
|
|
## File Classification
|
|
|
|
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
|
|-------------------|------|-----------|----------------|---------------|
|
|
| `apps/web/src/app/(portal)/marketplace/page.tsx` | component (page) | request-response | `apps/web/src/app/(portal)/admin/modules/page.tsx` | exact |
|
|
| `apps/web/src/app/(portal)/marketplace/[slug]/page.tsx` | component (page) | request-response | `apps/web/src/app/(portal)/modules/[category]/page.tsx` | role-match |
|
|
| `apps/web/src/app/(portal)/marketplace/components/MarketplaceCard.tsx` | component | CRUD | `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx` | exact |
|
|
| `apps/web/src/app/(portal)/marketplace/components/MarketplaceSearch.tsx` | component | event-driven | (no direct analog) | -- |
|
|
| `apps/web/src/app/(portal)/marketplace/components/CategoryFilter.tsx` | component | event-driven | (no direct analog) | -- |
|
|
| `apps/web/src/app/(portal)/marketplace/components/StatusFilter.tsx` | component | event-driven | (no direct analog) | -- |
|
|
| `apps/web/src/app/(portal)/marketplace/components/TenantContextSelector.tsx` | component | request-response | `apps/web/src/app/(portal)/admin/tenants/page.tsx` | partial |
|
|
| `apps/web/src/app/(portal)/marketplace/components/ActivationDialog.tsx` | component | event-driven | `apps/web/src/app/(portal)/admin/tenants/page.tsx` (delete confirm modal) | role-match |
|
|
| `apps/web/src/app/(portal)/marketplace/components/Toast.tsx` | component | event-driven | (no direct analog) | -- |
|
|
| `apps/web/src/lib/stores/marketplace-store.ts` | store | event-driven | `apps/web/src/lib/stores/sidebar-store.ts` | role-match |
|
|
| `apps/web/src/components/layout/sidebar.tsx` | component (MODIFY) | request-response | self | exact |
|
|
| `apps/web/src/components/layout/sidebar-search.tsx` | component | event-driven | (no direct analog) | -- |
|
|
|
|
## Pattern Assignments
|
|
|
|
### `apps/web/src/app/(portal)/marketplace/page.tsx` (page, request-response)
|
|
|
|
**Analog:** `apps/web/src/app/(portal)/admin/modules/page.tsx`
|
|
|
|
**Imports pattern** (lines 1-6):
|
|
```typescript
|
|
'use client';
|
|
|
|
import { useCallback, useEffect, useState } from 'react';
|
|
import { useTranslations } from 'next-intl';
|
|
import { useAuthStore } from '@/lib/stores/auth-store';
|
|
```
|
|
|
|
**API fetch pattern** (lines 39-64) -- parallel fetch of all modules + active modules, building activation map:
|
|
```typescript
|
|
const fetchModules = useCallback(async () => {
|
|
try {
|
|
const [allRes, activeRes] = await Promise.all([
|
|
fetch(`${API_URL}/modules`, { credentials: 'include' }),
|
|
fetch(`${API_URL}/modules/active`, { credentials: 'include' }),
|
|
]);
|
|
|
|
if (allRes.ok) {
|
|
const allModules: Module[] = await allRes.json();
|
|
setModules(allModules);
|
|
}
|
|
|
|
if (activeRes.ok) {
|
|
const activeModules: (Module & { activations?: TenantActivation[] })[] = await activeRes.json();
|
|
const map = new Map<string, boolean>();
|
|
for (const mod of activeModules) {
|
|
map.set(mod.id, true);
|
|
}
|
|
setActivations(map);
|
|
}
|
|
} catch {
|
|
// silently fail
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
}, []);
|
|
```
|
|
|
|
**Toggle activation pattern** (lines 74-103):
|
|
```typescript
|
|
const toggleModule = async (moduleId: string, currentlyActive: boolean) => {
|
|
setToggling(moduleId);
|
|
setError(null);
|
|
try {
|
|
const action = currentlyActive ? 'deactivate' : 'activate';
|
|
const res = await fetch(`${API_URL}/modules/${moduleId}/${action}`, {
|
|
method: 'POST',
|
|
credentials: 'include',
|
|
});
|
|
|
|
if (res.ok) {
|
|
setActivations((prev) => {
|
|
const next = new Map(prev);
|
|
if (currentlyActive) {
|
|
next.delete(moduleId);
|
|
} else {
|
|
next.set(moduleId, true);
|
|
}
|
|
return next;
|
|
});
|
|
} else {
|
|
const body = await res.text().catch(() => '');
|
|
setError(`${res.status}: ${body}`);
|
|
}
|
|
} catch (err) {
|
|
setError(String(err));
|
|
} finally {
|
|
setToggling(null);
|
|
}
|
|
};
|
|
```
|
|
|
|
**Role-gated access pattern** (lines 37, 110-116):
|
|
```typescript
|
|
const isAdmin = currentUser?.role === 'ADMIN' || currentUser?.role === 'SUPER_ADMIN';
|
|
|
|
if (!isAdmin) {
|
|
return (
|
|
<div className="flex items-center justify-center min-h-[60vh]">
|
|
<p className="text-lg text-muted-foreground">{tCommon('accessDenied')}</p>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
**Error display pattern** (lines 126-129):
|
|
```typescript
|
|
{error && (
|
|
<div className="rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive">
|
|
{error}
|
|
</div>
|
|
)}
|
|
```
|
|
|
|
**Page layout pattern** (lines 118-124):
|
|
```typescript
|
|
<div className="space-y-6">
|
|
<div>
|
|
<h1 className="text-2xl font-bold text-foreground">{t('title')}</h1>
|
|
<p className="mt-1 text-sm text-muted-foreground">{t('description')}</p>
|
|
</div>
|
|
{/* content */}
|
|
</div>
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/app/(portal)/marketplace/[slug]/page.tsx` (detail page, request-response)
|
|
|
|
**Analog:** `apps/web/src/app/(portal)/modules/[category]/page.tsx`
|
|
|
|
**Dynamic params pattern** (lines 1-5):
|
|
```typescript
|
|
'use client';
|
|
|
|
import { useTranslations } from 'next-intl';
|
|
import { useParams } from 'next/navigation';
|
|
import { useEffect, useState } from 'react';
|
|
```
|
|
|
|
**Loading + empty state pattern** (lines 104-143):
|
|
```typescript
|
|
{isLoading && (
|
|
<div className="flex items-center justify-center py-12">
|
|
<div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
|
|
</div>
|
|
)}
|
|
|
|
{!isLoading && modules.length === 0 && (
|
|
<div className="flex flex-col items-center justify-center py-16 text-center">
|
|
<div className="rounded-lg bg-muted p-4 mb-4">
|
|
{/* SVG icon */}
|
|
</div>
|
|
<p className="text-lg text-muted-foreground">{t('noModules')}</p>
|
|
</div>
|
|
)}
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/app/(portal)/marketplace/components/MarketplaceCard.tsx` (component, CRUD)
|
|
|
|
**Analog:** `apps/web/src/app/(portal)/modules/[category]/components/ModuleCard.tsx`
|
|
|
|
**Card structure pattern** (lines 70-107):
|
|
```typescript
|
|
export function ModuleCard({ name, slug, description, icon, category }: ModuleCardProps) {
|
|
const t = useTranslations('modules');
|
|
const locale = (typeof window !== 'undefined' && document.documentElement.lang) || 'de';
|
|
const localizedDescription = description[locale] || description.en || description.de || '';
|
|
|
|
return (
|
|
<Link href={`/modules/${category}/${slug}`} className="group block">
|
|
<div className="rounded-lg border border-border bg-card p-5 shadow-sm transition-all hover:shadow-md hover:border-primary/30 group-focus-visible:ring-2 group-focus-visible:ring-ring group-focus-visible:ring-offset-2">
|
|
<div className="flex items-start gap-3 mb-3">
|
|
<div className="rounded-md bg-muted p-2.5 shrink-0">
|
|
<ModuleIcon icon={icon} />
|
|
</div>
|
|
<div className="min-w-0">
|
|
<h3 className="font-semibold text-base leading-tight truncate">{name}</h3>
|
|
</div>
|
|
</div>
|
|
<p className="text-sm text-muted-foreground line-clamp-2 mb-4">{localizedDescription}</p>
|
|
</div>
|
|
</Link>
|
|
);
|
|
}
|
|
```
|
|
|
|
**Locale extraction pattern** (line 72-73):
|
|
```typescript
|
|
const locale = (typeof window !== 'undefined' && document.documentElement.lang) || 'de';
|
|
const localizedDescription = description[locale] || description.en || description.de || '';
|
|
```
|
|
|
|
**Responsive grid pattern** (from category page, line 112):
|
|
```typescript
|
|
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/app/(portal)/marketplace/components/TenantContextSelector.tsx` (component, request-response)
|
|
|
|
**Analog:** `apps/web/src/app/(portal)/admin/tenants/page.tsx`
|
|
|
|
**Tenant fetch pattern** (lines 44-57):
|
|
```typescript
|
|
const fetchTenants = useCallback(async () => {
|
|
try {
|
|
const res = await fetch(`${API_URL}/tenants`, {
|
|
credentials: 'include',
|
|
});
|
|
if (res.ok) {
|
|
setTenants(await res.json());
|
|
}
|
|
} catch {
|
|
// silently fail
|
|
} finally {
|
|
setLoading(false);
|
|
}
|
|
}, []);
|
|
```
|
|
|
|
**Tenant interface** (lines 9-16):
|
|
```typescript
|
|
interface Tenant {
|
|
id: string;
|
|
name: string;
|
|
slug: string;
|
|
isActive: boolean;
|
|
createdAt: string;
|
|
userCount: number;
|
|
}
|
|
```
|
|
|
|
**Super-Admin guard pattern** (line 42):
|
|
```typescript
|
|
const hasAccess = currentUser?.role === 'SUPER_ADMIN';
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/app/(portal)/marketplace/components/ActivationDialog.tsx` (component, event-driven)
|
|
|
|
**Analog:** `apps/web/src/app/(portal)/admin/tenants/page.tsx` (delete confirm modal)
|
|
|
|
**Modal pattern** (lines 301-323):
|
|
```typescript
|
|
{deleteConfirm && (
|
|
<div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
|
|
<div className="w-full max-w-sm rounded-lg border border-border bg-card p-6 shadow-lg">
|
|
<p className="text-sm text-foreground mb-4">{t('deleteConfirm')}</p>
|
|
<div className="flex justify-end gap-3">
|
|
<button
|
|
onClick={() => setDeleteConfirm(null)}
|
|
className="rounded-md border border-border px-4 py-2 text-sm text-foreground hover:bg-muted transition-colors"
|
|
>
|
|
{tCommon('cancel')}
|
|
</button>
|
|
<button
|
|
onClick={() => handleDelete(deleteConfirm)}
|
|
className="rounded-md bg-destructive px-4 py-2 text-sm font-medium text-destructive-foreground hover:opacity-90 transition-opacity"
|
|
>
|
|
{tCommon('delete')}
|
|
</button>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
)}
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/lib/stores/marketplace-store.ts` (store, event-driven)
|
|
|
|
**Analog:** `apps/web/src/lib/stores/sidebar-store.ts`
|
|
|
|
**Zustand store pattern** (lines 1-21):
|
|
```typescript
|
|
import { create } from 'zustand';
|
|
import { persist } from 'zustand/middleware';
|
|
|
|
interface SidebarState {
|
|
isCollapsed: boolean;
|
|
isMobileOpen: boolean;
|
|
toggle: () => void;
|
|
setMobileOpen: (open: boolean) => void;
|
|
}
|
|
|
|
export const useSidebarStore = create<SidebarState>()(
|
|
persist(
|
|
(set) => ({
|
|
isCollapsed: false,
|
|
isMobileOpen: false,
|
|
toggle: () => set((state) => ({ isCollapsed: !state.isCollapsed })),
|
|
setMobileOpen: (open) => set({ isMobileOpen: open }),
|
|
}),
|
|
{ name: 'tessera-sidebar' }
|
|
)
|
|
);
|
|
```
|
|
|
|
**Non-persisted store pattern** (from auth-store, lines 22-26):
|
|
```typescript
|
|
export const useAuthStore = create<AuthState>()((set) => ({
|
|
user: null,
|
|
setUser: (user) => set({ user }),
|
|
clearUser: () => set({ user: null }),
|
|
}));
|
|
```
|
|
|
|
---
|
|
|
|
### `apps/web/src/components/layout/sidebar.tsx` (MODIFY -- add search, Link, usePathname)
|
|
|
|
**Self-analog.** Key modification points:
|
|
|
|
**Replace `<a>` with `<Link>`** -- current pattern (lines 54-56, 81-82, etc.):
|
|
```typescript
|
|
// CURRENT (replace all instances):
|
|
<a href="/" className="...">
|
|
// REPLACE WITH:
|
|
<Link href="/" className="...">
|
|
```
|
|
|
|
**Add usePathname for active state** -- insert after existing imports:
|
|
```typescript
|
|
import { usePathname } from 'next/navigation';
|
|
import Link from 'next/link';
|
|
|
|
// Inside component:
|
|
const pathname = usePathname();
|
|
const isActive = (href: string) => {
|
|
if (href === '/') return pathname === '/';
|
|
return pathname.startsWith(href);
|
|
};
|
|
```
|
|
|
|
**Sidebar link CSS classes** -- current active pattern (line 57):
|
|
```typescript
|
|
// Active: 'bg-sidebar-accent text-sidebar-accent-foreground font-medium'
|
|
// Inactive: 'text-sidebar-foreground hover:bg-muted'
|
|
```
|
|
|
|
**Categories accordion structure** (lines 106-176) -- extend with SidebarSearch component insertion point before the accordion.
|
|
|
|
**Module items in categories** (lines 156-165) -- already renders per-module links under each category. These `<a>` tags need `<Link>` replacement.
|
|
|
|
---
|
|
|
|
## Shared Patterns
|
|
|
|
### API Fetch Convention
|
|
**Source:** All page components
|
|
**Apply to:** All new page/component files that fetch data
|
|
```typescript
|
|
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001';
|
|
|
|
// Always use credentials: 'include' for cookie-based auth
|
|
fetch(`${API_URL}/endpoint`, { credentials: 'include' });
|
|
|
|
// For Super-Admin tenant context, add x-tenant-id header:
|
|
headers: selectedTenantId ? { 'x-tenant-id': selectedTenantId } : {}
|
|
```
|
|
|
|
### Translations Convention
|
|
**Source:** All components
|
|
**Apply to:** All new components
|
|
```typescript
|
|
import { useTranslations } from 'next-intl';
|
|
const t = useTranslations('marketplace'); // namespace key
|
|
const tCommon = useTranslations('common');
|
|
```
|
|
|
|
### CSS Token Convention
|
|
**Source:** All components
|
|
**Apply to:** All new components
|
|
```
|
|
// Semantic color tokens (NOT raw colors):
|
|
text-foreground, text-muted-foreground, bg-card, bg-muted, border-border,
|
|
bg-primary, text-primary-foreground, bg-destructive, text-destructive,
|
|
bg-sidebar, text-sidebar-foreground, bg-sidebar-accent, text-sidebar-accent-foreground
|
|
|
|
// Status colors (only exception to semantic tokens):
|
|
// Active: 'text-green-600 dark:text-green-400' or 'bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-400'
|
|
```
|
|
|
|
### Role Check Convention
|
|
**Source:** `auth-store.ts` + all admin pages
|
|
**Apply to:** TenantContextSelector, marketplace activation controls
|
|
```typescript
|
|
const currentUser = useAuthStore((s) => s.user);
|
|
const isAdmin = currentUser?.role === 'ADMIN' || currentUser?.role === 'SUPER_ADMIN';
|
|
const isSuperAdmin = currentUser?.role === 'SUPER_ADMIN';
|
|
```
|
|
|
|
## No Analog Found
|
|
|
|
| File | Role | Data Flow | Reason |
|
|
|------|------|-----------|--------|
|
|
| `MarketplaceSearch.tsx` | component | event-driven | No search input components exist yet. Use standard `<input>` with debounced `onChange` + project CSS conventions from form inputs in tenants page (line 259: `flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm`). |
|
|
| `CategoryFilter.tsx` | component | event-driven | No chip/filter-row components exist. Build as horizontal button row using badge styling from admin/modules (line 157-159: `rounded-full bg-muted px-2 py-0.5 text-xs text-muted-foreground`). |
|
|
| `StatusFilter.tsx` | component | event-driven | No tab-bar components exist. Build as segmented button row following same badge/button conventions. |
|
|
| `Toast.tsx` | component | event-driven | No toast system exists. Build with Zustand store pattern (see RESEARCH.md Pattern 4). |
|
|
| `sidebar-search.tsx` | component | event-driven | No sidebar search exists. Use input styling from tenants page form fields. |
|
|
|
|
## Metadata
|
|
|
|
**Analog search scope:** `apps/web/src/`
|
|
**Files scanned:** 30 source files (excluding node_modules, .next, dist)
|
|
**Pattern extraction date:** 2026-06-22
|