GMW/docs/specs/2026-06-01-frontend-major-refactor-design.md

Frontend Major Refactor — Design Document

Date: 2026-06-01 Scope: /mnt/code/bete/frontend/ — React + Vite + Tailwind Stack: React 18, Vite, TailwindCSS, TanStack Query, lucide-react

Problem Statement

1. package.json hilang — project tidak bisa pnpm install
2. App.tsx 285 baris monolithic (audio, socket, state, layout semua satu file)
3. useMemo dipakai untuk side effect (LivePanel:47) — anti-pattern React
4. Shared ArrayBuffer bug saat kirim PCM ke WebSocket (App:166)
5. ws/client.ts duplikat socket logic dengan hooks/useDashboardSocket.ts
6. Async handler tanpa await (MessageCard:88)
7. UI terlihat "jelek" — flat dark theme tanpa depth/visual interest
8. Mobile UX buruk — tab bar di atas, tidak ada sidebar drawer

Section 1: Arsitektur — Feature-Sliced Directory

frontend/
├── index.html
├── package.json                    # [NEW] Lengkap dengan semua deps
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
├── tsconfig.json
└── src/
    ├── main.tsx                    # React entry + QueryClient
    ├── styles.css                  # Tailwind + design tokens
    ├── App.tsx                     # Thin shell (~60 baris)
    │
    ├── entities/                   # Domain types
    │   ├── message/types.ts
    │   ├── guild/types.ts
    │   ├── voice/types.ts
    │   ├── media/types.ts
    │   └── ui/types.ts
    │
    ├── shared/                     # Cross-cutting utilities
    │   ├── api/client.ts           # HTTP client + typed endpoints
    │   ├── ws/socket.ts            # WebSocket connection manager
    │   ├── ws/events.ts            # Typed event map + dispatcher
    │   ├── hooks/useAudioPlayback.ts
    │   ├── hooks/useAudioTransmit.ts
    │   ├── hooks/useLocalStorage.ts
    │   └── ui/                     # UI primitives
    │       ├── button.tsx
    │       ├── card.tsx
    │       ├── badge.tsx
    │       ├── input.tsx
    │       ├── select.tsx
    │       ├── tabs.tsx
    │       └── scroll-area.tsx
    │
    ├── features/                   # Feature-specific logic + presentation
    │   ├── live/
    │   │   ├── hooks/useVoiceControl.ts
    │   │   ├── hooks/useMediaControl.ts
    │   │   ├── index.tsx           # LivePanel
    │   │   ├── components/VoiceConnectionCard.tsx
    │   │   ├── components/AudioVisualizer.tsx
    │   │   ├── components/ActiveSpeakers.tsx
    │   │   ├── components/NowPlaying.tsx
    │   │   ├── components/MusicSubPanel.tsx
    │   │   ├── components/ScreenSubPanel.tsx
    │   │   └── components/RecordingsSubPanel.tsx
    │   ├── messages/
    │   │   ├── hooks/useMessages.ts
    │   │   ├── index.tsx           # MessagesPanel
    │   │   ├── components/MessageFeed.tsx
    │   │   ├── components/MessageCard.tsx
    │   │   └── components/ImageGrid.tsx
    │   ├── analytics/
    │   │   ├── hooks/useAnalytics.ts
    │   │   ├── index.tsx           # AnalyticsPanel
    │   │   └── components/         # (charts, tables kept as-is)
    │   └── auth/
    │       └── index.tsx           # AuthOverlay
    │
    └── widgets/                    # Composite layouts
        ├── DashboardLayout.tsx
        ├── Header.tsx
        └── Sidebar.tsx

Key Architectural Decisions

• App.tsx = hanya layout shell + providers. Semua hooks pindah ke features/.
• Socket = satu instance di shared/ws/socket.ts. Features subscribe via typed event bus.
• Entities = pure types, zero logic.
• Features = self-contained (hooks + components). Tidak cross-import antar feature.
• Widgets = layout compositions (sidebar, header, dashboard shell).

Section 2: Bug Fixes

