feat: implement frontend layout with master-detail structure (#126)

* feat: implement frontend layout with master-detail structure

Implement a complete frontend layout with sidebar navigation and routing:

- Add master-detail layout with 280px fixed sidebar and fluid content area
- Create sidebar with DBHub logo, Home link, and dynamic source list
- Implement React Router with routes for home and source detail views
- Add API client for fetching data sources from /api/sources endpoint
- Create HomeView with welcome content and getting started guide
- Create SourceDetailView showing connection status and configuration
- Add TypeScript types matching OpenAPI schema (DataSource, SSHTunnel)
- Include database type icons with color-coding for visual distinction
- Add loading states and error handling for async data fetching
- Display source metadata: host, port, database, user, SSH tunnel info
- Show configuration details: readonly mode, max rows, default source badge

Dependencies:
- react-router-dom ^7.9.5 for client-side routing
- @types/react-router-dom ^5.3.3 for TypeScript support

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address PR review comments for frontend layout

- Add input validation for sourceId to prevent path traversal attacks
- Add error state and retry UI for API failures
- Make sidebar width responsive across screen sizes (200px → 280px)
- Remove incompatible @types/react-router-dom package
- Add accessibility labels to main, aside, and nav elements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: replace full-screen error with toast notification

Replace the full-screen error UI with a bottom-right toast notification
for better user experience when API calls fail. The sidebar remains
visible and users can continue using the app while seeing the error.

- Create reusable Toast component with auto-dismiss
- Display error toast on fetchSources failure
- Remove blocking error screen

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address additional PR review comments

- Add URL encoding for sourceId to handle special characters
- Add safe JSON error parsing with content-type verification
- Make database field optional to match OpenAPI schema
- Add proper database type display names (SQL Server, PostgreSQL, etc.)
- Use explicit abbreviation mapping for database icons (PG, MY, MB, MS, SL)
- Remove redundant "configuration" word in HomeView text

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tianzhou

frontend/package.json

@@ -9,9 +9,10 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "clsx": "^2.1.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "clsx": "^2.1.1",
+    "react-router-dom": "^7.9.5",
     "tailwind-merge": "^2.5.5"
   },
   "devDependencies": {

frontend/public/logo-full-light.svg

@@ -1,13 +1,41 @@
+import { useEffect, useState } from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import Layout from './components/Layout';
+import HomeView from './components/views/HomeView';
+import SourceDetailView from './components/views/SourceDetailView';
+import Toast from './components/Toast';
+import { fetchSources } from './api/sources';
+import type { DataSource } from './types/datasource';
+
 function App() {
+  const [sources, setSources] = useState<DataSource[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetchSources()
+      .then((data) => {
+        setSources(data);
+        setIsLoading(false);
+      })
+      .catch((error) => {
+        console.error('Failed to fetch sources:', error);
+        setError(error instanceof Error ? error.message : 'Failed to load data sources');
+        setIsLoading(false);
+      });
+  }, []);
+
   return (
-    <div className="min-h-screen bg-background flex items-center justify-center">
-      <div className="container mx-auto px-4">
-        <h1 className="text-4xl font-bold text-center text-foreground">
-          DBHub - Universal Database MCP Server
-        </h1>
-      </div>
-    </div>
-  )
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Layout sources={sources} isLoading={isLoading} />}>
+          <Route index element={<HomeView />} />
+          <Route path="source/:sourceId" element={<SourceDetailView />} />
+        </Route>
+      </Routes>
+      {error && <Toast message={error} type="error" onClose={() => setError(null)} />}
+    </BrowserRouter>
+  );
 }
 
 export default App

frontend/src/App.tsx

