GMW/services/frontend/AGENTS.md

Bete Frontend — Project Overview

Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4, shadcn/ui, base-ui.

Key points:

• Server-side rendered (SSR) — output: "standalone" in next.config.ts; pages are React Server Components that fetch initial data from the backend at render-time, then hydrate interactive client components (no blank-spinner-first-load).
• Server data layer at src/lib/api/server.ts — server-only fetchers that call the backend directly via GMW_BACKEND_URL (default http://127.0.0.1:4001). Never import from a client component.
• API client at src/lib/api/client.ts — browser-side fetch for live ops, same-origin through the reverse proxy.
• WebSocket at src/lib/ws/ — auto-reconnecting client with typed event subscriptions. Realtime state (voice, media, messages) stays client-side.
• Shared realtime state is server-authoritative: the backend aggregates the gateway's voice_active_user deltas into a live speaker snapshot (GET /api/voice/status → activeSpeakers, plus WS voice_state sent on connect). Every browser converges on the same voice state; useSpeakers seeds from the server snapshot instead of accumulating per-tab.
• No authentication: all endpoints are public

Data flow (match these — do not invent endpoints)

Discord → discord-gateway → Redis pub/sub → backend (Express :4001) ←→ Next.js SSR
                                                ↑ REST /api/*        (server: GMW_BACKEND_URL
                                                └ WS /ws (events + PCM binary)  127.0.0.1:4001)
                                                      ↑ browser WS (same-origin /ws)

• Rendering: gmw-proxy nginx (:4009) proxies / → Next standalone server (:4017, node .next/standalone/server.js), and /api + /ws → backend :4001. Public host: imphnen.asepharyana.my.id (Caddy reverse proxy → :4009).
• SSR seed pattern: each page.tsx is a server component that fetches via src/lib/api/server.ts and passes typed data to a view.tsx client component; the hooks take initialData as SWR fallbackData.
• Local dev overrides: NEXT_PUBLIC_API_URL and NEXT_PUBLIC_WS_URL for the browser; GMW_BACKEND_URL for the server.
• Never hardcode a host in api/ws clients — same-origin/env or GMW_BACKEND_URL only.

Backend response shapes that bite

• GET /api/chat/history → { history: ChatbotHistoryRow[], total } where each row is { id, user_id, user_message, bot_response, context, created_at }. Map rows to display messages in chatbot-context.tsx.
• message_deleted WS payload → { id, deleted_at } (an object, not a string).
• voice_recording_uploaded WS payload has no duration_bytes (REST rows do).
• Dashboard endpoints: /api/dashboard/stats|users|channels (+ /:id details).
• Channel/guild names live inside message.metadata JSON (channel.channelName), not top-level.
• GET /api/voice/status now includes activeSpeakers (authoritative shared snapshot from src/modules/voice/live-speaker.ts on the backend).