Frontend API Client & Polling

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/lib/api/client.ts (Implicitly referenced via API usage)
• apps/web/src/lib/api/topics.ts
• apps/web/src/lib/api/sources.ts
• apps/web/src/lib/api/types.ts
• apps/web/src/routes/sources/$sourceId.tsx
• apps/web/src/features/sources/useSourceData.ts (Implicitly referenced via UI logic)
• AGENT_NOTES.md

The Frontend API Client and its associated polling mechanisms form the communication backbone between the React-based web application and the Kotlin/Spring Boot backend. This system handles asynchronous data fetching, error management, and real-time state synchronization for long-running processes like AI content extraction, formatting, and topic generation.

The architecture emphasizes a centralized client for standard HTTP methods (GET, POST, PATCH, DELETE) and specialized hooks that implement polling logic to ensure the UI remains consistent with the backend state during background processing tasks.

Core API Client Architecture

The frontend utilizes a centralized API client layer to interact with the backend services. This layer abstracts the standard fetch API, providing structured methods for common operations and automatic error handling using a custom ApiClientError class.

Unified Request Methods

The client provides several exported functions to handle different HTTP verbs. These functions are typed to ensure that response data matches the TypeScript interfaces defined in the shared types library.

Method	Function	Description
GET	apiGet<T>(path)	Fetches data from a specific endpoint. Used for listings and detail views.
POST	apiPost<T>(path, body)	Sends data to create resources or trigger actions (e.g., re-extraction).
PATCH	apiPatch<T>(path, body)	Updates specific fields of an existing resource.
DELETE	apiDelete(path)	Removes a resource or archives it based on backend semantics.

Sources: apps/web/src/lib/api/topics.ts:1-18, apps/web/src/lib/api/sources.ts:1-122, apps/web/src/lib/api/types.ts:1-320

Error Handling and Session Recovery

The API client is designed to perform single-flight session refreshes. If an eligible request returns a 401 Unauthorized error, the client attempts to refresh the user session and retries the original request once.

Sources: AGENT_NOTES.md (Non-Obvious Code Findings: 2026-03-07)

Specialized Resource Clients

The application organizes API interactions into module-specific files, such as sources.ts and topics.ts, which utilize the core client.

Source Management API

The Source API manages the lifecycle of content ingested into Briefy, including extraction and AI enrichment.

• Extraction & Retry Logic: Methods like retryExtraction, retryFormatting, and retryTopicExtraction allow the UI to manually trigger recovery for failed background jobs.
• Content Injection: provideSourceContent allows users to manually paste text if automated extraction fails.
• Batch Operations: archiveSourcesBatch facilitates bulk management of library items.

Sources: apps/web/src/lib/api/sources.ts:46-58, apps/web/src/lib/api/sources.ts:98-106

Topic Management API

The Topic API handles the organization of knowledge into themes.

• Listings: listTopics supports filtering by status (active or suggested) and search queries.
• Topic Creation: createTopic allows creating manual topics and linking existing sources immediately.

Sources: apps/web/src/lib/api/topics.ts:4-18

Polling and State Synchronization

Because content extraction and AI formatting are asynchronous background processes, the frontend implements polling to monitor state transitions.

Background Task Flow

When a source is created or updated, it moves through several states. The frontend monitors these via the Source interface properties.

The diagram above shows the lifecycle of a source from submission to an active state with AI-formatted content.
Sources: apps/web/src/lib/api/types.ts:50-70, apps/web/src/routes/sources/$sourceId.tsx:143-164

Polling Implementation in UI

The SourceDetailPage and the useSourceData hook coordinate to refresh source information when it is in a transient state (e.g., submitted, extracting, or when AI formatting/topic extraction is pending).

• Poll Trigger: The UI detects source.status !== 'active' or formattingState === 'pending'.
• Read-Time Repair: Polling acts as a recovery loop. If a backend event is lost, subsequent reads during polling can recover the state.
• Stuck Task Detection: The UI identifies "stuck" tasks if a process remains pending for more than 2 minutes, surfacing a manual retry option.

Sources: apps/web/src/routes/sources/$sourceId.tsx:156-164, AGENT_NOTES.md (Non-Obvious Code Findings: 2026-03-12)

Sequence Diagram: Status Polling

The following diagram illustrates how the frontend polls the API for source updates until a terminal state is reached.

Data Models for API Communication

Communication is strictly typed using shared DTO (Data Transfer Object) interfaces.

The Source Object

The Source object contains metadata regarding its processing status, which the frontend uses to determine UI rendering (e.g., showing a spinner vs. markdown content).

Field	Type	Description
status	Enum	submitted, extracting, active, failed, archived.
metadata.formattingState	Enum	pending, succeeded, failed, not_required.
topicExtractionState	Enum	Status of AI-suggested topics (pending, succeeded, failed).

Sources: apps/web/src/lib/api/types.ts:50-75

Summary

The Frontend API Client and Polling system provides a robust mechanism for handling the complex, asynchronous nature of AI-driven content processing. By centralizing request logic, implementing session recovery, and using targeted polling for transient states, the system ensures that users are presented with up-to-date information while long-running extraction and synthesis tasks complete in the background.