mcpedia/.hermes/plans/frontend-redesign-spec.md

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.