<!-- L1:START -->

add-api-endpoint

One sentence: Centralized API client for the web frontend with React Query integration.

Trigger: when fetching or mutating data from the backend API.

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

Quick Reference

Task	Pattern
Fetch generations	useGenerations()
Start generation	useStartGeneration()

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

Critical Patterns (Summary)

Error Handling with ApiError

Handle structured API errors using the ApiError class which provides status and code fields for precise error categorization.

import { ApiError } from '@/lib/api';

try {
  const data = await fetchApi<User>('/api/user');
} catch (error) {
  if (error instanceof ApiError) {
    // Handle specific status codes
    if (error.status === 401) {
      // Redirect to login
    }
  }
}

useStartGeneration Mutation

Use the useStartGeneration mutation to trigger generation workflows with automatic query invalidation.

import { useStartGeneration } from '@/lib/api';

const { mutate, isLoading } = useStartGeneration();
mutate({ mode: 'docs' });

When to Use

• Fetching generation data or provider lists from the backend
• Starting new generation workflows with proper mutation handling
• Canceling in-progress generation tasks
• Querying analytics and provider information

Commands

docker compose -f docker-compose.dev.yml up -d
python repoforge/cli.py dev

Anti-Patterns

Don't: Ignore ApiError status codes

Accessing error.message without checking error.status or error.code leads to brittle error handling that breaks on different error types.

// BAD - assumes all errors are generic
catch (error) {
  console.error(error.message); // Misses status/code context
}

<!-- L3:END -->