@@ -0,0 +1,51 @@
+import type { DataSource } from '../types/datasource';
+
+const API_BASE = '/api';
+
+async function parseJsonResponse<T>(response: Response): Promise<T> {
+  const contentType = response.headers.get('content-type');
+  if (contentType && contentType.includes('application/json')) {
+    return response.json();
+  }
+  // Fallback to text if not JSON
+  const text = await response.text();
+  throw new Error(text || response.statusText);
+}
+
+export async function fetchSources(): Promise<DataSource[]> {
+  const response = await fetch(`${API_BASE}/sources`);
+
+  if (!response.ok) {
+    const errorMessage = await parseJsonResponse<{ error: string }>(response)
+      .then((data) => data.error)
+      .catch(() => response.statusText);
+    throw new Error(`Failed to fetch sources: ${errorMessage}`);
+  }
+
+  return response.json();
+}
+
+export async function fetchSource(sourceId: string): Promise<DataSource> {
+  // Validate sourceId to prevent path traversal attacks
+  if (!sourceId || sourceId.trim() === '') {
+    throw new Error('Source ID cannot be empty');
+  }
+  if (sourceId.includes('/') || sourceId.includes('..')) {
+    throw new Error('Invalid source ID format');
+  }
+
+  const response = await fetch(`${API_BASE}/sources/${encodeURIComponent(sourceId)}`);
+
+  if (!response.ok) {
+    const errorMessage = await parseJsonResponse<{ error: string }>(response)
+      .then((data) => data.error)
+      .catch(() => response.statusText);
+
+    if (response.status === 404) {
+      throw new Error(`Source not found: ${sourceId}`);
+    }
+    throw new Error(`Failed to fetch source: ${errorMessage}`);
+  }
+
+  return response.json();
+}

frontend/src/api/sources.ts

@@ -0,0 +1,19 @@
+import { Outlet } from 'react-router-dom';
+import Sidebar from './Sidebar/Sidebar';
+import type { DataSource } from '../types/datasource';
+
+interface LayoutProps {
+  sources: DataSource[];
+  isLoading: boolean;
+}
+
+export default function Layout({ sources, isLoading }: LayoutProps) {
+  return (
+    <div className="flex h-screen bg-background">
+      <Sidebar sources={sources} isLoading={isLoading} />
+      <main className="flex-1 overflow-auto" aria-label="Main content">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

frontend/src/components/Layout.tsx

@@ -0,0 +1,11 @@
+export default function Logo() {
+  return (
+    <div className="px-6 py-4 border-b border-border">
+      <img
+        src="/logo-full-light.svg"
+        alt="DBHub"
+        className="w-[200px] h-auto"
+      />
+    </div>
+  );
+}

frontend/src/components/Sidebar/Logo.tsx

@@ -0,0 +1,29 @@
+import { Link, useLocation } from 'react-router-dom';
+import { cn } from '../../lib/utils';
+
+interface NavItemProps {
+  to: string;
+  icon: React.ReactNode;
+  label: string;
+}
+
+export default function NavItem({ to, icon, label }: NavItemProps) {
+  const location = useLocation();
+  const isActive = location.pathname === to;
+
+  return (
+    <Link
+      to={to}
+      className={cn(
+        'flex items-center gap-3 px-6 py-3 text-sm font-medium transition-colors',
+        'hover:bg-accent hover:text-accent-foreground',
+        isActive && 'bg-accent text-accent-foreground'
+      )}
+    >
+      <span className="w-5 h-5 flex items-center justify-center">
+        {icon}
+      </span>
+      <span>{label}</span>
+    </Link>
+  );
+}

frontend/src/components/Sidebar/NavItem.tsx

@@ -0,0 +1,40 @@
+import Logo from './Logo';
+import NavItem from './NavItem';
+import SourceList from './SourceList';
+import type { DataSource } from '../../types/datasource';
+
+interface SidebarProps {
+  sources: DataSource[];
+  isLoading: boolean;
+}
+
+function HomeIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="20"
+      height="20"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+      <polyline points="9 22 9 12 15 12 15 22" />
+    </svg>
+  );
+}
+
+export default function Sidebar({ sources, isLoading }: SidebarProps) {
+  return (
+    <aside className="w-[200px] sm:w-[220px] md:w-[240px] lg:w-[280px] border-r border-border bg-card flex flex-col" aria-label="Navigation sidebar">
+      <Logo />
+      <nav className="flex-1 flex flex-col overflow-hidden" aria-label="Sidebar navigation">
+        <NavItem to="/" icon={<HomeIcon />} label="Home" />
+        <SourceList sources={sources} isLoading={isLoading} />
+      </nav>
+    </aside>
+  );
+}

