Source & Topic UI Management
Relevant source files
The following files were used as context for generating this wiki page:
- apps/web/src/features/sources/components/SourceContent.tsx
- apps/web/src/features/sources/components/TopicSuggestionsSection.tsx
- apps/web/src/routes/topics/index.tsx
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt
- apps/web/src/routes/sources/$sourceId.tsx
- apps/web/src/lib/api/types.ts
- apps/web/src/features/sources/components/SourceHeader.tsx
Introduction
Source & Topic UI Management constitutes the core interface and application logic for organizing information within Briefy. It encompasses the lifecycle of "Sources" (imported content such as articles or videos) and "Topics" (thematic containers used to group and synthesize insights). The system provides users with tools to import, curate, and link these entities, often supported by AI-driven suggestions.
The primary goal of this module is to transition users from passive content consumption to structured knowledge management. It handles the display of extracted content, the generation of AI topic suggestions, and the manual organization of the knowledge graph.
Knowledge Graph Architecture
The system operates on a Knowledge Graph model where Sources are linked to Topics via a TopicLink. This relationship allows for multi-dimensional organization where one source can belong to multiple topics, and one topic can aggregate many sources.
Core Entities and Statuses
| Entity | Primary Statuses | Description |
|---|---|---|
| Source | submitted, extracting, active, failed, archived | Represents an external piece of content (URL or manual text). |
| Topic | suggested, active, archived | Represents a thematic category created by the user or suggested by AI. |
| TopicLink | suggested, active | The join entity connecting a Source to a Topic, including AI confidence scores. |
Sources: apps/web/src/lib/api/types.ts:47-51, apps/web/src/lib/api/types.ts:114-118, apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:15-18
Relationship Flow
The following diagram illustrates how sources move through the system and are associated with topics.
Source Management
Source management focuses on the ingestion and display of content. The UI handles various states of the extraction pipeline, including specialized handling for platforms like YouTube.
Content Display and Formatting
The SourceContentSection handles the rendering of extracted text or video. If a source is from YouTube, it embeds an iframe for the video and displays the transcript.
- Formatting States: If AI formatting is enabled, the UI monitors
formattingState. If it ispending, a notice is shown to the user. If it fails, aFormattingFailedNoticeallows for a retry. - Manual Overrides: Users can manually provide or update source content via
provideSourceContent, which sets the extraction provider tomanual.
Sources: apps/web/src/features/sources/components/SourceContent.tsx:24-45, apps/web/src/routes/sources/$sourceId.tsx:128-140, apps/web/src/lib/api/types.ts:25-27
Source Header Actions
The SourceHeader component provides the primary action suite for a specific source:
- Briefing Generation: Triggers the AI subagent runner to synthesize information.
- Narration: Requests audio generation for the source content.
- Lifecycle: Allows for archiving (deleting) or restoring sources.
Sources: apps/web/src/features/sources/components/SourceHeader.tsx:64-95
Topic Management and AI Suggestions
Topic management involves both user-defined organization and AI-assisted discovery.
Topic Suggestion Pipeline
The TopicSuggestionService uses an AI adapter to analyze source content and suggest up to 5 topics. It attempts to match content against existing active topics before proposing newTopics.
Suggestion Interaction (Confirm/Discard)
In the UI, suggested topics are displayed in a TopicSuggestionsSection. Users can:
- Select/Deselect: Toggle specific suggestions.
- Apply: "Keep" selected topics (transitioning
TopicLinktoACTIVE) and "Discard" the rest (deleting the link and potentially orphan suggested topics). - Manual Addition: Add a manual suggestion to a source before final confirmation.
Sources: apps/web/src/features/sources/components/TopicSuggestionsSection.tsx:40-100, apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:80-115
Topic Discovery and Browsing
The main Topics page (/topics/index.tsx) provides a dual view:
- Active Topics: Topics the user has confirmed or created.
- Suggested Topics: A discovery queue of topics extracted by the system but not yet finalized.
Sources: apps/web/src/routes/topics/index.tsx:41-45
API Endpoints for Topic Management
| Endpoint | Method | Description |
|---|---|---|
/api/topics | POST | Creates a new topic and optionally links active sources. |
/api/topics | GET | Lists topics filtered by status (active, suggested) and query. |
/api/sources/{id}/topics/suggestions | GET | Returns pending AI suggestions for a specific source. |
/api/sources/{id}/topics/apply | POST | Confirms specific suggested links and dismisses others. |
/api/sources/{id}/topics/manual | POST | Adds a user-defined suggestion to a specific source. |
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:145-210
Conclusion
The Source & Topic UI Management system bridges the gap between raw data ingestion and structured knowledge. By utilizing an AI-driven suggestion service alongside robust manual controls, it allows users to build a personalized knowledge graph. The system ensures data integrity through transactional status transitions and provides a responsive UI that handles the complexities of content extraction and AI synthesis.