#	Bug	Location	Fix
1	useMemo untuk async fetch (anti-pattern)	LivePanel.tsx:47	Ganti ke useEffect + useCallback
2	Shared ArrayBuffer dikirim ke WS	App.tsx:166	.slice() sebelum send
3	Missing useEffect deps	App.tsx:187	Add proper dependency arrays
4	Unstable keys (i sebagai fallback)	LivePanel.tsx:246	Gunakan s.userId ?? 'unknown-${i}'
5	Async handler tanpa await	MessageCard.tsx:88	onReanalyze → Promise<void>, di-await
6	monitorGuild recompute tiap render	App.tsx:65	Pakai useMemo
7	Socket localStorage tanpa validasi	useUIState.ts:9	Schema validation sebelum parse
8	Duplikat socket (ws/client.ts vs hooks/useDashboardSocket.ts)	Global	Hapus ws/client.ts, satu socket di shared/ws/socket.ts

Section 3: UI Redesign — Glass-morphism Modern

Color Tokens

--background: 222 47% 8%;       /* slightly darker */
--foreground: 210 40% 98%;
--card: 222 47% 12% / 0.7;       /* semi-transparent */
--card-border: 222 47% 25% / 0.4;/* translucent border */
--primary: 199 89% 52%;          /* brighter cyan-blue */
--accent: 217 33% 20%;
--muted: 217 33% 20%;
--radius: 0.85rem;

Visual Changes

• Background: Gradient mesh (dark → dark-purple → dark) dengan subtle noise overlay
• Cards: backdrop-blur-xl + semi-transparent bg + subtle glow border
• Sidebar: Expandable — icon-only (w-16) ↔ full (w-64) dengan smooth transition
• Mobile: Bottom tab bar (bukan top tabs), slide-in sidebar
• Typography: Inter tetap, heading scale lebih besar, weight lebih variatif
• Micro-interactions: transition-all duration-200, hover scale 1.01, focus rings
• Audio Visualizer: CSS animated bars (bukan static levels map)
• Message cards: Rounded-xl, subtle shadow, AI badge dengan color coding yang lebih jelas
• Charts: Recharts-based (existing), tapi dengan color scheme yang matching theme

Responsive Breakpoints

Breakpoint	Layout
< 768px	Bottom tab bar, no sidebar, full-width content
768px–1024px	Collapsed sidebar (icon-only), full content
> 1024px	Full sidebar (w-64), spaced content

Section 4: Error Handling

• Error Boundaries: Setiap feature punya error boundary (existing AnalyticsErrorBoundary pattern)
• API Errors: Global error toast via shared/ui/Toast component
• Socket Errors: Auto-reconnect dengan exponential backoff (existing pattern, diperbaiki)
• Loading States: Skeleton loaders (bukan text "Loading...") untuk semua data panels

Section 5: Data Flow

Browser → shared/ws/socket.ts → shared/ws/events.ts (dispatch)
                                    ↓
                        features/* subscribe via typed handlers
                                    ↓
                        features/*/hooks/ (React Query / useState)
                                    ↓
                        features/*/components (render)
                                    ↓
                        widgets/ (layout shell)

• REST API: React Query hooks di features/*/hooks/
• WebSocket Events: Event bus di shared/ws/events.ts, hooks subscribe ke events
• UI State: localStorage + shared/ws/socket.ts sync (existing pattern, dengan validasi)

Section 6: Testing Strategy

• Unit: Hooks testing dengan @testing-library/react — socket mocking
• Integration: Component render tests untuk panels
• E2E: Tidak termasuk scope initial refactor (future enhancement)

Section 7: Migration Plan

Phase 1: Foundation

1. package.json lengkap
2. tsconfig.json + vite.config.ts verified
3. shared/ structure + UI primitives
4. entities/ types extracted

Phase 2: Bug Fixes + Hooks Extraction

5. Extract hooks dari App.tsx → features/*/hooks/
6. Fix semua 8 bugs yang teridentifikasi
7. Single socket instance di shared/ws/socket.ts
8. App.tsx thin shell

Phase 3: UI Polish

9. Design tokens baru (glass-morphism)
10. Sidebar redesign (expandable + mobile drawer)
11. Audio visualizer animated
12. Message card redesign
13. Loading skeletons
14. Error boundaries + toast

Phase 4: Verification

15. pnpm run typecheck — zero errors
16. pnpm run lint — zero warnings
17. App runs + all 3 tabs functional
18. WebSocket connects + events work
19. Mobile responsive verified