Knowledge Graph & Topics
Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/topic/Topic.kt
- 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/api/src/main/kotlin/com/briefy/api/api/TopicController.kt
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicDto.kt
- apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/source/Source.kt
- apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql
The Knowledge Graph system in Briefy serves as the semantic backbone for organizing and connecting disparate information sources. It allows users to categorize content into high-level themes called Topics, which are linked to specific content units (Sources) via a many-to-many relationship managed by the system and AI-driven suggestions.
This module facilitates the transition from scattered reading to structured understanding by identifying recurring themes across sources. It employs a combination of automated AI extraction and manual user curation to maintain a relevant and evolving graph of knowledge.
Architecture and Core Entities
The Knowledge Graph is built upon two primary domain entities: Topic and TopicLink. These entities define how themes are created, normalized, and associated with content.
The Topic Entity
A Topic represents a semantic category. To prevent duplication, topics utilize a normalized name (lowercase, trimmed, with collapsed whitespace). Topics have a lifecycle that distinguishes between AI-suggested themes and user-validated categories.
Sources: apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/topic/Topic.kt:47-50, apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/topic/Topic.kt:70-74
The TopicLink Entity
A TopicLink acts as the edge in the knowledge graph, connecting a Topic to a Source. These links track the confidence level of AI suggestions and the method by which they were assigned (e.g., SYSTEM_SUGGESTED or USER_CREATED).
Sources: apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql:43-53
The diagram above illustrates the relationship between sources and topics through the link entity.
Topic Lifecycle and States
The system manages both Topics and TopicLinks through specific states to handle the workflow from automated discovery to manual approval.
Topic States
| State | Description |
|---|---|
SUGGESTED | Created by the AI engine but not yet validated by the user. |
ACTIVE | Validated by a user or manually created. Appears in primary filters. |
ARCHIVED | Hidden from standard views but preserved for historical context. |
Sources: apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/topic/Topic.kt:22-24, apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql:6-9
TopicLink States
Links between sources and topics follow a similar lifecycle:
- SUGGESTED: A potential connection identified by AI.
- ACTIVE: A confirmed connection.
- REMOVED: A dismissed suggestion.
Sources: apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql:43-53
AI-Driven Topic Extraction
The TopicSuggestionService manages the automated extraction of topics from source content using Large Language Models (LLMs).
Extraction Process
- Preparation: The service loads the source content and the user's existing active topics to provide context to the AI, ensuring the model prefers reusing existing themes over creating duplicates.
- AI Invocation: An LLM is prompted to return a JSON list of candidates, including the
existingTopicId(if matched) or a new name, along with a confidence score. - Resolution: The service resolves candidates by either linking to existing topics or creating new ones in the
SUGGESTEDstate. - Persistence: New
TopicLinkrecords are created with aSUGGESTEDstatus.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt:42-101
This sequence shows the flow from source identification to the creation of suggested topic links.
Topic Management and API
The TopicService and TopicController provide the interface for users to interact with the knowledge graph.
Key Operations
- Applying Suggestions: Users can "apply" suggestions by providing a list of
keepTopicLinkIds. Kept links becomeACTIVE, while others are marked asREMOVED. OrphanedSUGGESTEDtopics (those with no remaining links) are automatically deleted. - Manual Creation: Users can create topics and link them to multiple active sources in a single transaction.
- Search and Filtering: Topics can be searched by name (case-insensitive) and filtered by status.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:85-117, apps/api/src/main/kotlin/com/briefy/api/api/TopicController.kt:27-37
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/topics | Creates a new active topic and links provided sources. |
GET | /api/topics | Lists topics for the user, filtered by status or search query. |
GET | /api/topics/{id} | Returns detailed topic information including all linked sources. |
POST | /api/sources/{id}/topics/apply | Confirms or dismisses AI-generated suggestions for a source. |
Sources: apps/api/src/main/kotlin/com/briefy/api/api/TopicController.kt:27-55, apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:47-60
Data Integrity and Normalization
To maintain a clean knowledge graph, the system enforces several constraints:
- Normalization: All topic names are normalized before comparison using
Topic.normalizeName(raw). This collapses spaces and converts to lowercase. - Unique Constraints: A unique index exists on
(user_id, name_normalized)to prevent duplicate topics per user. - Live Edge Constraint: A unique index ensures only one "live" (Suggested or Active) link exists between a specific topic and source.
Sources: apps/api/src/main/kotlin/com/briefy/api/domain/knowledgegraph/topic/Topic.kt:70-74, apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql:35-36, apps/api/src/main/resources/db/migration/V20260211104500__topics_slice2.sql:102-105
Conclusion
The Knowledge Graph & Topics system provides a structured yet flexible way to navigate information within Briefy. By combining automated AI discovery with user-controlled validation, it ensures that the semantic connections between sources remain accurate, deduplicated, and personally relevant to the user's research needs.