frontend/src/components/Sidebar/Sidebar.tsx

@@ -0,0 +1,83 @@
+import { Link, useParams } from 'react-router-dom';
+import { cn } from '../../lib/utils';
+import type { DataSource, DatabaseType } from '../../types/datasource';
+
+interface SourceListProps {
+  sources: DataSource[];
+  isLoading: boolean;
+}
+
+const DB_COLORS: Record<DatabaseType, string> = {
+  postgres: '#336791',
+  mysql: '#4479A1',
+  mariadb: '#003545',
+  sqlserver: '#CC2927',
+  sqlite: '#003B57',
+};
+
+const DB_ABBREVIATIONS: Record<DatabaseType, string> = {
+  postgres: 'PG',
+  mysql: 'MY',
+  mariadb: 'MB',
+  sqlserver: 'MS',
+  sqlite: 'SL',
+};
+
+function DatabaseIcon({ type }: { type: DatabaseType }) {
+  return (
+    <div
+      className="w-5 h-5 rounded-full flex items-center justify-center text-white text-xs font-bold"
+      style={{ backgroundColor: DB_COLORS[type] }}
+    >
+      {DB_ABBREVIATIONS[type]}
+    </div>
+  );
+}
+
+export default function SourceList({ sources, isLoading }: SourceListProps) {
+  const { sourceId } = useParams<{ sourceId: string }>();
+
+  if (isLoading) {
+    return (
+      <div className="px-6 py-3 text-sm text-muted-foreground">
+        Loading sources...
+      </div>
+    );
+  }
+
+  if (sources.length === 0) {
+    return (
+      <div className="px-6 py-3 text-sm text-muted-foreground">
+        No sources configured
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex-1 overflow-auto">
+      <div className="px-6 py-2 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+        Data Sources
+      </div>
+      {sources.map((source) => {
+        const isActive = sourceId === source.id;
+        return (
+          <Link
+            key={source.id}
+            to={`/source/${source.id}`}
+            className={cn(
+              'flex items-center gap-3 px-6 py-3 text-sm font-medium transition-colors',
+              'hover:bg-accent hover:text-accent-foreground',
+              isActive && 'bg-accent text-accent-foreground'
+            )}
+          >
+            <DatabaseIcon type={source.type} />
+            <span className="flex-1 truncate">{source.id}</span>
+            {source.is_default && (
+              <span className="text-xs text-muted-foreground">default</span>
+            )}
+          </Link>
+        );
+      })}
+    </div>
+  );
+}

frontend/src/components/Sidebar/SourceList.tsx

@@ -0,0 +1,50 @@
+import { useEffect } from 'react';
+
+interface ToastProps {
+  message: string;
+  type?: 'error' | 'success' | 'info';
+  onClose: () => void;
+  duration?: number;
+}
+
+export default function Toast({ message, type = 'error', onClose, duration = 5000 }: ToastProps) {
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      onClose();
+    }, duration);
+
+    return () => clearTimeout(timer);
+  }, [duration, onClose]);
+
+  const bgColor = type === 'error' ? 'bg-red-600' : type === 'success' ? 'bg-green-600' : 'bg-blue-600';
+
+  return (
+    <div className="fixed bottom-4 right-4 z-50 animate-in slide-in-from-right">
+      <div className={`${bgColor} text-white px-6 py-4 rounded-lg shadow-lg max-w-md flex items-start gap-3`}>
+        <div className="flex-1">
+          <p className="text-sm font-medium">{message}</p>
+        </div>
+        <button
+          onClick={onClose}
+          className="text-white hover:text-gray-200 transition-colors"
+          aria-label="Close"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            width="20"
+            height="20"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <line x1="18" y1="6" x2="6" y2="18" />
+            <line x1="6" y1="6" x2="18" y2="18" />
+          </svg>
+        </button>
+      </div>
+    </div>
+  );
+}