frontend-layer

Frontend layer for the Gentleman-Skills project. Handles the React/TypeScript UI, including app shell, routing, authentication, generation streaming, and analytics dashboards. Owns the user-facing exp

SKILL.md

GitHub
<!-- L1:START -->

frontend-layer

Frontend layer for the Gentleman-Skills project. Handles the React/TypeScript UI, including app shell, routing, authentication, generation streaming, and analytics dashboards.

Trigger: When working in frontend/ directory — adding pages, debugging generation streams, or integrating auth flows in the web app.

<!-- L1:END --> <!-- L2:START -->

Quick Reference

Task Pattern
Stream generation useGenerationStream(generationId)
Auth check useAuth()
Start generation useStartGeneration(data)

Critical Patterns (Summary)

  • TypeScript React Components: Functional components with hooks; all UI components are pure functions returning JSX.
  • API Integration: fetchApi, streamGeneration, startGeneration from lib/api.ts; auth via AuthProvider/useAuth with VITE_API_URL env var.<!-- L2:END -->
<!-- L3:START -->

Critical Patterns (Detailed)

Pattern 1: TypeScript React Components

All UI components are functional components returning JSX. State is managed with React hooks (useState, useQuery, useMutation). Components are composed hierarchically: App wraps ErrorBoundary → Suspense → LoadingSpinner, with Layout and ProtectedRoute controlling routing and auth.

// Example: App.tsx entry point
import { HashRouter } from 'react-router-dom';
import { ErrorBoundary } from './components/ErrorBoundary';
import { LoadingSpinner } from './components/LoadingSpinner';
import { Layout } from './components/Layout';

function App() {
  return (
    <HashRouter>
      <ErrorBoundary>
        <Suspense fallback={<LoadingSpinner />}>
          <Layout>
            {/* route children rendered here */}
          </Layout>
        </Suspense>
      </ErrorBoundary>
    </HashRouter>
  );
}
export default App;

Pattern 2: Generation Streaming with useGenerationStream

Generation state is managed via useGenerationStream hook which tracks StreamStatus ('idle' | 'connecting' | 'running' | 'completed' | 'error' | 'cancelled'), StepItem list, and progress. Streaming uses SSE events from /api/generate endpoint. The hook provides events, status, steps, and progress for UI rendering.

// Example: useGenerationStream hook usage
const { status, steps, progress, events } = useGenerationStream(generationId);
if (status === 'running') {
  steps.map((step) => <Step key={step.label} {...step} />);
}

When to Use

  • Adding a new page or view in the web app
  • Debugging generation stream state or SSE event handling
  • Integrating or modifying authentication flow
  • Building analytics dashboards using useAnalyticsSummary, useAnalyticsUsage, useAnalyticsModels, useAnalyticsRepos

Commands

# Start development server
cd apps/web && npm run dev

# Build for production
cd apps/web && npm run build

# Run type check
cd apps/web && npm run typecheck

Anti-Patterns

Don't: Directly fetch API without error boundaries

Directly calling fetchApi without wrapping in ErrorBoundary or handling ApiError types will crash the UI on network errors or auth failures. Always use useStartGeneration/useCancelGeneration mutations or wrap calls in try/catch with ApiError handling, and ensure ErrorBoundary wraps the app root to catch rendering errors from child components.

// BAD: Unhandled fetchApi call
const data = await fetchApi('/api/generate', { method: 'POST' }); // crashes on error
<!-- L3:END -->