228 lines
14 KiB
Markdown
228 lines
14 KiB
Markdown
 
|
# MCPedia Frontend Redesign — Spec
|
||
|
|
|
||
|
|
Status: DRAFT — minta approval sebelum coding
|
||
|
|
Date: 2026-09-08 WIB
|
||
|
|
Author: Hermes
|
||
|
|
|
||
|
|
## 1. Tujuan
|
||
|
|
|
||
|
|
Merombak `apps/web` agar:
|
||
|
|
- Satu sumber kebenaran: semua data berasal dari `@mcpedia/core` types & `@mcpedia/config` section presets; tidak ada shape duplikat di FE.
|
||
|
|
- Selaras dengan gateway/BE data flow: tRPC `apps/api` (`/trpc/*`) + REST `/api/*` + MCP `:4021` semua mengembalikan shape yang sama (DocumentMeta, SectionInfo, SearchHit, ExportData).
|
||
|
|
- Ganti pola fetch ad-hoc (`fetch("/api/...")` tersebar) dengan **SWR** terpusat — cache, revalidate, mutate, optimistic UI, error boundary konsisten.
|
||
|
|
- Hapus sisa TanStack (saat ini tidak ada deps TanStack — audit `apps/web/package.json` clean; tapi pola akan dibakukan supaya tidak masuk lagi).
|
||
|
|
- UI: Archival Precision tetap (monochrome, hairline, mono telemetry), tapi lebih live dan terisi data real (bukan placeholder).
|
||
|
|
|
||
|
|
## 2. Audit Status Quo
|
||
|
|
|
||
|
|
### FE sekarang
|
||
|
|
- Next.js 16.3.4, App Router, `force-dynamic` di semua page yang baca DB.
|
||
|
|
- RSC langsung import `@mcpedia/core` (`listDocuments`, `getDocument`, `listSections`, `getRelated`, `listRevisions`, `getExportDocuments`). SEO bagus, tapi client components (Sidebar, Header, Search, CommandMenu) fetch ulang via REST tanpa cache sharing.
|
||
|
|
- REST: `/api/search?q&mode&limit`, `/api/docs` (list), `/api/sections`, `/api/export?path&sort`, `/api/revisions/restore`, `/api/auth/login`.
|
||
|
|
- tRPC `apps/api` (Hono) expose: search/semanticSearch/hybridSearch, getDocument, listDocuments, sections, related, revisions, CRUD (gated `x-webhook-secret`), jobStatus, reindex hooks, `/health`, `/metrics`.
|
||
|
|
- MCP `:4021` Streamable HTTP `/mcp` expose 13 tools (tidak dipakai FE, tapi shape-nya sama).
|
||
|
|
- Tidak ada `swr` / `@tanstack/react-query` di `apps/web/package.json` — jadi migrasi = greenfield SWR layer, bukan replace.
|
||
|
|
- Design tokens sudah rapi di `globals.css` (CSS vars light/dark + `--brand`, `--bg-*`, `--text-*`, `--code-*`). Header/Sidebar/Markdown/TOC/DocActions sudah pakai tokens.
|
||
|
|
|
||
|
|
### Masalah yang diselesaikan redesign
|
||
|
|
1. Sidebar & Header fetch `/api/docs` + `/api/sections` tanpa deduplikasi — tiap navigasi fetch ulang, tidak ada stale-while-revalidate.
|
||
|
|
2. Search page client-side `fetch` manual tanpa debounce terpusat, tanpa cache antar-mode (hybrid/keyword/semantic saling overwrite).
|
||
|
|
3. Doc page RSC tidak live: setelah create/update/delete atau reindex, harus hard refresh. Tidak ada `mutate` cross-component.
|
||
|
|
4. Shape drift: Search `snippet` vs `SearchHit` vs `ChunkHit` tidak konsisten antara `/api/search` dan `@mcpedia/search` — perlu typed fetcher.
|
||
|
|
5. Tidak ada surface untuk queue/embeddings status (BE punya `jobStatus`, `queueStatus`, `INDEX_QUEUE` BullMQ) — FE buta terhadap indexing.
|
||
|
|
|
||
|
|
## 3. Arsitektur Target
|
||
|
|
|
||
|
|
```
|
||
|
|
apps/web/app/
|
||
|
|
lib/
|
||
|
|
fetcher.ts — typed fetcher (fetch JSON + error envelope)
|
||
|
|
swr.ts — SWRConfig global (dedupingInterval, focusThrottle, errorRetry)
|
||
|
|
api.ts — typed client untuk /api/* (listDocuments, search, sections, export, revisions)
|
||
|
|
hooks/
|
||
|
|
useSections.ts — SWR '/api/sections' -> SectionInfo[]
|
||
|
|
useDocuments.ts — SWR '/api/docs?section&status' -> DocumentMeta[]
|
||
|
|
useDocument.ts — SWR '/api/docs/:slug' (baru, GET single) -> Document
|
||
|
|
useSearch.ts — SWR key [q, mode, limit] -> SearchHit[] + debounced
|
||
|
|
useRelated.ts — SWR '/api/related?slug'
|
||
|
|
useRevisions.ts — SWR '/api/revisions?slug'
|
||
|
|
useQueueStatus.ts — SWR '/api/queue/status' poll 5s (opsional, admin only)
|
||
|
|
components/
|
||
|
|
(existing: Header, Sidebar, CommandMenu, Markdown, TOC, DocActions, ...)
|
||
|
|
SearchBar.tsx — reusable, dipakai Header + Search page + CommandMenu
|
||
|
|
SectionCard.tsx — extract dari page.tsx
|
||
|
|
DocumentCard.tsx — reusable card (recent, related, folder list)
|
||
|
|
TagCloud.tsx — baru: agregasi tags dari docs
|
||
|
|
QueueBadge.tsx — baru: show indexing status (waiting/active/failed)
|
||
|
|
EmptyState.tsx / ErrorState.tsx
|
||
|
|
app/
|
||
|
|
layout.tsx — tambah <SWRProvider> wrapper (client boundary)
|
||
|
|
page.tsx — refactor: RSC shell + client islands via SWR
|
||
|
|
[section]/page.tsx — sama
|
||
|
|
[section]/[...slug]/page.tsx — RSC hero + Markdown, client islands (related/revisions via SWR)
|
||
|
|
search/page.tsx — fully SWR, hapus useState fetch manual
|
||
|
|
create/page.tsx — mutate after create
|
||
|
|
dashboard/page.tsx — BARU (optional phase 2): queue, sections, recent, tag stats
|
||
|
|
```
|
||
|
|
|
||
|
|
### Prinsip SWR
|
||
|
|
- Satu `fetcher` generic: `fetcher<T>(url: string): Promise<T>` — throw on !ok dengan `info` + `status` untuk error boundary.
|
||
|
|
- `SWRConfig` di `layout.tsx` client wrapper: `dedupingInterval: 4000`, `focusThrottleInterval: 10000`, `shouldRetryOnError: false` untuk search, `refreshInterval` hanya untuk queue.
|
||
|
|
- Semua hooks pakai key array/string yang deterministic supaya `mutate` cross-page bisa: `mutate('/api/docs')`, `mutate('/api/sections')`.
|
||
|
|
- Debounce search di hook, bukan di component: `useDebouncedValue(q, 180ms)` internal ke `useSearch`.
|
||
|
|
- Optimistic mutate untuk create/update/delete: `mutate('/api/docs', optimisticList, false)` lalu revalidate.
|
||
|
|
|
||
|
|
## 4. Kontrak Data (FE ↔ BE)
|
||
|
|
|
||
|
|
Semua types import dari `@mcpedia/types` — tidak ada re-declare shape di FE.
|
||
|
|
|
||
|
|
| FE Hook | BE Source | Endpoint | Shape |
|
||
|
|
|---------|-----------|----------|-------|
|
||
|
|
| useSections | `listSections()` | `GET /api/sections` | `SectionInfo[]` |
|
||
|
|
| useDocuments | `listDocuments({section,status})` | `GET /api/docs?section=&status=` | `DocumentMeta[]` |
|
||
|
|
| useDocument | `getDocument(slug)` | `GET /api/docs/:slug` (baru) | `Document` |
|
||
|
|
| useSearch | `keywordSearch/hybridSearch/semanticSearch` | `GET /api/search?q&mode&limit` | `{results: {slug,title,section,score,snippet}[]}` |
|
||
|
|
| useRelated | `getRelated(slug)` | `GET /api/related?slug=` (baru, atau reuse via core) | `DocumentMeta[]` |
|
||
|
|
| useRevisions | `listRevisions(slug)` | `GET /api/revisions?slug=` (baru) | `Revision[]` |
|
||
|
|
| useQueueStatus | BullMQ `getQueue()` | `GET /api/queue/status` (baru, proxy ke apps/api /metrics atau queue) | `{waiting,active,completed,failed,delayed}` |
|
||
|
|
|
||
|
|
**Tambahan endpoint yang perlu dibuat (tipis, proxy ke core):**
|
||
|
|
- `GET /api/docs/[slug]` — single doc (hindari RSC-only fetch, enable SWR).
|
||
|
|
- `GET /api/related?slug=&limit=` — wrapper `getRelated`.
|
||
|
|
- `GET /api/revisions?slug=&limit=` — wrapper `listRevisions`.
|
||
|
|
- `GET /api/queue/status` — wrapper `getQueue().get*Count()` (admin-only atau public read-only).
|
||
|
|
- (Opsional) `GET /api/tags` — agregasi tags dari `listDocuments` untuk TagCloud.
|
||
|
|
|
||
|
|
Semua endpoint return envelope sama: `{data}` atau `{results}` + `{error}` on 500, dengan `Content-Type: application/json`. Auth untuk mutasi tetap `x-webhook-secret` atau cookie `mcpedia_admin`.
|
||
|
|
|
||
|
|
## 5. Perubahan Per-File (Rincian)
|
||
|
|
|
||
|
|
### Phase 0 — Foundation (wajib)
|
||
|
|
- `apps/web/package.json`: tambah `swr: ^2.3.x` (latest 2.x). Tidak tambah TanStack. `bun install` + cek `typecheck`.
|
||
|
|
- `apps/web/app/lib/fetcher.ts` (baru): `export const fetcher = <T>(url: string): Promise<T> => fetch(url).then(r => { if(!r.ok) throw ...; return r.json() })`
|
||
|
|
- `apps/web/app/lib/swr.tsx` (baru): `SWRProvider` client component wrapping `SWRConfig`.
|
||
|
|
- `apps/web/app/lib/api.ts` (baru): typed helpers `searchDocs(q,mode,limit)`, `listDocs()`, `listSections()` — dipakai hooks.
|
||
|
|
- `apps/web/app/layout.tsx`: bungkus children dengan `<SWRProvider>` (client boundary minimal).
|
||
|
|
|
||
|
|
### Phase 1 — Hooks + Refactor Existing Pages
|
||
|
|
- `hooks/useSections.ts`, `useDocuments.ts`, `useSearch.ts`: ganti `useEffect+fetch` di `Header.tsx`, `Sidebar.tsx`, `search/page.tsx`, `CommandMenu.tsx`, `page.tsx` (home).
|
||
|
|
- `Header.tsx`: `useSections()` alih-alih `useState+useEffect fetch /api/sections`.
|
||
|
|
- `Sidebar.tsx`: `useDocuments()` + `useSections()` + filter memo — hilangkan `useEffect fetch /api/docs`.
|
||
|
|
- `search/page.tsx`: `useSearch(q, mode)` — hapus `handleSearch` manual, pakai `isLoading`, `isValidating`, `error` dari SWR. Mode & section filter tetap local state, tapi key SWR mencakup keduanya.
|
||
|
|
- `CommandMenu.tsx`: `useSearch(query)` debounced — hapus timer manual.
|
||
|
|
- `app/page.tsx`: tetap RSC untuk SEO (listDocuments/listSections server), tapi `SectionTree` dan `Recently Updated` bisa jadi client islands yang pakai SWR untuk live update (opsional: keep RSC + `mutate` on focus).
|
||
|
|
- `[section]/page.tsx` & `[section]/[...slug]/page.tsx`: RSC hero + Markdown tetap, `related` & `revisions` pindah ke client islands `RelatedGrid` & `RevisionList` pakai `useRelated`/`useRevisions`.
|
||
|
|
|
||
|
|
### Phase 2 — Fitur Baru (detail)
|
||
|
|
1. **Dashboard `/dashboard` (baru, admin-aware):**
|
||
|
|
- Cards: total docs, sections, queue (waiting/active/failed), embedding provider status.
|
||
|
|
- Section breakdown bar (docCount per section).
|
||
|
|
- Tag cloud (top 20 tags dengan count).
|
||
|
|
- Recent activity (last 10 updated docs).
|
||
|
|
- Queue status poll 5s via `useQueueStatus` (hanya jika admin cookie ada, else hide).
|
||
|
|
2. **Tag Explorer `/tags` atau sidebar widget:**
|
||
|
|
- `GET /api/tags` agregasi, klik tag → `/search?tag=...` atau filter docs.
|
||
|
|
3. **Doc page enhancements:**
|
||
|
|
- `QueueBadge` di hero jika doc sedang di-index (query queue by slug).
|
||
|
|
- Optimistic revision restore: `mutate('/api/revisions?slug=...')` setelah POST restore.
|
||
|
|
- Related docs pakai SWR + `keepPreviousData`.
|
||
|
|
4. **Search enhancements:**
|
||
|
|
- Persist `mode` di URL (`?q=&mode=hybrid`) — sudah ada, pertahankan + SWR key sync.
|
||
|
|
- Highlight snippet `mark` sudah ada — pertahankan.
|
||
|
|
- Empty & error states pakai `EmptyState`/`ErrorState` components.
|
||
|
|
5. **Create/Edit:**
|
||
|
|
- Setelah `POST /api/docs`, `mutate('/api/docs')` + `mutate('/api/sections')` + `router.push('/${slug}')`.
|
||
|
|
- Custom fields (extraFields) tetap flat → `splitPayload` di BE tidak berubah.
|
||
|
|
6. **Export:**
|
||
|
|
- `PdfExportView` tetap, tapi tambah SWR preload `getExportDocuments` untuk preview count sebelum export.
|
||
|
|
|
||
|
|
### Phase 3 — Polish & Cleanup
|
||
|
|
- Hapus semua `fetch` ad-hoc yang tersisa — semua lewat hooks.
|
||
|
|
- Pastikan `globals.css` tokens dipakai konsisten (tidak ada hard-coded hex baru).
|
||
|
|
- `CommandMenu` jadi satu-satunya omnisearch entry — `Header` search icon di mobile buka CommandMenu, bukan link `/search`.
|
||
|
|
- A11y: `aria-live` untuk search results count, `role="status"` untuk queue badge.
|
||
|
|
- Print/PDF styles sudah ada — tidak diubah.
|
||
|
|
|
||
|
|
## 6. File yang Disentuh (Checklist)
|
||
|
|
|
||
|
|
Baru:
|
||
|
|
- `apps/web/app/lib/fetcher.ts`
|
||
|
|
- `apps/web/app/lib/swr.tsx`
|
||
|
|
- `apps/web/app/lib/api.ts`
|
||
|
|
- `apps/web/app/hooks/useSections.ts`
|
||
|
|
- `apps/web/app/hooks/useDocuments.ts`
|
||
|
|
- `apps/web/app/hooks/useSearch.ts`
|
||
|
|
- `apps/web/app/hooks/useRelated.ts`
|
||
|
|
- `apps/web/app/hooks/useRevisions.ts`
|
||
|
|
- `apps/web/app/hooks/useQueueStatus.ts`
|
||
|
|
- `apps/web/app/hooks/useTags.ts` (opsional)
|
||
|
|
- `apps/web/app/components/SearchBar.tsx`
|
||
|
|
- `apps/web/app/components/SectionCard.tsx`
|
||
|
|
- `apps/web/app/components/DocumentCard.tsx`
|
||
|
|
- `apps/web/app/components/TagCloud.tsx`
|
||
|
|
- `apps/web/app/components/QueueBadge.tsx`
|
||
|
|
- `apps/web/app/components/EmptyState.tsx`
|
||
|
|
- `apps/web/app/dashboard/page.tsx` (baru)
|
||
|
|
- `apps/web/app/api/docs/[slug]/route.ts` (baru)
|
||
|
|
- `apps/web/app/api/related/route.ts` (baru)
|
||
|
|
- `apps/web/app/api/revisions/route.ts` (baru GET)
|
||
|
|
- `apps/web/app/api/queue/status/route.ts` (baru)
|
||
|
|
- `apps/web/app/api/tags/route.ts` (baru, opsional)
|
||
|
|
|
||
|
|
Edit:
|
||
|
|
- `apps/web/package.json` (+ swr)
|
||
|
|
- `apps/web/app/layout.tsx` (+ SWRProvider)
|
||
|
|
- `apps/web/app/page.tsx` (extract SectionCard, optional SWR islands)
|
||
|
|
- `apps/web/app/[section]/page.tsx` (DocumentCard)
|
||
|
|
- `apps/web/app/[section]/[...slug]/page.tsx` (related/revisions islands)
|
||
|
|
- `apps/web/app/search/page.tsx` (full SWR)
|
||
|
|
- `apps/web/app/components/Header.tsx` (useSections)
|
||
|
|
- `apps/web/app/components/Sidebar.tsx` (useDocuments/useSections)
|
||
|
|
- `apps/web/app/components/CommandMenu.tsx` (useSearch)
|
||
|
|
- `apps/web/app/create/page.tsx` (mutate)
|
||
|
|
- `apps/web/app/components/DocForm.tsx` (mutate setelah submit)
|
||
|
|
|
||
|
|
Tidak disentuh:
|
||
|
|
- `packages/core`, `packages/types`, `packages/config`, `packages/db` (hanya dibaca)
|
||
|
|
- `apps/api`, `apps/mcp`, `apps/worker` (hanya diproxy)
|
||
|
|
- `globals.css`, `next.config.ts`, `tailwind` config (kecuali perlu token baru)
|
||
|
|
|
||
|
|
## 7. Urutan Implementasi
|
||
|
|
|
||
|
|
1. Phase 0 foundation → `bun install && bun run typecheck` green.
|
||
|
|
2. Phase 1 hooks + Header/Sidebar/Search/CommandMenu → manual test + `next build` smoke.
|
||
|
|
3. Phase 2 doc page islands + create mutate → test CRUD flow dengan `x-webhook-secret` / admin cookie.
|
||
|
|
4. Phase 2 dashboard + tags → behind `canEdit` guard jika perlu.
|
||
|
|
5. Phase 3 cleanup, hapus fetch manual, final `bun run lint && typecheck && build`.
|
||
|
|
|
||
|
|
## 8. Verifikasi
|
||
|
|
|
||
|
|
- `bun run typecheck` — tidak ada error (SWR types + @mcpedia/types).
|
||
|
|
- `bun run lint` — rules Next 16 ok.
|
||
|
|
- `bun --cwd apps/web run build` — semua route `force-dynamic` OK, tidak ada import-time DB throw.
|
||
|
|
- Manual:
|
||
|
|
- Sidebar filter + section count live setelah create doc.
|
||
|
|
- Search mode switch (hybrid/keyword/semantic) cache terpisah, tidak flicker.
|
||
|
|
- CommandMenu ⌘K debounce 180ms, Enter navigasi benar.
|
||
|
|
- Doc related & revisions muncul via SWR tanpa hard refresh.
|
||
|
|
- Queue badge (jika ada) poll 5s, tidak spam (dedupingInterval).
|
||
|
|
- Dark/light toggle tetap work (SWRProvider tidak break `ThemeToggle`).
|
||
|
|
- Staging: `curl /api/search?q=test&mode=hybrid`, `/api/sections`, `/api/docs` return shape konsisten dengan tRPC.
|
||
|
|
|
||
|
|
## 9. Risiko & Mitigasi
|
||
|
|
|
||
|
|
- RSC + SWR double fetch: mitigasi dengan `fallbackData` dari RSC props ke SWR hook di islands (opsi, tidak wajib v1).
|
||
|
|
- Peningkatan request ke DB: SWR deduping 4s + `revalidateOnFocus: false` untuk search, `true` untuk sections/docs.
|
||
|
|
- Auth untuk `/api/queue/status`: jadikan public read-only (hanya counts, bukan detail job) — aman.
|
||
|
|
|
||
|
|
## 10. Keputusan yang Perlu Kamu Konfirmasi
|
||
|
|
|
||
|
|
1. **Dashboard `/dashboard` perlu tidak?** Atau cukup queue badge di existing pages? Rekomendasi: bikin, tapi Phase 2 — bisa ditunda.
|
||
|
|
2. **Endpoint baru (`/api/docs/[slug]`, `/api/related`, `/api/revisions` GET, `/api/queue/status`, `/api/tags`) setuju?** Alternatif: FE langsung pakai tRPC client (`@trpc/client`) — tapi spec ini pilih REST `/api/*` supaya Next cache & SWR fetcher simpel.
|
||
|
|
3. **SWR vs tRPC+SWR?** Spec ini pakai SWR+REST (paling simpel, tidak tambah `@trpc/client` di FE). Jika mau tRPC, tambah `createTRPCClient` + `httpBatchLink` — tradeoff: lebih typed tapi lebih berat. Default: SWR+REST.
|
||
|
|
4. **Keep RSC server fetch untuk SEO atau full client SWR?** Rekomendasi: keep RSC untuk initial HTML (SEO), SWR untuk live revalidation di client islands — hybrid, bukan full SWR.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
Jawab: `Lanjut Phase 0+1` untuk eksekusi, atau beri koreksi poin 10.
|