feat: add app header, sidebar, and mobile navigation components

- Implemented AppHeader component with theme toggle and connection status.
- Created AppSidebar component for navigation with connection status indicator.
- Added MobileNav component for mobile navigation with responsive design.
- Introduced shared components: DetailStat, EmptyState, ErrorState, LoadingSkeleton, and StatCard for consistent UI.
- Developed hooks for async data fetching: useAsync, useConfig, useDashboard, useGuilds, useMedia, useMessages, useRecordings, and useVoice.
- Added chatbot API functions for sending messages and managing chat history.

services/discord-gateway/src/modules/voice-recording/transmitter.ts

@@ -28,9 +28,6 @@ export class VoiceTransmitter {
   /** Set true before sending SIGTERM so exit handler knows it's intentional */
   private _expectedExit = false;
 
-  /** True while backpressure drain is in progress */
-  private draining = false;
-
   /**
    * Start listening for PCM audio data from Redis and stream to Discord
    */

services/frontend/src/app/(dashboard)/analysis/page.tsx

@@ -2,55 +2,44 @@
 
 import { Loader2, RefreshCw, Search, Sparkles } from "lucide-react";
 import { useCallback, useState } from "react";
-
+import { EmptyState, LoadingSkeleton } from "@/components/shared";
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Progress } from "@/components/ui/progress";
-import { Skeleton } from "@/components/ui/skeleton";
-import { messagesApi } from "@/lib/api";
+import { useSearch } from "@/hooks";
 import { safeParseJsonArray } from "@/lib/format";
 import type { MessageRecord } from "@/lib/types";
 import { cn } from "@/lib/utils";
 
 export default function AnalysisPage() {
+  const { results, searching, search } = useSearch();
   const [query, setQuery] = useState("");
-  const [results, setResults] = useState<MessageRecord[] | null>(null);
-  const [searching, setSearching] = useState(false);
   const [searched, setSearched] = useState(false);
 
-  const handleSearch = useCallback(async () => {
+  const handleSearch = useCallback(() => {
     if (!query.trim()) return;
-    setSearching(true);
     setSearched(true);
-    try {
-      const result = await messagesApi.search(query, 50);
-      setResults(result.results);
-    } catch {
-      setResults([]);
-    } finally {
-      setSearching(false);
-    }
-  }, [query]);
+    search(query);
+  }, [query, search]);
 
   const handleReanalyze = useCallback(async (id: string) => {
+    const { messagesApi } = await import("@/lib/api");
     try {
       await messagesApi.reanalyze(id);
     } catch {
-      // ignore
+      /* ignore */
     }
   }, []);
 
   return (
     <div className="space-y-5 animate-fade-in-up">
-      {/* Search */}
       <div className="flex gap-2">
         <div className="relative flex-1">
           <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
           <Input
-            type="text"
             placeholder="Search message content, AI flags, analysis text…"
             value={query}
             onChange={(e) => setQuery(e.target.value)}
@@ -64,112 +53,27 @@ export default function AnalysisPage() {
         </Button>
       </div>
 
-      {/* Results */}
       {searching ? (
-        <div className="space-y-3">
-          {Array.from({ length: 5 }, (_, i) => (
-            <Skeleton key={i} className="h-28 rounded-xl" />
-          ))}
-        </div>
+        <LoadingSkeleton count={5} height="h-28" />
       ) : results !== null ? (
         <>
           <p className="text-sm text-muted-foreground">
-            Found {results.length} result
-            {results.length !== 1 ? "s" : ""}
+            Found {results.length} result{results.length !== 1 ? "s" : ""}
           </p>
 
           {results.length === 0 ? (
-            <div className="flex flex-col items-center justify-center py-20 text-center">
-              <Search className="size-10 text-muted-foreground/40 mb-3" />
-              <p className="text-sm text-muted-foreground">
-                No messages found matching your query.
-              </p>
-            </div>
+            <EmptyState
+              icon={Search}
+              title="No messages found matching your query."
+            />
           ) : (
             <div className="space-y-2">
               {results.map((msg) => (
-                <Card key={msg.id}>
-                  <CardContent className="p-4">
-                    <div className="flex items-start gap-3">
-                      <Avatar className="size-8 shrink-0 mt-0.5">
-                        <AvatarImage src={msg.avatar_url ?? undefined} />
-                        <AvatarFallback className="text-xs">
-                          {msg.username.charAt(0).toUpperCase()}
-                        </AvatarFallback>
-                      </Avatar>
-
-                      <div className="flex-1 min-w-0 space-y-2">
-                        <div className="flex items-center gap-2 flex-wrap">
-                          <span className="text-sm font-medium">
-                            {msg.username}
-                          </span>
-                          <span className="text-xs text-muted-foreground">
-                            {new Date(msg.created_at).toLocaleString()}
-                          </span>
-                          {msg.ai_status && (
-                            <Badge
-                              variant="outline"
-                              className={cn(
-                                "text-[10px] px-1.5 py-0 h-4",
-                                msg.ai_status === "clean" && "text-green-500",
-                                msg.ai_status === "flagged" && "text-red-500",
-                              )}
-                            >
-                              {msg.ai_status}
-                            </Badge>
-                          )}
-                        </div>
-
-                        <p className="text-sm leading-relaxed">{msg.content}</p>
-
-                        {msg.ai_moderation_flags &&
-                          msg.ai_moderation_flags !== "[]" && (
-                            <div className="flex flex-wrap gap-1">
-                              {safeParseJsonArray(msg.ai_moderation_flags).map(
-                                (flag) => (
-                                  <Badge
-                                    key={flag}
-                                    variant="destructive"
-                                    className="text-[10px] px-1.5 py-0 h-4"
-                                  >
-                                    {flag}
-                                  </Badge>
-                                ),
-                              )}
-                            </div>
-                          )}
-
-                        {msg.ai_analysis && (
-                          <p className="text-xs text-muted-foreground italic line-clamp-2 leading-relaxed">
-                            <Sparkles className="size-3 inline mr-1" />
-                            {msg.ai_analysis}
-                          </p>
-                        )}
-
-                        {msg.ai_confidence != null && (
-                          <div className="flex items-center gap-2 max-w-40">
-                            <Progress
-                              value={msg.ai_confidence * 100}
-                              className="h-1.5"
-                            />
-                            <span className="text-[11px] text-muted-foreground tabular-nums shrink-0">
-                              {(msg.ai_confidence * 100).toFixed(0)}%
-                            </span>
-                          </div>
-                        )}
-
-                        <Button
-                          variant="ghost"
-                          size="xs"
-                          onClick={() => handleReanalyze(msg.id)}
-                        >
-                          <RefreshCw className="size-3 mr-1" />
-                          Reanalyze
-                        </Button>
-                      </div>
-                    </div>
-                  </CardContent>
-                </Card>
+                <SearchResultCard
+                  key={msg.id}
+                  message={msg}
+                  onReanalyze={handleReanalyze}
+                />
               ))}
             </div>
           )}
@@ -188,3 +92,88 @@ export default function AnalysisPage() {
     </div>
   );
 }
+
+function SearchResultCard({
+  message: msg,
+  onReanalyze,
+}: {
+  message: MessageRecord;
+  onReanalyze: (id: string) => void;
+}) {
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <div className="flex items-start gap-3">
+          <Avatar className="size-8 shrink-0 mt-0.5">
+            <AvatarImage src={msg.avatar_url ?? undefined} />
+            <AvatarFallback className="text-xs">
+              {msg.username.charAt(0).toUpperCase()}
+            </AvatarFallback>
+          </Avatar>
+
+          <div className="flex-1 min-w-0 space-y-2">
+            <div className="flex items-center gap-2 flex-wrap">
+              <span className="text-sm font-medium">{msg.username}</span>
+              <span className="text-xs text-muted-foreground">
+                {new Date(msg.created_at).toLocaleString()}
+              </span>
+              {msg.ai_status && (
+                <Badge
+                  variant="outline"
+                  className={cn(
+                    "text-[10px] px-1.5 py-0 h-4",
+                    msg.ai_status === "clean" && "text-green-500",
+                    msg.ai_status === "flagged" && "text-red-500",
+                  )}
+                >
+                  {msg.ai_status}
+                </Badge>
+              )}
+            </div>
+
+            <p className="text-sm leading-relaxed">{msg.content}</p>
+
+            {msg.ai_moderation_flags && msg.ai_moderation_flags !== "[]" && (
+              <div className="flex flex-wrap gap-1">
+                {safeParseJsonArray(msg.ai_moderation_flags).map((flag) => (
+                  <Badge
+                    key={flag}
+                    variant="destructive"
+                    className="text-[10px] px-1.5 py-0 h-4"
+                  >
+                    {flag}
+                  </Badge>
+                ))}
+              </div>
+            )}
+
+            {msg.ai_analysis && (
+              <p className="text-xs text-muted-foreground italic line-clamp-2 leading-relaxed">
+                <Sparkles className="size-3 inline mr-1" />
+                {msg.ai_analysis}
+              </p>
+            )}
+
+            {msg.ai_confidence != null && (
+              <div className="flex items-center gap-2 max-w-40">
+                <Progress value={msg.ai_confidence * 100} className="h-1.5" />
+                <span className="text-[11px] text-muted-foreground tabular-nums shrink-0">
+                  {(msg.ai_confidence * 100).toFixed(0)}%
+                </span>
+              </div>
+            )}
+
+            <Button
+              variant="ghost"
+              size="xs"
+              onClick={() => onReanalyze(msg.id)}
+            >
+              <RefreshCw className="size-3 mr-1" />
+              Reanalyze
+            </Button>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

services/frontend/src/app/(dashboard)/dashboard/page.tsx

@@ -7,33 +7,30 @@ import {
   ChevronRight,
   Clock,
   Hash,
-  RefreshCw,
   Search,
   Shield,
   Sparkles,
   Users,
 } from "lucide-react";
 import Image from "next/image";
-import { useCallback, useEffect, useState } from "react";
+import { useEffect, useState } from "react";
+import {
+  DetailStat,
+  EmptyState,
+  ErrorState,
+  LoadingSkeleton,
+  StatCard,
+} from "@/components/shared";
 import { GuildSelector } from "@/components/shared/guild-selector";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Progress } from "@/components/ui/progress";
-import { Skeleton } from "@/components/ui/skeleton";
 import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
-import { dashboardApi } from "@/lib/api";
+import { useChannels, useStats, useUsers } from "@/hooks";
 import { formatNumber } from "@/lib/format";
-import type {
-  DashboardChannel,
-  DashboardChannelDetail,
-  DashboardStats,
-  DashboardUser,
-  DashboardUserDetail,
-} from "@/lib/types";
-import { cn } from "@/lib/utils";
-import { useWebSocket } from "@/lib/ws/context";
+import type { DashboardChannelDetail, DashboardUserDetail } from "@/lib/types";
 
 type View = "stats" | "users" | "channels" | "user-detail" | "channel-detail";
 
@@ -46,60 +43,6 @@ export default function DashboardPage() {
   const [activeChannel, setActiveChannel] =
     useState<DashboardChannelDetail | null>(null);
 
-  // WS connection for real-time awareness
-  useWebSocket();
-
-  const renderView = () => {
-    switch (view) {
-      case "stats":
-        return <StatsView />;
-      case "users":
-        return (
-          <UsersView
-            onSelectUser={async (userId) => {
-              try {
-                const detail = await dashboardApi.getUserDetail(userId);
-                setActiveUser(detail);
-                setView("user-detail");
-              } catch {
-                // ignore
-              }
-            }}
-          />
-        );
-      case "channels":
-        return (
-          <ChannelsView
-            guildId={guildId}
-            onSelectChannel={async (channelId) => {
-              try {
-                const detail = await dashboardApi.getChannelDetail(channelId);
-                setActiveChannel(detail);
-                setView("channel-detail");
-              } catch {
-                // ignore
-              }
-            }}
-          />
-        );
-      case "user-detail":
-        return activeUser ? (
-          <UserDetailView user={activeUser} onBack={() => setView("users")} />
-        ) : (
-          <UsersView onSelectUser={() => {}} />
-        );
-      case "channel-detail":
-        return activeChannel ? (
-          <ChannelDetailView
-            channel={activeChannel}
-            onBack={() => setView("channels")}
-          />
-        ) : (
-          <ChannelsView guildId={guildId} onSelectChannel={() => {}} />
-        );
-    }
-  };
-
   return (
     <div className="space-y-5">
       <GuildSelector value={guildId} onChange={setGuildId} />
@@ -130,260 +73,221 @@ export default function DashboardPage() {
         </TabsList>
       </Tabs>
 
-      {renderView()}
+      {view === "stats" && <StatsSection />}
+      {view === "users" && (
+        <UsersSection
+          onSelect={async (userId) => {
+            try {
+              const { dashboardApi } = await import("@/lib/api");
+              const detail = await dashboardApi.getUserDetail(userId);
+              setActiveUser(detail);
+              setView("user-detail");
+            } catch {
+              /* ignore */
+            }
+          }}
+        />
+      )}
+      {view === "channels" && (
+        <ChannelsSection
+          guildId={guildId}
+          onSelect={async (chId) => {
+            try {
+              const { dashboardApi } = await import("@/lib/api");
+              const detail = await dashboardApi.getChannelDetail(chId);
+              setActiveChannel(detail);
+              setView("channel-detail");
+            } catch {
+              /* ignore */
+            }
+          }}
+        />
+      )}
+      {view === "user-detail" && activeUser && (
+        <UserDetailView user={activeUser} onBack={() => setView("users")} />
+      )}
+      {view === "channel-detail" && activeChannel && (
+        <ChannelDetailView
+          channel={activeChannel}
+          onBack={() => setView("channels")}
+        />
+      )}
     </div>
   );
 }
 
-// ── Stats View ──────────────────────────────────
+// ── Stats Section ───────────────────────────────
 
-function StatsView() {
-  const [stats, setStats] = useState<DashboardStats | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+function StatsSection() {
+  const { stats, loading, error, refetch } = useStats();
 
-  const fetchStats = useCallback(async () => {
-    setLoading(true);
-    setError(null);
-    try {
-      const data = await dashboardApi.getStats();
-      setStats(data);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to load stats");
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+  if (error) return <ErrorState message={error} onRetry={refetch} />;
 
-  useEffect(() => {
-    fetchStats();
-  }, [fetchStats]);
-
-  if (error) {
+  if (loading || !stats) {
     return (
-      <div className="flex flex-col items-center justify-center py-20 text-center">
-        <AlertCircle className="size-10 text-destructive mb-3" />
-        <p className="text-sm text-muted-foreground mb-4 max-w-sm">{error}</p>
-        <Button variant="outline" onClick={fetchStats}>
-          <RefreshCw className="size-4 mr-2" />
-          Retry
-        </Button>
+      <div className="space-y-5 animate-fade-in-up">
+        <LoadingSkeleton count={8} height="h-28" columns={4} />
       </div>
     );
   }
 
   return (
     <div className="space-y-5 animate-fade-in-up">
-      {loading ? (
-        <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
-          {Array.from({ length: 8 }, (_, i) => (
-            <Skeleton key={i} className="h-28 rounded-xl" />
-          ))}
-        </div>
-      ) : stats ? (
-        <>
-          <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
-            <StatCard
-              label="Total Messages"
-              value={stats.total_messages}
-              icon={Hash}
-            />
-            <StatCard label="Today" value={stats.today_messages} icon={Clock} />
-            <StatCard label="Users" value={stats.total_users} icon={Users} />
-            <StatCard
-              label="Active 24h"
-              value={stats.active_users_24h}
-              icon={Sparkles}
-            />
-            <StatCard
-              label="Flagged"
-              value={stats.total_flagged}
-              variant="danger"
-              icon={AlertCircle}
-            />
-            <StatCard
-              label="Clean"
-              value={stats.total_clean}
-              variant="success"
-              icon={Shield}
-            />
-            <StatCard
-              label="Voice Recordings"
-              value={stats.total_voice_recordings}
-              icon={Hash}
-            />
-            <StatCard
-              label="AI Profiles"
-              value={stats.total_profiles}
-              icon={Sparkles}
-            />
-          </div>
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+        <StatCard
+          label="Total Messages"
+          value={stats.total_messages}
+          icon={Hash}
+        />
+        <StatCard label="Today" value={stats.today_messages} icon={Clock} />
+        <StatCard label="Users" value={stats.total_users} icon={Users} />
+        <StatCard
+          label="Active 24h"
+          value={stats.active_users_24h}
+          icon={Sparkles}
+        />
+        <StatCard
+          label="Flagged"
+          value={stats.total_flagged}
+          icon={AlertCircle}
+          variant="danger"
+        />
+        <StatCard
+          label="Clean"
+          value={stats.total_clean}
+          icon={Shield}
+          variant="success"
+        />
+        <StatCard
+          label="Voice Recordings"
+          value={stats.total_voice_recordings}
+          icon={Hash}
+        />
+        <StatCard
+          label="AI Profiles"
+          value={stats.total_profiles}
+          icon={Sparkles}
+        />
+      </div>
 
-          <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-            <Card>
-              <CardHeader>
-                <CardTitle className="flex items-center gap-2 text-sm font-semibold">
-                  <Hash className="size-4 text-muted-foreground" />
-                  Top Channels
-                </CardTitle>
-              </CardHeader>
-              <CardContent>
-                {stats.top_channels.length === 0 ? (
-                  <p className="text-sm text-muted-foreground py-6 text-center">
-                    No channel data yet.
-                  </p>
-                ) : (
-                  <div className="space-y-2">
-                    {stats.top_channels.map((ch, _i) => {
-                      const maxCount = stats.top_channels[0].message_count;
-                      const pct =
-                        maxCount > 0 ? (ch.message_count / maxCount) * 100 : 0;
-                      return (
-                        <div key={ch.channel_id} className="space-y-1">
-                          <div className="flex items-center justify-between text-sm">
-                            <span className="truncate font-medium">
-                              #{ch.channel_name ?? ch.channel_id.slice(0, 8)}
-                            </span>
-                            <span className="text-muted-foreground tabular-nums">
-                              {formatNumber(ch.message_count)}
-                            </span>
-                          </div>
-                          <Progress value={pct} className="h-1.5" />
-                        </div>
-                      );
-                    })}
-                  </div>
-                )}
-              </CardContent>
-            </Card>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2 text-sm font-semibold">
+              <Hash className="size-4 text-muted-foreground" />
+              Top Channels
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            {stats.top_channels.length === 0 ? (
+              <p className="text-sm text-muted-foreground py-6 text-center">
+                No channel data yet.
+              </p>
+            ) : (
+              <div className="space-y-2">
+                {stats.top_channels.map((ch) => {
+                  const max = stats.top_channels[0].message_count;
+                  const pct = max > 0 ? (ch.message_count / max) * 100 : 0;
+                  return (
+                    <div key={ch.channel_id} className="space-y-1">
+                      <div className="flex items-center justify-between text-sm">
+                        <span className="truncate font-medium">
+                          #{ch.channel_name ?? ch.channel_id.slice(0, 8)}
+                        </span>
+                        <span className="text-muted-foreground tabular-nums">
+                          {formatNumber(ch.message_count)}
+                        </span>
+                      </div>
+                      <Progress value={pct} className="h-1.5" />
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </CardContent>
+        </Card>
 
-            <Card>
-              <CardHeader>
-                <CardTitle className="flex items-center gap-2 text-sm font-semibold">
-                  <Shield className="size-4 text-muted-foreground" />
-                  Moderation Queue
-                </CardTitle>
-              </CardHeader>
-              <CardContent>
-                <div className="grid grid-cols-3 gap-3">
-                  <div className="rounded-lg bg-muted/50 p-3 text-center space-y-1.5">
-                    <div className="text-2xl font-bold tabular-nums">
-                      {stats.moderation_overview.pending}
-                    </div>
-                    <div className="text-xs text-muted-foreground">Pending</div>
-                  </div>
-                  <div className="rounded-lg bg-yellow-500/10 p-3 text-center space-y-1.5">
-                    <div className="text-2xl font-bold tabular-nums text-yellow-500">
-                      {stats.moderation_overview.processing}
-                    </div>
-                    <div className="text-xs text-muted-foreground">
-                      Processing
-                    </div>
-                  </div>
-                  <div className="rounded-lg bg-destructive/10 p-3 text-center space-y-1.5">
-                    <div className="text-2xl font-bold tabular-nums text-destructive">
-                      {stats.moderation_overview.error}
-                    </div>
-                    <div className="text-xs text-muted-foreground">Errors</div>
-                  </div>
-                </div>
-              </CardContent>
-            </Card>
-          </div>
-        </>
-      ) : null}
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2 text-sm font-semibold">
+              <Shield className="size-4 text-muted-foreground" />
+              Moderation Queue
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="grid grid-cols-3 gap-3">
+              <QueueStat
+                label="Pending"
+                value={stats.moderation_overview.pending}
+              />
+              <QueueStat
+                label="Processing"
+                value={stats.moderation_overview.processing}
+                variant="warning"
+              />
+              <QueueStat
+                label="Errors"
+                value={stats.moderation_overview.error}
+                variant="danger"
+              />
+            </div>
+          </CardContent>
+        </Card>
+      </div>
     </div>
   );
 }
 
-function StatCard({
+function QueueStat({
   label,
   value,
   variant,
-  icon: Icon,
 }: {
   label: string;
   value: number;
-  variant?: "default" | "danger" | "success";
-  icon: React.ComponentType<{ className?: string }>;
+  variant?: "default" | "warning" | "danger";
 }) {
   return (
-    <Card>
-      <CardContent className="p-4">
-        <div className="flex items-start justify-between">
-          <div className="space-y-1.5">
-            <p className="text-xs text-muted-foreground">{label}</p>
-            <p
-              className={cn(
-                "text-2xl font-bold tabular-nums tracking-tight",
-                variant === "danger" && "text-destructive",
-                variant === "success" && "text-green-500",
-              )}
-            >
-              {formatNumber(value)}
-            </p>
-          </div>
-          <div
-            className={cn(
-              "flex size-9 shrink-0 items-center justify-center rounded-lg",
-              variant === "danger"
-                ? "bg-destructive/10 text-destructive"
-                : variant === "success"
-                  ? "bg-green-500/10 text-green-500"
-                  : "bg-primary/10 text-primary",
-            )}
-          >
-            <Icon className="size-4" />
-          </div>
-        </div>
-      </CardContent>
-    </Card>
+    <div
+      className={`rounded-lg p-3 text-center space-y-1.5 ${
+        variant === "danger"
+          ? "bg-destructive/10"
+          : variant === "warning"
+            ? "bg-yellow-500/10"
+            : "bg-muted/50"
+      }`}
+    >
+      <div
+        className={`text-2xl font-bold tabular-nums ${
+          variant === "danger"
+            ? "text-destructive"
+            : variant === "warning"
+              ? "text-yellow-500"
+              : ""
+        }`}
+      >
+        {value}
+      </div>
+      <div className="text-xs text-muted-foreground">{label}</div>
+    </div>
   );
 }
 
-// ── Users View ──────────────────────────────────
+// ── Users Section ───────────────────────────────
 
-function UsersView({
-  onSelectUser,
-}: {
-  onSelectUser: (userId: string) => void;
-}) {
-  const [users, setUsers] = useState<DashboardUser[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [_cursor, setCursor] = useState<string | null>(null);
-  const [search, setSearch] = useState("");
-
-  const fetchUsers = useCallback(async (searchQuery?: string) => {
-    setLoading(true);
-    try {
-      const result = await dashboardApi.listUsers(20, undefined, searchQuery);
-      setUsers(result.data);
-      setCursor(result.nextCursor);
-    } catch {
-      // ignore
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+function UsersSection({ onSelect }: { onSelect: (id: string) => void }) {
+  const { users, loading, search, setSearch, refetch } = useUsers();
 
   useEffect(() => {
-    fetchUsers();
-  }, [fetchUsers]);
-
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      if (search) fetchUsers(search);
-      else fetchUsers();
-    }, 300);
+    const timer = setTimeout(refetch, 300);
     return () => clearTimeout(timer);
-  }, [search, fetchUsers]);
+  }, [refetch]);
 
   return (
     <div className="space-y-4 animate-fade-in-up">
       <div className="relative">
         <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
         <Input
-          type="text"
           placeholder="Search users…"
           value={search}
           onChange={(e) => setSearch(e.target.value)}
@@ -392,118 +296,81 @@ function UsersView({
       </div>
 
       {loading ? (
-        <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
-          {Array.from({ length: 6 }, (_, i) => (
-            <Skeleton key={i} className="h-20 rounded-xl" />
-          ))}
-        </div>
+        <LoadingSkeleton count={6} height="h-20" columns={2} />
+      ) : users.length === 0 ? (
+        <EmptyState icon={Users} title="No users found." />
       ) : (
         <div className="grid grid-cols-1 md:grid-cols-2 gap-3">
-          {users.length === 0 ? (
-            <div className="col-span-full flex flex-col items-center justify-center py-16 text-center">
-              <Users className="size-10 text-muted-foreground/40 mb-3" />
-              <p className="text-sm text-muted-foreground">No users found.</p>
-            </div>
-          ) : (
-            users.map((user) => (
-              <Card
-                key={user.user_id}
-                className="cursor-pointer hover:bg-accent/5 transition-colors"
-                onClick={() => onSelectUser(user.user_id)}
-              >
-                <CardContent className="p-3">
-                  <div className="flex items-center gap-3">
-                    <div className="size-10 shrink-0 rounded-full bg-muted flex items-center justify-center text-sm font-medium overflow-hidden ring-1 ring-border">
-                      {user.avatar_url ? (
-                        <Image
-                          src={user.avatar_url}
-                          alt=""
-                          width={40}
-                          height={40}
-                          className="size-full object-cover"
-                        />
-                      ) : (
-                        (user.username ?? "?").charAt(0).toUpperCase()
-                      )}
-                    </div>
-                    <div className="flex-1 min-w-0">
-                      <p className="text-sm font-medium truncate">
-                        {user.username ?? "Unknown"}
-                      </p>
-                      <p className="text-xs text-muted-foreground flex items-center gap-2">
-                        <span>{user.total_messages} messages</span>
-                        {user.flagged_count > 0 && (
-                          <Badge
-                            variant="destructive"
-                            className="text-[10px] px-1.5 py-0 h-4"
-                          >
-                            {user.flagged_count} flagged
-                          </Badge>
-                        )}
-                      </p>
-                    </div>
-                    <ChevronRight className="size-4 text-muted-foreground shrink-0" />
+          {users.map((user) => (
+            <Card
+              key={user.user_id}
+              className="cursor-pointer hover:bg-accent/5 transition-colors"
+              onClick={() => onSelect(user.user_id)}
+            >
+              <CardContent className="p-3">
+                <div className="flex items-center gap-3">
+                  <div className="size-10 shrink-0 rounded-full bg-muted flex items-center justify-center text-sm font-medium overflow-hidden ring-1 ring-border">
+                    {user.avatar_url ? (
+                      <Image
+                        src={user.avatar_url}
+                        alt=""
+                        width={40}
+                        height={40}
+                        className="size-full object-cover"
+                      />
+                    ) : (
+                      (user.username ?? "?").charAt(0).toUpperCase()
+                    )}
                   </div>
-                </CardContent>
-              </Card>
-            ))
-          )}
+                  <div className="flex-1 min-w-0">
+                    <p className="text-sm font-medium truncate">
+                      {user.username ?? "Unknown"}
+                    </p>
+                    <p className="text-xs text-muted-foreground flex items-center gap-2">
+                      <span>{user.total_messages} messages</span>
+                      {user.flagged_count > 0 && (
+                        <Badge
+                          variant="destructive"
+                          className="text-[10px] px-1.5 py-0 h-4"
+                        >
+                          {user.flagged_count} flagged
+                        </Badge>
+                      )}
+                    </p>
+                  </div>
+                  <ChevronRight className="size-4 text-muted-foreground shrink-0" />
+                </div>
+              </CardContent>
+            </Card>
+          ))}
         </div>
       )}
     </div>
   );
 }
 
-// ── Channels View ───────────────────────────────
+// ── Channels Section ────────────────────────────
 
-function ChannelsView({
-  onSelectChannel,
+function ChannelsSection({
   guildId,
+  onSelect,
 }: {
-  onSelectChannel: (channelId: string) => void;
   guildId: string;
+  onSelect: (id: string) => void;
 }) {
-  const [channels, setChannels] = useState<DashboardChannel[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [search, setSearch] = useState("");
-
-  const fetchChannels = useCallback(
-    async (searchQuery?: string) => {
-      setLoading(true);
-      try {
-        const result = await dashboardApi.listChannels(
-          20,
-          searchQuery,
-          guildId || undefined,
-        );
-        setChannels(result.data);
-      } catch {
-        // ignore
-      } finally {
-        setLoading(false);
-      }
-    },
-    [guildId],
-  );
+  const { channels, loading, search, setSearch, refetch } =
+    useChannels(guildId);
 
   useEffect(() => {
-    fetchChannels();
-  }, [fetchChannels]);
-
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      if (search) fetchChannels(search);
-      else fetchChannels();
-    }, 300);
+    const timer = setTimeout(refetch, 300);
     return () => clearTimeout(timer);
-  }, [search, fetchChannels]);
+  }, [refetch]);
 
   return (
     <div className="space-y-4 animate-fade-in-up">
       <div className="relative">
         <Search className="absolute left-3 top-1/2 -translate-y-1/2 size-4 text-muted-foreground" />
         <Input
-          type="text"
           placeholder="Search channels…"
           value={search}
           onChange={(e) => setSearch(e.target.value)}
@@ -512,59 +379,48 @@ function ChannelsView({
       </div>
 
       {loading ? (
-        <div className="space-y-2">
-          {Array.from({ length: 6 }, (_, i) => (
-            <Skeleton key={i} className="h-20 rounded-xl" />
-          ))}
-        </div>
+        <LoadingSkeleton count={6} height="h-20" />
+      ) : channels.length === 0 ? (
+        <EmptyState icon={Hash} title="No channels found." />
       ) : (
         <div className="space-y-2">
-          {channels.length === 0 ? (
-            <div className="flex flex-col items-center justify-center py-16 text-center">
-              <Hash className="size-10 text-muted-foreground/40 mb-3" />
-              <p className="text-sm text-muted-foreground">
-                No channels found.
-              </p>
-            </div>
-          ) : (
-            channels.map((ch) => (
-              <Card
-                key={ch.channel_id}
-                className="cursor-pointer hover:bg-accent/5 transition-colors"
-                onClick={() => onSelectChannel(ch.channel_id)}
-              >
-                <CardContent className="p-4">
-                  <div className="flex items-center justify-between">
-                    <div className="min-w-0 flex-1">
-                      <div className="flex items-center gap-2">
-                        <Hash className="size-3.5 text-muted-foreground shrink-0" />
-                        <p className="text-sm font-medium truncate">
-                          {ch.channel_name ?? ch.channel_id.slice(0, 8)}
-                        </p>
-                      </div>
-                      <p className="text-xs text-muted-foreground mt-0.5 flex items-center gap-2">
-                        <span>{ch.total_messages} messages</span>
-                        {ch.flagged_count > 0 && (
-                          <Badge
-                            variant="destructive"
-                            className="text-[10px] px-1.5 py-0 h-4"
-                          >
-                            {ch.flagged_count} flagged
-                          </Badge>
-                        )}
+          {channels.map((ch) => (
+            <Card
+              key={ch.channel_id}
+              className="cursor-pointer hover:bg-accent/5 transition-colors"
+              onClick={() => onSelect(ch.channel_id)}
+            >
+              <CardContent className="p-4">
+                <div className="flex items-center justify-between">
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <Hash className="size-3.5 text-muted-foreground shrink-0" />
+                      <p className="text-sm font-medium truncate">
+                        {ch.channel_name ?? ch.channel_id.slice(0, 8)}
                       </p>
                     </div>
-                    <ChevronRight className="size-4 text-muted-foreground shrink-0 ml-2" />
-                  </div>
-                  {ch.culture_summary && (
-                    <p className="text-xs text-muted-foreground/70 mt-2 italic line-clamp-2 border-t border-border/50 pt-2">
-                      &ldquo;{ch.culture_summary}&rdquo;
+                    <p className="text-xs text-muted-foreground mt-0.5 flex items-center gap-2">
+                      <span>{ch.total_messages} messages</span>
+                      {ch.flagged_count > 0 && (
+                        <Badge
+                          variant="destructive"
+                          className="text-[10px] px-1.5 py-0 h-4"
+                        >
+                          {ch.flagged_count} flagged
+                        </Badge>
+                      )}
                     </p>
-                  )}
-                </CardContent>
-              </Card>
-            ))
-          )}
+                  </div>
+                  <ChevronRight className="size-4 text-muted-foreground shrink-0 ml-2" />
+                </div>
+                {ch.culture_summary && (
+                  <p className="text-xs text-muted-foreground/70 mt-2 italic line-clamp-2 border-t border-border/50 pt-2">
+                    &ldquo;{ch.culture_summary}&rdquo;
+                  </p>
+                )}
+              </CardContent>
+            </Card>
+          ))}
         </div>
       )}
     </div>
@@ -582,12 +438,10 @@ function UserDetailView({
 }) {
   return (
     <div className="space-y-5 animate-fade-in-up">
-      <div className="flex items-center gap-3">
-        <Button variant="ghost" size="sm" onClick={onBack}>
-          <ArrowLeft className="size-4 mr-1" />
-          Back
-        </Button>
-      </div>
+      <Button variant="ghost" size="sm" onClick={onBack}>
+        <ArrowLeft className="size-4 mr-1" />
+        Back
+      </Button>
 
       <Card>
         <CardContent className="p-6 space-y-5">
@@ -609,7 +463,7 @@ function UserDetailView({
               <h2 className="text-lg font-semibold">
                 {user.username ?? "Unknown"}
               </h2>
-              <p className="text-sm text-muted-foreground font-mono text-xs">
+              <p className="text-xs text-muted-foreground font-mono">
                 {user.user_id}
               </p>
             </div>
@@ -684,12 +538,10 @@ function ChannelDetailView({
 }) {
   return (
     <div className="space-y-5 animate-fade-in-up">
-      <div className="flex items-center gap-3">
-        <Button variant="ghost" size="sm" onClick={onBack}>
-          <ArrowLeft className="size-4 mr-1" />
-          Back
-        </Button>
-      </div>
+      <Button variant="ghost" size="sm" onClick={onBack}>
+        <ArrowLeft className="size-4 mr-1" />
+        Back
+      </Button>
 
       <Card>
         <CardContent className="p-6 space-y-5">
@@ -698,7 +550,7 @@ function ChannelDetailView({
               <Hash className="size-5 text-muted-foreground" />
               {channel.channel_name ?? channel.channel_id.slice(0, 8)}
             </h2>
-            <p className="text-xs text-muted-foreground font-mono mt-0.5">
+            <p className="text-xs text-muted-foreground font-mono">
               {channel.channel_id}
             </p>
           </div>
@@ -762,35 +614,3 @@ function ChannelDetailView({
     </div>
   );
 }
-
-// ── Shared Components ───────────────────────────
-
-function DetailStat({
-  label,
-  value,
-  variant,
-  suffix,
-}: {
-  label: string;
-  value: number;
-  variant?: "default" | "danger" | "success";
-  suffix?: string;
-}) {
-  return (
-    <Card>
-      <CardContent className="p-3">
-        <p className="text-xs text-muted-foreground">{label}</p>
-        <p
-          className={cn(
-            "text-lg font-bold tabular-nums",
-            variant === "danger" && "text-destructive",
-            variant === "success" && "text-green-500",
-          )}
-        >
-          {formatNumber(value)}
-          {suffix}
-        </p>
-      </CardContent>
-    </Card>
-  );
-}

services/frontend/src/app/(dashboard)/layout.tsx

@@ -2,24 +2,12 @@
 
 import { Suspense } from "react";
 
-import { Header } from "@/components/layout/header";
-import { MobileTabBar } from "@/components/layout/mobile-tab-bar";
-import { Sidebar } from "@/components/layout/sidebar";
-import { MascotChatbot } from "@/components/mascot/mascot-chatbot";
-import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
+import { Chatbot } from "@/components/chatbot/chatbot";
+import { AppHeader } from "@/components/layout/app-header";
+import { AppSidebar } from "@/components/layout/app-sidebar";
+import { MobileNav } from "@/components/layout/mobile-nav";
 import { WsProvider } from "@/lib/ws/context";
 
-function LoadingFallback() {
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-background">
-      <div className="flex flex-col items-center gap-3">
-        <div className="size-8 animate-spin rounded-full border-2 border-primary border-t-transparent" />
-        <p className="text-sm text-muted-foreground">Loading dashboard…</p>
-      </div>
-    </div>
-  );
-}
-
 export default function DashboardLayout({
   children,
 }: {
@@ -27,19 +15,25 @@ export default function DashboardLayout({
 }) {
   return (
     <WsProvider>
-      <SidebarProvider defaultOpen={true}>
-        <div className="flex min-h-screen bg-background">
-          <Sidebar />
-          <SidebarInset className="flex flex-col">
-            <Header />
-            <main className="flex-1 p-4 md:p-6 pb-20 md:pb-6 animate-fade-in-up">
-              <Suspense fallback={<LoadingFallback />}>{children}</Suspense>
-            </main>
-          </SidebarInset>
-          <MobileTabBar />
+      <div className="flex h-screen overflow-hidden bg-background">
+        <AppSidebar />
+        <div className="flex flex-1 flex-col min-w-0">
+          <AppHeader />
+          <main className="flex-1 overflow-y-auto p-4 md:p-6 pb-20 md:pb-6">
+            <Suspense
+              fallback={
+                <div className="flex h-full items-center justify-center">
+                  <div className="size-6 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+                </div>
+              }
+            >
+              {children}
+            </Suspense>
+          </main>
         </div>
-      </SidebarProvider>
-      <MascotChatbot />
+        <MobileNav />
+      </div>
+      <Chatbot />
     </WsProvider>
   );
 }

services/frontend/src/app/(dashboard)/media/page.tsx

@@ -8,81 +8,29 @@ import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Slider } from "@/components/ui/slider";
-import { voiceApi } from "@/lib/api";
-import type { MediaState } from "@/lib/types";
+import { useMediaState } from "@/hooks";
 import { useWebSocket } from "@/lib/ws/context";
 
 export default function MediaPage() {
   const ws = useWebSocket();
-
-  const [mediaState, setMediaState] = useState<MediaState | null>(null);
+  const { mediaState, refresh, queue, skip, stop, setVolume } = useMediaState();
   const [queueUrl, setQueueUrl] = useState("");
 
-  const fetchMediaStatus = useCallback(async () => {
-    try {
-      const state = await voiceApi.getMediaStatus();
-      setMediaState(state);
-    } catch {
-      // ignore
-    }
-  }, []);
-
   useEffect(() => {
-    fetchMediaStatus();
-  }, [fetchMediaStatus]);
+    refresh();
+  }, [refresh]);
 
-  // WS subscription
+  // WS subscription for real-time media state
   useEffect(() => {
-    const unsubMedia = ws.on("media_state", (state) => {
-      setMediaState(state as MediaState);
-    });
+    const unsub = ws.on("media_state", () => refresh());
+    return unsub;
+  }, [ws, refresh]);
 
-    return () => {
-      unsubMedia();
-    };
-  }, [ws]);
-
-  const handleQueueMedia = useCallback(async () => {
+  const handleQueue = useCallback(() => {
     if (!queueUrl.trim()) return;
-    try {
-      const state = await voiceApi.mediaQueue(queueUrl.trim(), "music");
-      setMediaState(state);
-      setQueueUrl("");
-    } catch {
-      // ignore
-    }
-  }, [queueUrl]);
-
-  const handleSkip = useCallback(async () => {
-    try {
-      const state = await voiceApi.mediaSkip();
-      setMediaState(state);
-    } catch {
-      // ignore
-    }
-  }, []);
-
-  const handleStop = useCallback(async () => {
-    try {
-      const state = await voiceApi.mediaStop();
-      setMediaState(state);
-    } catch {
-      // ignore
-    }
-  }, []);
-
-  const handleVolume = useCallback(
-    async (value: number | readonly number[]) => {
-      const vol = Array.isArray(value) ? value[0] : value;
-      try {
-        const state = await voiceApi.mediaVolume(vol);
-        setMediaState(state);
-      } catch {
-        // ignore
-      }
-    },
-    [],
-  );
+    queue(queueUrl.trim());
+    setQueueUrl("");
+  }, [queueUrl, queue]);
 
   return (
     <div className="space-y-5 animate-fade-in-up">
@@ -94,23 +42,20 @@ export default function MediaPage() {
           </CardTitle>
         </CardHeader>
         <CardContent className="space-y-4">
-          {/* Queue URL */}
           <div className="flex gap-2">
             <Input
-              type="text"
               placeholder="Queue a URL (YouTube, audio file…)"
               value={queueUrl}
               onChange={(e) => setQueueUrl(e.target.value)}
-              onKeyDown={(e) => e.key === "Enter" && handleQueueMedia()}
+              onKeyDown={(e) => e.key === "Enter" && handleQueue()}
               className="flex-1 h-9"
             />
-            <Button onClick={handleQueueMedia} disabled={!queueUrl.trim()}>
+            <Button onClick={handleQueue} disabled={!queueUrl.trim()}>
               <Play className="size-4 mr-1.5" />
               Queue
             </Button>
           </div>
 
-          {/* Now Playing */}
           {mediaState?.current && (
             <div className="rounded-lg bg-gradient-to-br from-primary/5 to-primary/[0.02] border border-primary/10 p-4 space-y-2">
               <p className="text-xs text-muted-foreground font-medium uppercase tracking-wider flex items-center gap-1.5">
@@ -133,9 +78,7 @@ export default function MediaPage() {
                   </p>
                   <p className="text-xs text-muted-foreground mt-0.5">
                     {mediaState.current.durationMs
-                      ? `${Math.floor(
-                          mediaState.current.durationMs / 60000,
-                        )}:${String(
+                      ? `${Math.floor(mediaState.current.durationMs / 60000)}:${String(
                           Math.floor(
                             (mediaState.current.durationMs % 60000) / 1000,
                           ),
@@ -153,13 +96,12 @@ export default function MediaPage() {
             </p>
           )}
 
-          {/* Controls */}
           <div className="flex items-center gap-2">
-            <Button variant="outline" size="sm" onClick={handleStop}>
+            <Button variant="outline" size="sm" onClick={stop}>
               <Square className="size-4 mr-1" />
               Stop
             </Button>
-            <Button variant="outline" size="sm" onClick={handleSkip}>
+            <Button variant="outline" size="sm" onClick={skip}>
               <SkipForward className="size-4 mr-1" />
               Skip
             </Button>
@@ -169,7 +111,7 @@ export default function MediaPage() {
                 className="w-24"
                 defaultValue={[mediaState?.musicVolume ?? 0.5]}
                 value={[mediaState?.musicVolume ?? 0.5]}
-                onValueChange={handleVolume}
+                onValueChange={setVolume}
                 min={0}
                 max={1}
                 step={0.05}
@@ -177,7 +119,6 @@ export default function MediaPage() {
             </div>
           </div>
 
-          {/* Queue */}
           {mediaState && mediaState.queue.length > 0 && (
             <div className="space-y-1.5">
               <p className="text-xs text-muted-foreground font-medium">

services/frontend/src/app/(dashboard)/recordings/page.tsx

@@ -1,54 +1,31 @@
 "use client";
 
 import { Download, Headphones, Trash2 } from "lucide-react";
-import { useCallback, useEffect, useState } from "react";
-
+import { useEffect } from "react";
+import { EmptyState, LoadingSkeleton } from "@/components/shared";
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-import { recordingsApi } from "@/lib/api";
+import { useRecordings } from "@/hooks";
 import { formatBytes } from "@/lib/format";
-import type { VoiceRecording } from "@/lib/types";
 import { useWebSocket } from "@/lib/ws/context";
 
 export default function RecordingsPage() {
   const ws = useWebSocket();
-  const [recordings, setRecordings] = useState<VoiceRecording[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  const fetchRecordings = useCallback(async () => {
-    setLoading(true);
-    try {
-      const result = await recordingsApi.list(50);
-      setRecordings(result.items);
-    } catch {
-      // ignore
-    } finally {
-      setLoading(false);
-    }
-  }, []);
+  const { recordings, loading, refresh, remove, prepend } = useRecordings();
 
   useEffect(() => {
-    fetchRecordings();
-  }, [fetchRecordings]);
+    refresh();
+  }, [refresh]);
 
-  // WS subscription for live updates
+  // WS subscription for real-time updates
   useEffect(() => {
-    const unsub = ws.on("voice_recording_uploaded", (rec) => {
-      setRecordings((prev) => [rec as VoiceRecording, ...prev]);
+    const unsub = ws.on("voice_recording_uploaded", (data) => {
+      prepend(data as import("@/lib/types").VoiceRecording);
     });
-    return () => unsub();
-  }, [ws]);
-
-  const handleDelete = useCallback(async (id: string) => {
-    try {
-      await recordingsApi.delete(id);
-      setRecordings((prev) => prev.filter((r) => r.id !== id));
-    } catch {
-      // ignore
-    }
-  }, []);
+    return unsub;
+  }, [ws, prepend]);
 
   return (
     <div className="space-y-5 animate-fade-in-up">
@@ -61,18 +38,9 @@ export default function RecordingsPage() {
         </CardHeader>
         <CardContent>
           {loading ? (
-            <div className="space-y-2">
-              {Array.from({ length: 5 }, (_, i) => (
-                <div
-                  key={i}
-                  className="h-16 rounded-lg bg-muted/30 animate-pulse"
-                />
-              ))}
-            </div>
+            <LoadingSkeleton count={5} height="h-16" />
           ) : recordings.length === 0 ? (
-            <p className="text-sm text-muted-foreground py-8 text-center">
-              No recordings yet.
-            </p>
+            <EmptyState icon={Headphones} title="No recordings yet." />
           ) : (
             <div className="space-y-2">
               {recordings.map((rec) => (
@@ -117,7 +85,7 @@ export default function RecordingsPage() {
                   <Button
                     variant="ghost"
                     size="icon"
-                    onClick={() => handleDelete(rec.id)}
+                    onClick={() => remove(rec.id)}
                     className="hover:text-destructive hover:bg-destructive/10"
                   >
                     <Trash2 className="size-4" />

services/frontend/src/app/(dashboard)/settings/page.tsx

@@ -2,20 +2,17 @@
 
 import { Moon, Server, Shield, Sun, Wifi } from "lucide-react";
 import { useEffect, useState } from "react";
-
+import { LoadingSkeleton } from "@/components/shared";
 import { Badge } from "@/components/ui/badge";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";
-import { Skeleton } from "@/components/ui/skeleton";
-import { configApi } from "@/lib/api";
-import type { AppConfig } from "@/lib/types";
+import { useConfig } from "@/hooks";
 import { cn } from "@/lib/utils";
 import { useWebSocket } from "@/lib/ws/context";
 
 export default function SettingsPage() {
   const { status } = useWebSocket();
-  const [config, setConfig] = useState<AppConfig | null>(null);
-  const [configLoading, setConfigLoading] = useState(true);
+  const { config, loading: configLoading } = useConfig();
   const [theme, setTheme] = useState<"light" | "dark">("dark");
 
   useEffect(() => {
@@ -23,14 +20,6 @@ export default function SettingsPage() {
     if (stored) setTheme(stored);
   }, []);
 
-  useEffect(() => {
-    configApi
-      .get()
-      .then(setConfig)
-      .catch(() => {})
-      .finally(() => setConfigLoading(false));
-  }, []);
-
   const toggleTheme = () => {
     const next = theme === "dark" ? "light" : "dark";
     setTheme(next);
@@ -64,7 +53,6 @@ export default function SettingsPage() {
 
   return (
     <div className="space-y-5 animate-fade-in-up max-w-2xl">
-      {/* Connection Status */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2 text-sm font-semibold">
@@ -86,7 +74,6 @@ export default function SettingsPage() {
         </CardContent>
       </Card>
 
-      {/* Appearance */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2 text-sm font-semibold">
@@ -112,7 +99,6 @@ export default function SettingsPage() {
         </CardContent>
       </Card>
 
-      {/* Server Config */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2 text-sm font-semibold">
@@ -122,11 +108,7 @@ export default function SettingsPage() {
         </CardHeader>
         <CardContent>
           {configLoading ? (
-            <div className="space-y-2">
-              {Array.from({ length: 6 }, (_, i) => (
-                <Skeleton key={i} className="h-6 w-full" />
-              ))}
-            </div>
+            <LoadingSkeleton count={6} height="h-6" />
           ) : config ? (
             <div className="space-y-2 text-sm">
               <ConfigRow
@@ -162,7 +144,6 @@ export default function SettingsPage() {
         </CardContent>
       </Card>
 
-      {/* About */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2 text-sm font-semibold">
@@ -173,8 +154,8 @@ export default function SettingsPage() {
         <CardContent>
           <div className="text-sm space-y-1">
             <p>
-              <span className="text-gradient font-bold">Bete</span> — Discord
-              Moderation Watcher
+              <span className="text-gradient font-bold">DC Automod</span> —
+              Discord Moderation Watcher
             </p>
             <p className="text-xs text-muted-foreground">
               AI-powered message moderation, voice recording, and real-time

services/frontend/src/app/(dashboard)/voice/page.tsx

@@ -21,115 +21,75 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { Switch } from "@/components/ui/switch";
+import {
+  useGuilds,
+  useSpeakers,
+  useVoiceChannels,
+  useVoiceStatus,
+} from "@/hooks";
 import { voiceApi } from "@/lib/api";
-import type { ActiveSpeaker, VoiceStatus } from "@/lib/types";
 import { cn } from "@/lib/utils";
 import { useWebSocket } from "@/lib/ws/context";
 
 export default function VoicePage() {
   const ws = useWebSocket();
+  const { voiceStatus, refresh: refreshStatus } = useVoiceStatus();
+  const { guilds } = useGuilds();
+  const { channels: voiceChannels, fetch: fetchChannels } = useVoiceChannels();
+  const { speakers, subscribe } = useSpeakers();
 
-  const [voiceStatus, setVoiceStatus] = useState<VoiceStatus | null>(null);
-  const [speakers, setSpeakers] = useState<ActiveSpeaker[]>([]);
-  const [guilds, setGuilds] = useState<Array<{ id: string; name: string }>>([]);
-  const [voiceChannels, setVoiceChannels] = useState<
-    Array<{ id: string; name: string }>
-  >([]);
   const [selectedGuild, setSelectedGuild] = useState("");
   const [selectedChannel, setSelectedChannel] = useState("");
   const [voiceLoading, setVoiceLoading] = useState(false);
   const [micActive, setMicActive] = useState(false);
-  const [guildsLoading, setGuildsLoading] = useState(true);
-
-  const fetchVoiceStatus = useCallback(async () => {
-    try {
-      const status = await voiceApi.getStatus();
-      setVoiceStatus(status);
-    } catch {
-      // ignore
-    }
-  }, []);
-
-  const fetchGuilds = useCallback(async () => {
-    setGuildsLoading(true);
-    try {
-      const g = await voiceApi.getGuilds();
-      setGuilds(g);
-    } catch {
-      // ignore
-    } finally {
-      setGuildsLoading(false);
-    }
-  }, []);
 
+  // Subscribe to WS speaker events
   useEffect(() => {
-    fetchVoiceStatus();
-    fetchGuilds();
-  }, [fetchVoiceStatus, fetchGuilds]);
+    const unsub = subscribe(ws);
+    return () => unsub();
+  }, [ws, subscribe]);
 
-  // WS subscriptions
-  useEffect(() => {
-    const unsubSpeaker = ws.on("voice_active_user", (user) => {
-      const speaker = user as ActiveSpeaker;
-      setSpeakers((prev) => {
-        const existing = prev.findIndex((s) => s.userId === speaker.userId);
-        if (existing >= 0) {
-          const next = [...prev];
-          next[existing] = speaker;
-          return next;
-        }
-        return [...prev, speaker];
-      });
-    });
-
-    return () => {
-      unsubSpeaker();
-    };
-  }, [ws]);
-
-  const handleGuildChange = useCallback(async (guildId: string | null) => {
-    if (!guildId) {
-      setSelectedGuild("");
-      setVoiceChannels([]);
-      return;
-    }
-    setSelectedGuild(guildId);
-    setSelectedChannel("");
-    try {
-      const channels = await voiceApi.getVoiceChannels(guildId);
-      setVoiceChannels(channels);
-    } catch {
-      setVoiceChannels([]);
-    }
-  }, []);
+  const handleGuildChange = useCallback(
+    (guildId: string | null) => {
+      if (!guildId) {
+        setSelectedGuild("");
+        setSelectedChannel("");
+        return;
+      }
+      setSelectedGuild(guildId);
+      setSelectedChannel("");
+      fetchChannels(guildId);
+    },
+    [fetchChannels],
+  );
 
   const handleConnect = useCallback(async () => {
     if (!selectedGuild || !selectedChannel) return;
     setVoiceLoading(true);
     try {
-      const status = await voiceApi.connect(selectedGuild, selectedChannel);
-      setVoiceStatus(status);
+      const _status = await voiceApi.connect(selectedGuild, selectedChannel);
+      // voiceStatus will be refreshed
+      setVoiceLoading(false);
+      refreshStatus();
     } finally {
       setVoiceLoading(false);
     }
-  }, [selectedGuild, selectedChannel]);
+  }, [selectedGuild, selectedChannel, refreshStatus]);
 
   const handleDisconnect = useCallback(async () => {
     setVoiceLoading(true);
     try {
-      const status = await voiceApi.disconnect();
-      setVoiceStatus(status);
-      setSpeakers([]);
+      await voiceApi.disconnect();
+      refreshStatus();
     } finally {
       setVoiceLoading(false);
     }
-  }, []);
+  }, [refreshStatus]);
 
   const activeSpeakers = speakers.filter((s) => s.speaking);
 
   return (
     <div className="space-y-5 animate-fade-in-up">
-      {/* Voice Connection */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center justify-between">
@@ -168,17 +128,9 @@ export default function VoicePage() {
           )}
 
           <div className="flex flex-col sm:flex-row gap-2">
-            <Select
-              value={selectedGuild}
-              onValueChange={handleGuildChange}
-              disabled={guildsLoading}
-            >
+            <Select value={selectedGuild} onValueChange={handleGuildChange}>
               <SelectTrigger className="flex-1 h-9">
-                <SelectValue
-                  placeholder={
-                    guildsLoading ? "Loading guilds…" : "Select guild…"
-                  }
-                />
+                <SelectValue placeholder="Select guild…" />
               </SelectTrigger>
               <SelectContent>
                 {guilds.map((g) => (
@@ -197,11 +149,17 @@ export default function VoicePage() {
                 <SelectValue placeholder="Select channel…" />
               </SelectTrigger>
               <SelectContent>
-                {voiceChannels.map((c) => (
-                  <SelectItem key={c.id} value={c.id}>
-                    {c.name}
+                {voiceChannels.length === 0 ? (
+                  <SelectItem value="_none" disabled>
+                    No channels loaded
                   </SelectItem>
-                ))}
+                ) : (
+                  voiceChannels.map((c) => (
+                    <SelectItem key={c.id} value={c.id}>
+                      {c.name}
+                    </SelectItem>
+                  ))
+                )}
               </SelectContent>
             </Select>
             {voiceStatus?.connected ? (
@@ -234,7 +192,6 @@ export default function VoicePage() {
         </CardContent>
       </Card>
 
-      {/* Active Speakers */}
       {activeSpeakers.length > 0 && (
         <Card>
           <CardHeader>
@@ -262,7 +219,6 @@ export default function VoicePage() {
         </Card>
       )}
 
-      {/* Microphone */}
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center justify-between">

services/frontend/src/app/layout.tsx

@@ -16,7 +16,7 @@ const geistMono = Geist_Mono({
 });
 
 export const metadata: Metadata = {
-  title: "Bete — Discord Moderation Dashboard",
+  title: "DC Automod — Discord Moderation Dashboard",
   description: "Live Discord monitoring and AI moderation dashboard",
 };
 

services/frontend/src/components/chatbot/chatbot.tsx

@@ -22,11 +22,11 @@ import {
 } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { ScrollArea } from "@/components/ui/scroll-area";
-import { mascotApi } from "@/lib/api";
+import { chatbotApi } from "@/lib/api";
 import type { ChatHistoryMessage } from "@/lib/types";
 import { cn } from "@/lib/utils";
 
-export function MascotChatbot() {
+export function Chatbot() {
   const [open, setOpen] = useState(false);
   const [messages, setMessages] = useState<ChatHistoryMessage[]>([]);
   const [input, setInput] = useState("");
@@ -35,7 +35,7 @@ export function MascotChatbot() {
 
   useEffect(() => {
     if (!open) return;
-    mascotApi
+    chatbotApi
       .getHistory()
       .then(setMessages)
       .catch(() => {});
@@ -49,7 +49,7 @@ export function MascotChatbot() {
 
   const handleClear = useCallback(async () => {
     try {
-      await mascotApi.clearHistory();
+      await chatbotApi.clearHistory();
       setMessages([]);
     } catch {
       // ignore
@@ -69,7 +69,7 @@ export function MascotChatbot() {
     ]);
 
     try {
-      const resp = await mascotApi.send(text);
+      const resp = await chatbotApi.send(text);
       setMessages((prev) => [
         ...prev,
         {
@@ -115,7 +115,7 @@ export function MascotChatbot() {
               <div className="flex size-6 items-center justify-center rounded-full bg-primary/10">
                 <Bot className="size-3.5 text-primary" />
               </div>
-              Mascot
+              Chatbot
               <Sparkles className="size-3 text-primary/60 ml-0.5" />
               <div className="flex-1" />
               {messages.length > 0 && (

services/frontend/src/components/landing/live-stats.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { Skeleton } from "@/components/ui/skeleton";
+import { dashboardApi, voiceApi } from "@/lib/api";
+import { cn } from "@/lib/utils";
+
+interface LiveStats {
+  totalMessages: number | null;
+  todayMessages: number | null;
+  totalFlagged: number | null;
+  totalRecordings: number | null;
+  guildCount: number;
+  wsConnected: boolean;
+}
+
+export function LiveStats() {
+  const [stats, setStats] = useState<LiveStats>({
+    totalMessages: null,
+    todayMessages: null,
+    totalFlagged: null,
+    totalRecordings: null,
+    guildCount: 0,
+    wsConnected: false,
+  });
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    async function fetch() {
+      try {
+        const [dashStats, guilds] = await Promise.all([
+          dashboardApi.getStats().catch(() => null),
+          voiceApi.getGuilds().catch(() => [] as { id: string }[]),
+        ]);
+        if (cancelled) return;
+        setStats({
+          totalMessages: dashStats?.total_messages ?? null,
+          todayMessages: dashStats?.today_messages ?? null,
+          totalFlagged: dashStats?.total_flagged ?? null,
+          totalRecordings: dashStats?.total_voice_recordings ?? null,
+          guildCount: guilds.length,
+          wsConnected: false,
+        });
+      } catch {
+        // ignore
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+    fetch();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (loading) {
+    return (
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-4 max-w-3xl mx-auto">
+        {Array.from({ length: 4 }, (_, i) => (
+          <Skeleton key={i} className="h-24 rounded-xl" />
+        ))}
+      </div>
+    );
+  }
+
+  const items = [
+    {
+      label: "Messages Captured",
+      value: stats.totalMessages ?? "—",
+      color: "from-sky-500/20 to-cyan-500/10 border-sky-500/30",
+    },
+    {
+      label: "Today",
+      value: stats.todayMessages ?? "—",
+      color: "from-emerald-500/20 to-teal-500/10 border-emerald-500/30",
+    },
+    {
+      label: "Flagged",
+      value: stats.totalFlagged ?? "—",
+      color: "from-rose-500/20 to-pink-500/10 border-rose-500/30",
+    },
+    {
+      label: "Voice Recordings",
+      value: stats.totalRecordings ?? "—",
+      color: "from-violet-500/20 to-purple-500/10 border-violet-500/30",
+    },
+  ];
+
+  return (
+    <div className="grid grid-cols-2 md:grid-cols-4 gap-4 max-w-3xl mx-auto">
+      {items.map((item) => (
+        <div
+          key={item.label}
+          className={cn(
+            "rounded-xl border bg-gradient-to-br p-4 text-center backdrop-blur-sm",
+            item.color,
+          )}
+        >
+          <div className="text-2xl md:text-3xl font-bold tabular-nums tracking-tight">
+            {typeof item.value === "number"
+              ? item.value.toLocaleString()
+              : item.value}
+          </div>
+          <div className="text-xs text-muted-foreground mt-1">{item.label}</div>
+        </div>
+      ))}
+      <div className="col-span-full text-center mt-2">
+        <div className="inline-flex items-center gap-2 text-xs text-muted-foreground">
+          <span className="relative flex size-2">
+            <span className="absolute inline-flex size-full rounded-full bg-green-400 opacity-75 animate-ping" />
+            <span className="relative inline-flex size-2 rounded-full bg-green-500" />
+          </span>
+          {stats.guildCount > 0
+            ? `Monitoring ${stats.guildCount} guild${stats.guildCount > 1 ? "s" : ""}`
+            : "Connecting to gateway…"}
+        </div>
+      </div>
+    </div>
+  );
+}

services/frontend/src/components/layout/app-header.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+import { Moon, PanelLeft, Sun } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useEffect, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { navItems } from "@/lib/navigation";
+import { cn } from "@/lib/utils";
+import { useWebSocket } from "@/lib/ws/context";
+
+export function AppHeader() {
+  const pathname = usePathname();
+  const { status } = useWebSocket();
+  const [theme, setTheme] = useState<"light" | "dark">("dark");
+  const [mobileOpen, setMobileOpen] = useState(false);
+
+  useEffect(() => {
+    const stored = localStorage.getItem("theme") as "light" | "dark" | null;
+    if (stored) setTheme(stored);
+  }, []);
+
+  const toggleTheme = () => {
+    const next = theme === "dark" ? "light" : "dark";
+    setTheme(next);
+    localStorage.setItem("theme", next);
+    document.documentElement.classList.remove("light", "dark");
+    document.documentElement.classList.add(next);
+  };
+
+  const pageTitle =
+    navItems
+      .filter((n) =>
+        n.matchPrefix === "/dashboard"
+          ? pathname === "/dashboard"
+          : pathname.startsWith(n.matchPrefix),
+      )
+      .map((n) => n.label)
+      .at(0) ?? "Dashboard";
+
+  const statusVariant =
+    status === "connected"
+      ? "default"
+      : status === "connecting"
+        ? "secondary"
+        : "destructive";
+
+  const statusLabel =
+    status === "connected"
+      ? "Connected"
+      : status === "connecting"
+        ? "Connecting"
+        : "Disconnected";
+
+  return (
+    <>
+      <header className="flex h-14 items-center gap-3 border-b border-border/50 bg-background/60 backdrop-blur-lg px-4 shrink-0">
+        {/* Mobile menu button */}
+        <Button
+          variant="ghost"
+          size="icon"
+          className="md:hidden size-8 -ml-1 text-muted-foreground"
+          onClick={() => setMobileOpen(!mobileOpen)}
+          aria-label="Toggle menu"
+        >
+          <PanelLeft className="size-4" />
+        </Button>
+
+        <h1 className="text-sm font-semibold">{pageTitle}</h1>
+
+        <div className="flex-1" />
+
+        <Badge
+          variant={statusVariant}
+          className="gap-1.5 px-2.5 py-1 cursor-default select-none"
+        >
+          <span
+            className={cn(
+              "size-1.5 rounded-full",
+              status === "connected" &&
+                "bg-green-500 shadow-[0_0_6px] shadow-green-500/60",
+              status === "connecting" && "bg-yellow-500 animate-pulse",
+              status === "disconnected" && "bg-destructive",
+              status === "error" && "bg-destructive",
+            )}
+          />
+          <span className="hidden sm:inline text-xs">{statusLabel}</span>
+        </Badge>
+
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={toggleTheme}
+          aria-label="Toggle theme"
+          className="size-8"
+        >
+          <Sun
+            className={cn(
+              "size-4 transition-all absolute",
+              theme === "dark"
+                ? "opacity-0 rotate-90 scale-75"
+                : "opacity-100 rotate-0 scale-100",
+            )}
+          />
+          <Moon
+            className={cn(
+              "size-4 transition-all absolute",
+              theme === "dark"
+                ? "opacity-100 rotate-0 scale-100"
+                : "opacity-0 -rotate-90 scale-75",
+            )}
+          />
+        </Button>
+      </header>
+
+      {/* Mobile overlay menu */}
+      {mobileOpen && (
+        <div className="fixed inset-0 z-50 md:hidden">
+          {/* biome-ignore lint/a11y/noStaticElementInteractions: overlay backdrop */}
+          <div
+            className="absolute inset-0 bg-black/50"
+            role="button"
+            tabIndex={0}
+            onClick={() => setMobileOpen(false)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") setMobileOpen(false);
+            }}
+          />
+          <aside className="absolute left-0 top-0 bottom-0 w-60 bg-sidebar border-r border-sidebar-border p-2 space-y-0.5">
+            {navItems.map(({ href, label, icon: Icon, matchPrefix }) => {
+              const active = isActivePath(pathname, matchPrefix);
+              return (
+                <button
+                  key={href}
+                  type="button"
+                  onClick={() => {
+                    window.location.href = href;
+                    setMobileOpen(false);
+                  }}
+                  className={cn(
+                    "flex w-full items-center gap-3 rounded-lg px-3 py-2 text-sm transition-all text-left",
+                    active
+                      ? "bg-sidebar-accent text-sidebar-accent-foreground font-medium"
+                      : "text-sidebar-foreground/70 hover:bg-sidebar-accent/50",
+                  )}
+                >
+                  <Icon className="size-4 shrink-0" />
+                  <span>{label}</span>
+                </button>
+              );
+            })}
+          </aside>
+        </div>
+      )}
+    </>
+  );
+}
+
+function isActivePath(pathname: string, prefix: string) {
+  if (prefix === "/dashboard") return pathname === "/dashboard";
+  return pathname.startsWith(prefix);
+}

services/frontend/src/components/layout/app-sidebar.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import { usePathname, useRouter } from "next/navigation";
+
+import { navItems } from "@/lib/navigation";
+import { cn } from "@/lib/utils";
+import { useWebSocket } from "@/lib/ws/context";
+
+export function AppSidebar() {
+  const pathname = usePathname();
+  const router = useRouter();
+  const { status } = useWebSocket();
+
+  const isActive = (prefix: string) => {
+    if (prefix === "/dashboard") return pathname === "/dashboard";
+    return pathname.startsWith(prefix);
+  };
+
+  const connectionDot = {
+    connected: "bg-green-500",
+    connecting: "bg-yellow-500 animate-pulse",
+    disconnected: "bg-destructive",
+    error: "bg-destructive",
+  }[status];
+
+  const connectionLabel = {
+    connected: "Connected",
+    connecting: "Connecting",
+    disconnected: "Disconnected",
+    error: "Error",
+  }[status];
+
+  return (
+    <aside className="hidden md:flex md:w-60 flex-col border-r border-border/50 bg-sidebar shrink-0">
+      {/* Brand */}
+      <div className="flex h-14 items-center gap-2.5 border-b border-sidebar-border/50 px-4 shrink-0">
+        <div className="flex size-8 items-center justify-center rounded-lg bg-gradient-to-br from-sky-500 to-cyan-400 text-white text-xs font-bold">
+          D
+        </div>
+        <div>
+          <div className="text-sm font-bold tracking-tight">
+            <span className="text-gradient">DC Automod</span>
+          </div>
+          <div className="text-[10px] text-muted-foreground tracking-widest uppercase leading-none">
+            Dashboard
+          </div>
+        </div>
+      </div>
+
+      {/* Nav */}
+      <nav className="flex-1 overflow-y-auto p-2 space-y-0.5">
+        {navItems.map(({ href, label, icon: Icon, matchPrefix }) => {
+          const active = isActive(matchPrefix);
+          return (
+            <button
+              key={href}
+              type="button"
+              onClick={() => router.push(href)}
+              className={cn(
+                "flex w-full items-center gap-3 rounded-lg px-3 py-2 text-sm transition-all duration-150 text-left",
+                active
+                  ? "bg-sidebar-accent text-sidebar-accent-foreground font-medium"
+                  : "text-sidebar-foreground/70 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground",
+              )}
+            >
+              <Icon
+                className={cn(
+                  "size-4 shrink-0 transition-all",
+                  active && "text-sky-400",
+                )}
+              />
+              <span className="truncate">{label}</span>
+              {active && (
+                <div className="ml-auto w-0.5 h-4 rounded-full bg-gradient-to-b from-sky-400 to-cyan-400" />
+              )}
+            </button>
+          );
+        })}
+      </nav>
+
+      {/* Connection status */}
+      <div className="border-t border-sidebar-border/50 p-3 shrink-0">
+        <div className="flex items-center gap-2">
+          <span className="relative flex size-2 shrink-0">
+            <span
+              className={cn(
+                "absolute inline-flex size-full rounded-full opacity-75",
+                connectionDot,
+                status === "connected" && "animate-ping",
+              )}
+            />
+            <span
+              className={cn(
+                "relative inline-flex size-2 rounded-full",
+                connectionDot,
+              )}
+            />
+          </span>
+          <span className="text-xs text-muted-foreground truncate">
+            {connectionLabel}
+          </span>
+        </div>
+      </div>
+    </aside>
+  );
+}

services/frontend/src/components/layout/header.tsx

@@ -1,136 +0,0 @@
-"use client";
-
-import { Moon, Sun } from "lucide-react";
-import { usePathname } from "next/navigation";
-import { useEffect, useState } from "react";
-
-import { Badge } from "@/components/ui/badge";
-import { Button } from "@/components/ui/button";
-import { SidebarTrigger } from "@/components/ui/sidebar";
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger,
-} from "@/components/ui/tooltip";
-import { navItems } from "@/lib/navigation";
-import { cn } from "@/lib/utils";
-import { useWebSocket } from "@/lib/ws/context";
-
-function usePageTitle(): string {
-  const pathname = usePathname();
-
-  // Exact match first, then prefix match
-  const item = navItems.find((n) => {
-    if (n.matchPrefix === "/dashboard") return pathname === "/dashboard";
-    return pathname.startsWith(n.matchPrefix);
-  });
-
-  if (item) return item.label;
-
-  // Fallback: derive from pathname
-  const segment = pathname.split("/").filter(Boolean)[0];
-  if (segment) {
-    return segment.charAt(0).toUpperCase() + segment.slice(1);
-  }
-  return "Dashboard";
-}
-
-export function Header() {
-  const { status } = useWebSocket();
-  const pageTitle = usePageTitle();
-  const [theme, setTheme] = useState<"light" | "dark">("dark");
-
-  useEffect(() => {
-    const stored = localStorage.getItem("theme") as "light" | "dark" | null;
-    if (stored) setTheme(stored);
-  }, []);
-
-  const toggleTheme = () => {
-    const next = theme === "dark" ? "light" : "dark";
-    setTheme(next);
-    localStorage.setItem("theme", next);
-    document.documentElement.classList.remove("light", "dark");
-    document.documentElement.classList.add(next);
-  };
-
-  const statusVariant =
-    status === "connected"
-      ? "default"
-      : status === "connecting"
-        ? "secondary"
-        : "destructive";
-
-  const statusLabel =
-    status === "connected"
-      ? "Connected"
-      : status === "connecting"
-        ? "Connecting"
-        : status === "error"
-          ? "Error"
-          : "Disconnected";
-
-  return (
-    <header className="sticky top-0 z-10 flex h-14 items-center gap-3 border-b border-border/50 bg-background/60 backdrop-blur-lg px-4 md:px-6">
-      <SidebarTrigger className="-ml-1 size-8 text-muted-foreground hover:text-foreground" />
-
-      <h1 className="text-sm font-semibold hidden sm:block">{pageTitle}</h1>
-
-      <div className="flex-1" />
-
-      {/* Connection status */}
-      <Tooltip>
-        <TooltipTrigger>
-          <span>
-            <Badge
-              variant={statusVariant}
-              className="gap-1.5 px-2.5 py-1 cursor-default select-none"
-            >
-              <span
-                className={cn(
-                  "size-1.5 rounded-full",
-                  status === "connected" &&
-                    "bg-green-500 shadow-[0_0_6px] shadow-green-500/60",
-                  status === "connecting" && "bg-yellow-500 animate-pulse",
-                  (status === "disconnected" || status === "error") &&
-                    "bg-destructive",
-                )}
-              />
-              <span className="hidden sm:inline text-xs">{statusLabel}</span>
-            </Badge>
-          </span>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">
-          <p>WebSocket: {statusLabel}</p>
-        </TooltipContent>
-      </Tooltip>
-
-      {/* Theme toggle */}
-      <Button
-        variant="ghost"
-        size="icon"
-        onClick={toggleTheme}
-        aria-label="Toggle theme"
-        className="size-8"
-      >
-        <div className="relative size-4">
-          <Sun
-            className={cn(
-              "absolute inset-0 size-4 transition-all duration-300",
-              theme === "dark"
-                ? "opacity-0 rotate-90 scale-75"
-                : "opacity-100 rotate-0 scale-100",
-            )}
-          />
-          <Moon
-            className={cn(
-              "absolute inset-0 size-4 transition-all duration-300",
-              theme === "dark"
-                ? "opacity-100 rotate-0 scale-100"
-                : "opacity-0 -rotate-90 scale-75",
-            )}
-          />
-        </div>
-      </Button>
-    </header>
-  );
-}

services/frontend/src/components/layout/mobile-nav.tsx

@@ -6,12 +6,12 @@ import { usePathname } from "next/navigation";
 import { mobileNavItems } from "@/lib/navigation";
 import { cn } from "@/lib/utils";
 
-export function MobileTabBar() {
+export function MobileNav() {
   const pathname = usePathname();
 
-  const isActive = (matchPrefix: string) => {
-    if (matchPrefix === "/dashboard") return pathname === "/dashboard";
-    return pathname.startsWith(matchPrefix);
+  const isActive = (prefix: string) => {
+    if (prefix === "/dashboard") return pathname === "/dashboard";
+    return pathname.startsWith(prefix);
   };
 
   return (
@@ -24,10 +24,8 @@ export function MobileTabBar() {
               key={href}
               href={href}
               className={cn(
-                "flex-1 flex flex-col items-center gap-0.5 py-2 text-xs font-medium transition-all duration-200 relative",
-                active
-                  ? "text-sky-400"
-                  : "text-muted-foreground hover:text-foreground",
+                "flex-1 flex flex-col items-center gap-0.5 py-2 text-xs font-medium transition-all relative",
+                active ? "text-sky-400" : "text-muted-foreground",
               )}
             >
               <Icon className="size-5" />

services/frontend/src/components/layout/sidebar.tsx

@@ -1,142 +0,0 @@
-"use client";
-
-import { Radio } from "lucide-react";
-import { usePathname, useRouter } from "next/navigation";
-
-import {
-  SidebarContent,
-  SidebarFooter,
-  SidebarGroup,
-  SidebarGroupContent,
-  SidebarHeader,
-  SidebarMenu,
-  SidebarMenuButton,
-  SidebarMenuItem,
-  Sidebar as SidebarPrimitive,
-  useSidebar,
-} from "@/components/ui/sidebar";
-import { navItems } from "@/lib/navigation";
-import { cn } from "@/lib/utils";
-import { useWebSocket } from "@/lib/ws/context";
-
-export function Sidebar() {
-  const pathname = usePathname();
-  const router = useRouter();
-  const { state } = useSidebar();
-  const { status } = useWebSocket();
-  const collapsed = state === "collapsed";
-
-  const isActive = (matchPrefix: string) => {
-    if (matchPrefix === "/dashboard") return pathname === "/dashboard";
-    return pathname.startsWith(matchPrefix);
-  };
-
-  const connectionLabel = {
-    connected: "Connected",
-    connecting: "Connecting",
-    disconnected: "Disconnected",
-    error: "Error",
-  }[status];
-
-  const connectionColor = {
-    connected: "bg-green-500",
-    connecting: "bg-yellow-500",
-    disconnected: "bg-destructive",
-    error: "bg-destructive",
-  }[status];
-
-  return (
-    <SidebarPrimitive variant="sidebar" collapsible="icon">
-      <SidebarHeader className="border-b border-sidebar-border/50">
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <SidebarMenuButton
-              size="lg"
-              className="group-data-[collapsible=icon]:!p-0"
-              onClick={() => router.push("/dashboard")}
-            >
-              <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-gradient-to-br from-sky-500 to-cyan-400 text-sidebar-primary-foreground">
-                <Radio className="size-4" />
-              </div>
-              <div
-                className={cn(
-                  "flex flex-col gap-0.5 leading-none",
-                  collapsed && "hidden",
-                )}
-              >
-                <span className="text-base font-bold tracking-tight">
-                  <span className="text-gradient">Bete</span>
-                </span>
-                <span className="text-[10px] text-muted-foreground tracking-widest uppercase">
-                  Dashboard
-                </span>
-              </div>
-            </SidebarMenuButton>
-          </SidebarMenuItem>
-        </SidebarMenu>
-      </SidebarHeader>
-
-      <SidebarContent>
-        <SidebarGroup>
-          <SidebarGroupContent>
-            <SidebarMenu>
-              {navItems.map(({ href, label, icon: Icon, matchPrefix }) => {
-                const active = isActive(matchPrefix);
-                return (
-                  <SidebarMenuItem key={href}>
-                    <SidebarMenuButton
-                      isActive={active}
-                      tooltip={collapsed ? label : undefined}
-                      className={cn(
-                        "relative transition-all duration-200",
-                        active &&
-                          "bg-sidebar-accent/80 text-sidebar-accent-foreground font-medium",
-                      )}
-                      onClick={() => router.push(href)}
-                    >
-                      <Icon
-                        className={cn(
-                          "size-4 transition-all duration-200",
-                          active && "text-sky-400 scale-110",
-                        )}
-                      />
-                      <span>{label}</span>
-                      {active && (
-                        <div className="absolute right-0 top-1/2 -translate-y-1/2 w-0.5 h-5 rounded-full bg-gradient-to-b from-sky-400 to-cyan-400" />
-                      )}
-                    </SidebarMenuButton>
-                  </SidebarMenuItem>
-                );
-              })}
-            </SidebarMenu>
-          </SidebarGroupContent>
-        </SidebarGroup>
-      </SidebarContent>
-
-      <SidebarFooter className="border-t border-sidebar-border/50 p-3">
-        <div className="flex items-center gap-2">
-          <span className="relative flex size-2 shrink-0">
-            <span
-              className={cn(
-                "absolute inline-flex size-full rounded-full opacity-75",
-                connectionColor,
-                status === "connected" && "animate-ping",
-              )}
-            />
-            <span
-              className={cn(
-                "relative inline-flex size-2 rounded-full",
-                connectionColor,
-              )}
-            />
-          </span>
-          {!collapsed && (
-            <span className="text-xs text-muted-foreground truncate">
-              {connectionLabel}
-            </span>
-          )}
-        </div>
-      </SidebarFooter>
-    </SidebarPrimitive>
-  );
-}

services/frontend/src/components/shared/detail-stat.tsx

@@ -0,0 +1,38 @@
+import { Card, CardContent } from "@/components/ui/card";
+import { formatNumber } from "@/lib/format";
+import { cn } from "@/lib/utils";
+
+interface DetailStatProps {
+  label: string;
+  value: number;
+  variant?: "default" | "danger" | "success";
+  suffix?: string;
+}
+
+/**
+ * Small stat label used inside detail views.
+ */
+export function DetailStat({
+  label,
+  value,
+  variant = "default",
+  suffix,
+}: DetailStatProps) {
+  return (
+    <Card>
+      <CardContent className="p-3">
+        <p className="text-xs text-muted-foreground">{label}</p>
+        <p
+          className={cn(
+            "text-lg font-bold tabular-nums",
+            variant === "danger" && "text-destructive",
+            variant === "success" && "text-green-500",
+          )}
+        >
+          {formatNumber(value)}
+          {suffix}
+        </p>
+      </CardContent>
+    </Card>
+  );
+}

services/frontend/src/components/shared/empty-state.tsx

@@ -0,0 +1,26 @@
+import type { LucideIcon } from "lucide-react";
+
+interface EmptyStateProps {
+  icon: LucideIcon;
+  title: string;
+  description?: string;
+}
+
+/**
+ * Consistent empty state for data-fetching pages.
+ */
+export function EmptyState({
+  icon: Icon,
+  title,
+  description,
+}: EmptyStateProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-20 text-center">
+      <Icon className="size-10 text-muted-foreground/40 mb-3" />
+      <p className="text-sm text-muted-foreground">{title}</p>
+      {description && (
+        <p className="text-xs text-muted-foreground/60 mt-1">{description}</p>
+      )}
+    </div>
+  );
+}

services/frontend/src/components/shared/error-state.tsx

@@ -0,0 +1,27 @@
+import { AlertCircle, RefreshCw } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+
+interface ErrorStateProps {
+  message: string;
+  onRetry?: () => void;
+}
+
+/**
+ * Consistent error state for data-fetching pages.
+ * Shows the error message with an optional retry button.
+ */
+export function ErrorState({ message, onRetry }: ErrorStateProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-20 text-center">
+      <AlertCircle className="size-10 text-destructive mb-3" />
+      <p className="text-sm text-muted-foreground mb-4 max-w-sm">{message}</p>
+      {onRetry && (
+        <Button variant="outline" onClick={onRetry}>
+          <RefreshCw className="size-4 mr-2" />
+          Retry
+        </Button>
+      )}
+    </div>
+  );
+}

services/frontend/src/components/shared/index.ts

@@ -0,0 +1,5 @@
+export { DetailStat } from "./detail-stat";
+export { EmptyState } from "./empty-state";
+export { ErrorState } from "./error-state";
+export { LoadingSkeleton } from "./loading-skeleton";
+export { StatCard } from "./stat-card";

services/frontend/src/components/shared/loading-skeleton.tsx

@@ -0,0 +1,38 @@
+import { Skeleton } from "@/components/ui/skeleton";
+import { cn } from "@/lib/utils";
+
+interface LoadingSkeletonProps {
+  /** Number of skeleton rows */
+  count?: number;
+  /** Height per skeleton row */
+  height?: string;
+  /** Grid layout: columns */
+  columns?: number;
+  /** Additional classes */
+  className?: string;
+}
+
+/**
+ * Consistent loading skeleton for data-fetching pages.
+ * Renders a grid of skeleton placeholders.
+ */
+export function LoadingSkeleton({
+  count = 4,
+  height = "h-28",
+  columns = 1,
+  className,
+}: LoadingSkeletonProps) {
+  return (
+    <div
+      className={cn(
+        "grid gap-3",
+        columns > 1 ? `grid-cols-1 md:grid-cols-${columns}` : "grid-cols-1",
+        className,
+      )}
+    >
+      {Array.from({ length: count }, (_, i) => (
+        <Skeleton key={i} className={cn(height, "rounded-xl")} />
+      ))}
+    </div>
+  );
+}

services/frontend/src/components/shared/stat-card.tsx

@@ -0,0 +1,55 @@
+import type { LucideIcon } from "lucide-react";
+
+import { Card, CardContent } from "@/components/ui/card";
+import { formatNumber } from "@/lib/format";
+import { cn } from "@/lib/utils";
+
+interface StatCardProps {
+  label: string;
+  value: number;
+  icon: LucideIcon;
+  variant?: "default" | "danger" | "success";
+}
+
+/**
+ * Metric card used across dashboard and landing pages.
+ */
+export function StatCard({
+  label,
+  value,
+  icon: Icon,
+  variant = "default",
+}: StatCardProps) {
+  return (
+    <Card>
+      <CardContent className="p-4">
+        <div className="flex items-start justify-between">
+          <div className="space-y-1.5">
+            <p className="text-xs text-muted-foreground">{label}</p>
+            <p
+              className={cn(
+                "text-2xl font-bold tabular-nums tracking-tight",
+                variant === "danger" && "text-destructive",
+                variant === "success" && "text-green-500",
+              )}
+            >
+              {formatNumber(value)}
+            </p>
+          </div>
+          <div
+            className={cn(
+              "flex size-9 shrink-0 items-center justify-center rounded-lg",
+              variant === "danger"
+                ? "bg-destructive/10 text-destructive"
+                : variant === "success"
+                  ? "bg-green-500/10 text-green-500"
+                  : "bg-primary/10 text-primary",
+            )}
+          >
+            <Icon className="size-4" />
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}

services/frontend/src/hooks/index.ts

@@ -0,0 +1,22 @@
+export { useAsync } from "./use-async";
+export { useConfig } from "./use-config";
+export {
+  useChannelDetail,
+  useChannels,
+  useStats,
+  useUserDetail,
+  useUsers,
+} from "./use-dashboard";
+export { useGuilds } from "./use-guilds";
+export { useMediaState, useMediaWsSubscription } from "./use-media";
+export {
+  useImages,
+  useMessageDetail,
+  useMessages,
+  useMessageWsSubscription,
+  useReview,
+  useSearch,
+  useTextChannels,
+} from "./use-messages";
+export { useRecordings, useRecordingsWsSubscription } from "./use-recordings";
+export { useSpeakers, useVoiceChannels, useVoiceStatus } from "./use-voice";

services/frontend/src/hooks/use-async.ts

@@ -0,0 +1,58 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+interface UseAsyncState<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+}
+
+type UseAsyncReturn<T> = UseAsyncState<T> & { refetch: () => void };
+
+/**
+ * Generic async data-fetching hook.
+ *
+ * - Cancels requests on unmount
+ * - Provides loading / error / data states
+ * - Returns a refetch trigger
+ */
+export function useAsync<T>(
+  fetcher: () => Promise<T>,
+  deps: unknown[] = [],
+): UseAsyncReturn<T> {
+  const [state, setState] = useState<UseAsyncState<T>>({
+    data: null,
+    loading: true,
+    error: null,
+  });
+  const cancelledRef = useRef(false);
+
+  const execute = useCallback(() => {
+    cancelledRef.current = false;
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    fetcher()
+      .then((data) => {
+        if (!cancelledRef.current) {
+          setState({ data, loading: false, error: null });
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelledRef.current) {
+          setState({
+            data: null,
+            loading: false,
+            error: err instanceof Error ? err.message : "An error occurred",
+          });
+        }
+      });
+    // biome-ignore lint/correctness/useExhaustiveDependencies: deps is intentionally dynamic
+  }, deps);
+
+  useEffect(() => {
+    execute();
+    return () => {
+      cancelledRef.current = true;
+    };
+  }, [execute]);
+
+  return { ...state, refetch: execute };
+}

services/frontend/src/hooks/use-config.ts

@@ -0,0 +1,21 @@
+import { configApi } from "@/lib/api";
+import type { AppConfig } from "@/lib/types";
+import { useAsync } from "./use-async";
+
+interface UseConfigReturn {
+  config: AppConfig | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+/**
+ * Fetch the app configuration from the backend.
+ */
+export function useConfig(): UseConfigReturn {
+  const { data, loading, error, refetch } = useAsync<AppConfig>(
+    () => configApi.get(),
+    [],
+  );
+  return { config: data, loading, error, refetch };
+}

services/frontend/src/hooks/use-dashboard.ts

@@ -0,0 +1,169 @@
+import { useCallback, useState } from "react";
+
+import { dashboardApi } from "@/lib/api";
+import type {
+  DashboardChannel,
+  DashboardChannelDetail,
+  DashboardStats,
+  DashboardUser,
+  DashboardUserDetail,
+} from "@/lib/types";
+
+// ── Stats ───────────────────────────────────────
+
+interface UseStatsReturn {
+  stats: DashboardStats | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+export function useStats(): UseStatsReturn {
+  const [stats, setStats] = useState<DashboardStats | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetch = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await dashboardApi.getStats();
+      setStats(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to load stats");
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { stats, loading, error, refetch: fetch };
+}
+
+// ── Users ───────────────────────────────────────
+
+interface UseUsersReturn {
+  users: DashboardUser[];
+  loading: boolean;
+  search: string;
+  setSearch: (q: string) => void;
+  refetch: () => void;
+}
+
+export function useUsers(): UseUsersReturn {
+  const [users, setUsers] = useState<DashboardUser[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [search, setSearch] = useState("");
+
+  const fetch = useCallback(async (q?: string) => {
+    setLoading(true);
+    try {
+      const result = await dashboardApi.listUsers(20, undefined, q);
+      setUsers(result.data);
+    } catch {
+      // silently fail
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const fetchWithSearch = useCallback(() => {
+    fetch(search || undefined);
+  }, [fetch, search]);
+
+  return {
+    users,
+    loading,
+    search,
+    setSearch,
+    refetch: fetchWithSearch,
+  };
+}
+
+// ── Channels ────────────────────────────────────
+
+interface UseChannelsReturn {
+  channels: DashboardChannel[];
+  loading: boolean;
+  search: string;
+  setSearch: (q: string) => void;
+  refetch: () => void;
+}
+
+export function useChannels(guildId: string): UseChannelsReturn {
+  const [channels, setChannels] = useState<DashboardChannel[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [search, setSearch] = useState("");
+
+  const fetch = useCallback(
+    async (q?: string) => {
+      setLoading(true);
+      try {
+        const result = await dashboardApi.listChannels(
+          20,
+          q,
+          guildId || undefined,
+        );
+        setChannels(result.data);
+      } catch {
+        // silently fail
+      } finally {
+        setLoading(false);
+      }
+    },
+    [guildId],
+  );
+
+  const fetchWithSearch = useCallback(() => {
+    fetch(search || undefined);
+  }, [fetch, search]);
+
+  return {
+    channels,
+    loading,
+    search,
+    setSearch,
+    refetch: fetchWithSearch,
+  };
+}
+
+// ── User Detail ─────────────────────────────────
+
+export function useUserDetail() {
+  const [user, setUser] = useState<DashboardUserDetail | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetch = useCallback(async (userId: string) => {
+    setLoading(true);
+    try {
+      const detail = await dashboardApi.getUserDetail(userId);
+      setUser(detail);
+    } catch {
+      // ignore
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { user, loading, fetch };
+}
+
+// ── Channel Detail ──────────────────────────────
+
+export function useChannelDetail() {
+  const [channel, setChannel] = useState<DashboardChannelDetail | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetch = useCallback(async (channelId: string) => {
+    setLoading(true);
+    try {
+      const detail = await dashboardApi.getChannelDetail(channelId);
+      setChannel(detail);
+    } catch {
+      // ignore
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { channel, loading, fetch };
+}

services/frontend/src/hooks/use-guilds.ts

@@ -0,0 +1,38 @@
+import { useCallback, useEffect, useState } from "react";
+
+import { voiceApi } from "@/lib/api";
+import type { Guild } from "@/lib/types";
+
+interface UseGuildsReturn {
+  guilds: Guild[];
+  loading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+/**
+ * Fetch the list of available Discord guilds.
+ */
+export function useGuilds(): UseGuildsReturn {
+  const [guilds, setGuilds] = useState<Guild[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchGuilds = useCallback(() => {
+    setLoading(true);
+    setError(null);
+    voiceApi
+      .getGuilds()
+      .then(setGuilds)
+      .catch((err: unknown) =>
+        setError(err instanceof Error ? err.message : "Failed to load guilds"),
+      )
+      .finally(() => setLoading(false));
+  }, []);
+
+  useEffect(() => {
+    fetchGuilds();
+  }, [fetchGuilds]);
+
+  return { guilds, loading, error, refetch: fetchGuilds };
+}

services/frontend/src/hooks/use-media.ts

@@ -0,0 +1,80 @@
+import { useCallback, useState } from "react";
+
+import { voiceApi } from "@/lib/api";
+import type { MediaState } from "@/lib/types";
+import type { WsEventType } from "@/lib/ws/types";
+
+type WsHook = {
+  on: <E extends WsEventType>(
+    eventType: E,
+    handler: (data: unknown) => void,
+  ) => () => void;
+};
+
+interface UseMediaStateReturn {
+  mediaState: MediaState | null;
+  refresh: () => void;
+  queue: (url: string) => void;
+  skip: () => void;
+  stop: () => void;
+  setVolume: (value: number | readonly number[]) => void;
+}
+
+export function useMediaState(): UseMediaStateReturn {
+  const [mediaState, setMediaState] = useState<MediaState | null>(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      const state = await voiceApi.getMediaStatus();
+      setMediaState(state);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  const queue = useCallback(async (url: string) => {
+    try {
+      const state = await voiceApi.mediaQueue(url, "music");
+      setMediaState(state);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  const skip = useCallback(async () => {
+    try {
+      const state = await voiceApi.mediaSkip();
+      setMediaState(state);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  const stop = useCallback(async () => {
+    try {
+      const state = await voiceApi.mediaStop();
+      setMediaState(state);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  const setVolume = useCallback(async (value: number | readonly number[]) => {
+    const vol = Array.isArray(value) ? value[0] : value;
+    try {
+      const state = await voiceApi.mediaVolume(vol);
+      setMediaState(state);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  return { mediaState, refresh, queue, skip, stop, setVolume };
+}
+
+export function useMediaWsSubscription(
+  ws: WsHook,
+  onState: (state: MediaState) => void,
+) {
+  return ws.on("media_state", (data) => onState(data as MediaState));
+}

services/frontend/src/hooks/use-messages.ts

@@ -0,0 +1,265 @@
+import { useCallback, useEffect, useState } from "react";
+
+import { messagesApi, voiceApi } from "@/lib/api";
+import type { AttachmentRecord, Channel, MessageRecord } from "@/lib/types";
+import type { WsEventType } from "@/lib/ws/types";
+
+type WsHook = {
+  on: <E extends WsEventType>(
+    eventType: E,
+    handler: (data: unknown) => void,
+  ) => () => void;
+};
+
+// ── Messages list ───────────────────────────────
+
+interface UseMessagesReturn {
+  messages: MessageRecord[];
+  loading: boolean;
+  loadingMore: boolean;
+  error: string | null;
+  hasMore: boolean;
+  refetch: () => void;
+  loadMore: () => void;
+  prepend: (msg: MessageRecord) => void;
+  update: (msg: MessageRecord) => void;
+  remove: (id: string) => void;
+}
+
+export function useMessages(
+  guildId: string,
+  channelId?: string,
+): UseMessagesReturn {
+  const [messages, setMessages] = useState<MessageRecord[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [hasMore, setHasMore] = useState(true);
+
+  const fetch = useCallback(async () => {
+    if (!guildId) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await messagesApi.list(
+        guildId,
+        50,
+        channelId || undefined,
+      );
+      setMessages(result.data);
+      setCursor(result.nextCursor);
+      setHasMore(result.nextCursor !== null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to load messages");
+    } finally {
+      setLoading(false);
+    }
+  }, [guildId, channelId]);
+
+  const loadMore = useCallback(async () => {
+    if (!cursor || loadingMore) return;
+    setLoadingMore(true);
+    try {
+      const result = await messagesApi.list(
+        guildId,
+        50,
+        channelId || undefined,
+        cursor,
+      );
+      setMessages((prev) => [...prev, ...result.data]);
+      setCursor(result.nextCursor);
+      setHasMore(result.nextCursor !== null);
+    } catch {
+      // ignore
+    } finally {
+      setLoadingMore(false);
+    }
+  }, [cursor, loadingMore, guildId, channelId]);
+
+  const prepend = useCallback((msg: MessageRecord) => {
+    setMessages((prev) => [msg, ...prev]);
+  }, []);
+
+  const update = useCallback((msg: MessageRecord) => {
+    setMessages((prev) => prev.map((m) => (m.id === msg.id ? msg : m)));
+  }, []);
+
+  const remove = useCallback((id: string) => {
+    setMessages((prev) => prev.filter((m) => m.id !== id));
+  }, []);
+
+  return {
+    messages,
+    loading,
+    loadingMore,
+    error,
+    hasMore,
+    refetch: fetch,
+    loadMore,
+    prepend,
+    update,
+    remove,
+  };
+}
+
+// ── Channels list ───────────────────────────────
+
+interface UseTextChannelsReturn {
+  channels: Channel[];
+  loading: boolean;
+}
+
+export function useTextChannels(guildId: string): UseTextChannelsReturn {
+  const [channels, setChannels] = useState<Channel[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    if (!guildId) return;
+    voiceApi
+      .getTextChannels(guildId)
+      .then(setChannels)
+      .catch(() => {})
+      .finally(() => setLoading(false));
+  }, [guildId]);
+
+  return { channels, loading };
+}
+
+// ── Search ──────────────────────────────────────
+
+interface UseSearchReturn {
+  results: MessageRecord[] | null;
+  searching: boolean;
+  search: (query: string) => void;
+}
+
+export function useSearch(): UseSearchReturn {
+  const [results, setResults] = useState<MessageRecord[] | null>(null);
+  const [searching, setSearching] = useState(false);
+
+  const search = useCallback(async (query: string) => {
+    if (!query.trim()) {
+      setResults(null);
+      return;
+    }
+    setSearching(true);
+    try {
+      const result = await messagesApi.search(query, 50);
+      setResults(result.results);
+    } catch {
+      setResults([]);
+    } finally {
+      setSearching(false);
+    }
+  }, []);
+
+  return { results, searching, search };
+}
+
+// ── Images ──────────────────────────────────────
+
+export function useImages(guildId: string) {
+  const [images, setImages] = useState<MessageRecord[]>([]);
+
+  const fetch = useCallback(async () => {
+    if (!guildId) return;
+    try {
+      const result = await messagesApi.getImages(guildId, 50);
+      setImages(result.data);
+    } catch {
+      // silently fail
+    }
+  }, [guildId]);
+
+  return { images, refetch: fetch };
+}
+
+// ── Review ──────────────────────────────────────
+
+export function useReview(channelId?: string) {
+  const [reviews, setReviews] = useState<MessageRecord[]>([]);
+
+  const fetch = useCallback(async () => {
+    try {
+      const result = await messagesApi.getReview(50, channelId || undefined);
+      setReviews(result.results);
+    } catch {
+      // silently fail
+    }
+  }, [channelId]);
+
+  return { reviews, refetch: fetch };
+}
+
+// ── Detail ──────────────────────────────────────
+
+interface UseMessageDetailReturn {
+  message: MessageRecord | null;
+  attachments: AttachmentRecord[];
+  loading: boolean;
+  open: (id: string) => void;
+  close: () => void;
+}
+
+export function useMessageDetail(): UseMessageDetailReturn {
+  const [message, setMessage] = useState<MessageRecord | null>(null);
+  const [attachments, setAttachments] = useState<AttachmentRecord[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  const open = useCallback(async (id: string) => {
+    setLoading(true);
+    setAttachments([]);
+    try {
+      const detail = await messagesApi.getDetail(id);
+      setMessage(detail);
+      if (detail.channel_id && id) {
+        messagesApi
+          .getAttachments(detail.channel_id, 10)
+          .then((res) => setAttachments(res.data))
+          .catch(() => {});
+      }
+    } catch {
+      setMessage(null);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const close = useCallback(() => setMessage(null), []);
+
+  return { message, attachments, loading, open, close };
+}
+
+// ── WS Subscription helper ──────────────────────
+
+export function useMessageWsSubscription(
+  ws: WsHook | undefined,
+  guildId: string,
+  onCreated: (msg: MessageRecord) => void,
+  onUpdated: (msg: MessageRecord) => void,
+  onDeleted: (id: string) => void,
+  onAnalyzed: (msg: MessageRecord) => void,
+) {
+  useEffect(() => {
+    if (!ws || !guildId) return;
+    const unsub1 = ws.on("message_created", (data) =>
+      onCreated(data as MessageRecord),
+    );
+    const unsub2 = ws.on("message_updated", (data) =>
+      onUpdated(data as MessageRecord),
+    );
+    const unsub3 = ws.on("message_deleted", (data) =>
+      onDeleted(data as unknown as string),
+    );
+    const unsub4 = ws.on("message_analyzed", (data) =>
+      onAnalyzed(data as MessageRecord),
+    );
+    return () => {
+      unsub1();
+      unsub2();
+      unsub3();
+      unsub4();
+    };
+  }, [ws, guildId, onCreated, onUpdated, onDeleted, onAnalyzed]);
+}

services/frontend/src/hooks/use-recordings.ts

@@ -0,0 +1,61 @@
+import { useCallback, useState } from "react";
+
+import { recordingsApi } from "@/lib/api";
+import type { VoiceRecording } from "@/lib/types";
+import type { WsEventType } from "@/lib/ws/types";
+
+type WsHook = {
+  on: <E extends WsEventType>(
+    eventType: E,
+    handler: (data: unknown) => void,
+  ) => () => void;
+};
+
+interface UseRecordingsReturn {
+  recordings: VoiceRecording[];
+  loading: boolean;
+  refresh: () => void;
+  remove: (id: string) => void;
+  prepend: (rec: VoiceRecording) => void;
+}
+
+export function useRecordings(): UseRecordingsReturn {
+  const [recordings, setRecordings] = useState<VoiceRecording[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    try {
+      const result = await recordingsApi.list(50);
+      setRecordings(result.items);
+    } catch {
+      // ignore
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const remove = useCallback(async (id: string) => {
+    try {
+      await recordingsApi.delete(id);
+      setRecordings((prev) => prev.filter((r) => r.id !== id));
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  const prepend = useCallback((rec: VoiceRecording) => {
+    setRecordings((prev) => [rec, ...prev]);
+  }, []);
+
+  return { recordings, loading, refresh, remove, prepend };
+}
+
+export function useRecordingsWsSubscription(
+  ws: WsHook,
+  onUploaded: (rec: VoiceRecording) => void,
+) {
+  return ws.on("voice_recording_uploaded", (data) =>
+    onUploaded(data as VoiceRecording),
+  );
+}

services/frontend/src/hooks/use-voice.ts

@@ -0,0 +1,89 @@
+import { useCallback, useState } from "react";
+
+import { voiceApi } from "@/lib/api";
+import type { ActiveSpeaker, VoiceStatus } from "@/lib/types";
+import type { WsEventType } from "@/lib/ws/types";
+
+type WsHook = {
+  on: <E extends WsEventType>(
+    eventType: E,
+    handler: (data: unknown) => void,
+  ) => () => void;
+};
+
+interface UseVoiceStatusReturn {
+  voiceStatus: VoiceStatus | null;
+  refresh: () => void;
+}
+
+export function useVoiceStatus(): UseVoiceStatusReturn {
+  const [voiceStatus, setVoiceStatus] = useState<VoiceStatus | null>(null);
+
+  const refresh = useCallback(async () => {
+    try {
+      const status = await voiceApi.getStatus();
+      setVoiceStatus(status);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  return { voiceStatus, refresh };
+}
+
+interface UseVoiceChannelsReturn {
+  channels: Array<{ id: string; name: string }>;
+  loading: boolean;
+  fetch: (guildId: string) => void;
+}
+
+export function useVoiceChannels(): UseVoiceChannelsReturn {
+  const [channels, setChannels] = useState<Array<{ id: string; name: string }>>(
+    [],
+  );
+  const [loading, setLoading] = useState(false);
+
+  const fetch = useCallback(async (guildId: string) => {
+    setLoading(true);
+    try {
+      const ch = await voiceApi.getVoiceChannels(guildId);
+      setChannels(ch);
+    } catch {
+      setChannels([]);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { channels, loading, fetch };
+}
+
+interface UseSpeakersReturn {
+  speakers: ActiveSpeaker[];
+  subscribe: (ws: WsHook) => () => void;
+}
+
+export function useSpeakers(): UseSpeakersReturn {
+  const [speakers, setSpeakers] = useState<ActiveSpeaker[]>([]);
+
+  const subscribe = useCallback((ws: WsHook) => {
+    const unsub = ws.on("voice_active_user", (data) => {
+      const speaker = data as ActiveSpeaker;
+      setSpeakers((prev) => {
+        const idx = prev.findIndex((s) => s.userId === speaker.userId);
+        if (idx >= 0) {
+          const next = [...prev];
+          next[idx] = speaker;
+          return next;
+        }
+        return [...prev, speaker];
+      });
+    });
+    return () => {
+      unsub();
+      setSpeakers([]);
+    };
+  }, []);
+
+  return { speakers, subscribe };
+}

services/frontend/src/lib/api/chatbot.ts

@@ -1,9 +1,9 @@
-import type { ChatHistoryMessage, MascotChatResponse } from "@/lib/types";
+import type { ChatbotResponse, ChatHistoryMessage } from "@/lib/types";
 import { api } from "./client";
 
-export const mascotApi = {
+export const chatbotApi = {
   send: (message: string) =>
-    api.post<MascotChatResponse>("/api/mascot/chat", { message }),
+    api.post<ChatbotResponse>("/api/mascot/chat", { message }),
 
   getHistory: () => api.get<ChatHistoryMessage[]>("/api/mascot/chat/history"),
 

services/frontend/src/lib/api/index.ts

@@ -1,7 +1,7 @@
+export { chatbotApi } from "./chatbot";
 export { ApiError, api, apiRequest } from "./client";
 export { configApi } from "./config";
 export { dashboardApi } from "./dashboard";
-export { mascotApi } from "./mascot";
 export { messagesApi } from "./messages";
 export { recordingsApi } from "./recordings";
 export { uiStateApi } from "./ui-state";

services/frontend/src/lib/types/ui.ts

@@ -11,7 +11,7 @@ export interface UiState {
   is_streaming?: boolean | null;
 }
 
-export interface MascotChatResponse {
+export interface ChatbotResponse {
   response: string;
   timestamp: string;
 }