Overview

The Services module wraps REST API endpoints (14 core services) and integrates them with React Query for automatic caching, deduplication, and optimistic updates. Each service method returns a React Query query/mutation definition, not raw promises. This ensures consistent data flow across all pages.

🔗 Service Modules

📂 Service Layer Architecture

src/services/
├── agent-service.ts      # Agent CRUD + DSL
├── chat-service.ts       # Chat & streaming
├── knowledge-service.ts  # File upload + KB mgmt
├── search-service.ts     # Vector search
├── user-service.ts       # User profile
├── admin-service.ts      # Admin API
└── api-client.ts         # Base HTTP client

🔄 React Query Integration

Pattern: Each service method returns a query/mutation definition that can be used with useQuery/useMutation.

Query Example

// In service: agent-service.ts
export const agentQueries = {
    list: (page: number) => ({
        queryKey: ['agents', page],
        queryFn: () => http.get('/api/v1/agents', { params: { page } })
    })
};

// In component: useAgentRequest hook
export const useAgentList = (page: number) => {
    const query = agentQueries.list(page);
    return useQuery({
        ...query,
        staleTime: 5 * 60 * 1000  // 5 min
    });
};

// Usage in component
const { data, isLoading, error } = useAgentList(1);

Mutation Example

// In service: agent-service.ts
export const agentMutations = {
    create: {
        mutationFn: (data: CreateAgentDTO) => 
            http.post('/api/v1/agents', data),
        onSuccess: () => {
            queryClient.invalidateQueries(['agents']);
        }
    }
};

// Usage in component
const mutation = useMutation(agentMutations.create);
mutation.mutate({ name: 'New Agent' });

⚡ Optimizations

• Query deduplication: If 2 components request same agent within stale time, only 1 fetch happens
• Stale-while-revalidate: Cache used immediately; refetch in background
• Optimistic updates: UI updates before server response (agent name change appears instantly)
• Refetch on focus: Auto-sync when user returns to tab (configurable)
• Refetch on mount: New component instances re-validate cache

Error Handling

Centralized error interceptor: HTTP client catches 4xx/5xx and formats errors.

// In api-client.ts
http.interceptors.response.use(
    res => res.data,
    error => {
        const msg = error.response?.data?.error || error.message;
        toast.error(msg);
        return Promise.reject(error);
    }
);

Authentication & Headers

All requests automatically include JWT token from localStorage.

// In api-client.ts
http.interceptors.request.use(config => {
    const token = localStorage.getItem('auth_token');
    if (token) {
        config.headers.Authorization = `Bearer ${token}`;
    }
    return config;
});

Proxy Routing (Dev Only)

Vite dev server proxies API calls to backend (see vite.config.ts):

proxy: {
    '/api/v1/agents': { target: 'http://localhost:9380' },
    '/api/v1/admin': { target: 'http://localhost:9383' },
    '/v1/kb': { target: 'http://localhost:9384' }
}

Common Issues & Solutions

Next Steps

• Explore Pages to see service usage in components
• Review Components for UI binding patterns
• Deep-dive: API Data Layer for advanced React Query patterns

Services Module/{{SUBMOD_NAME}}/ — {{SUBMOD_TITLE}}

Contents

Architecture

flowchart TD
  A["Component A"] --> B["Component B"]
  B --> C["Component C"]
  C --> D["Component D"]

Key Classes

Data Structures

Interactions

Configuration

Directory Map

submod_name/
├── file_a.ext                 ← Role: brief annotation
├── file_b.ext                 ← Role: brief annotation
├── file_c.ext                 ← Role: brief annotation
└── index.ext                  ← Role: entry point

📑 Annotated Code Walkthrough

The most important code in this sub-module, annotated with WHY each piece exists:

// Replace with actual code from the source
void key_function() {
    // ← WHY: Explain the purpose of this line
    // ← WHY: What constraint or requirement drives this?
}

⚠️ Edge Cases & Boundaries

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Typical Usage

// Replace with actual code example
void example() {
    // ...
}