High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt
- apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt
- apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiBriefingPlanGenerator.kt
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt
- apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt
- apps/web/src/routes/index.tsx
- AGENT_NOTES.md
Briefy is designed as a knowledge synthesis system that transforms scattered information into structured understanding. The architecture supports a multi-persona AI research pipeline that collects evidence from internal and external sources to generate comprehensive briefings. The project is organized as a monorepo containing a Kotlin-based backend and a React-based frontend.
Sources: AGENTS.md:7-13, apps/web/src/routes/index.tsx:87-95
System Overview
The system follows a classic client-server model optimized for AI-heavy workloads. The frontend handles user interactions and content visualization, while the backend orchestrates data persistence, external content extraction, and complex AI generation workflows.
Project Structure
| Component | Technology Stack | Description |
|---|---|---|
| Backend (API) | Kotlin, Spring Boot, Flyway | Handles domain logic, AI orchestration, and PostgreSQL persistence. |
| Frontend (Web) | React, TypeScript, Vite | Provides the library interface, topic exploration, and briefing views. |
| Infrastructure | Docker Compose, PostgreSQL | Manages local services including the database and multi-service stack. |
The diagram above shows the high-level relationship between the monorepo components and external dependencies.
Sources: AGENTS.md:7-13, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:151-160
Backend Architecture
The backend (apps/api) implements a layered architecture to maintain clear boundaries between external interfaces and core business logic.
Layered Organization
The API package tree is divided into four primary domains:
- API Layer: Controllers handling HTTP requests (e.g.,
SourceController,TopicController). - Application Layer: Orchestrators and runners that coordinate complex flows like briefing generation and topic suggestion.
- Domain Layer: Core business entities (Sources, Topics, Briefings) and their repository interfaces.
- Infrastructure Layer: Adapters for external systems, including AI models (AiAdapter), database migrations (Flyway), and search tools.
Sources: AGENTS.md:14-16, apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:20-28
Knowledge Management Workflow
The system manages content through a lifecycle of ingestion and extraction:
- Source Extraction: External URLs are processed by providers like
JSOUPorFIRECRAWLto extract clean text. - Topic Suggestion: An AI extraction engine analyzes source content to suggest or link existing topics.
- Briefing Generation: A specialized pipeline that consumes sources to produce synthesized research.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt:113-130, apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt:130-135
AI Generation Pipeline
The core value proposition of Briefy is its advanced AI pipeline, which moves beyond simple summarization into multi-persona synthesis.
The Orchestration Flow
Briefing generation follows a rigid four-stage sequence:
The flow represents the transition from a single request to multi-persona research and final synthesis.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiBriefingPlanGenerator.kt:22-38, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:47-103
Component Responsibilities
1. Planning (AiBriefingPlanGenerator)
This component analyzes the "Enrichment Intent" (e.g., TRUTH_GROUNDING or DEEP_DIVE) and internal sources to create a plan consisting of 2 to 5 steps. Each step is assigned to a specific AI persona (e.g., "The Skeptic" or "Claim Auditor").
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiBriefingPlanGenerator.kt:101-115
2. Subagent Execution (AiSubagentExecutionRunner)
Each subagent executes its task in a "Tool Loop." The agent can decide to produce output directly if internal sources are sufficient or use tools like web_search and web_fetch to gather external evidence.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:56-103
3. Synthesis (AiSynthesisExecutionRunner)
The synthesis runner aggregates the curated text from all subagents. It is specifically instructed to resolve disagreements explicitly and produce a cohesive Markdown briefing backed by a structured JSON response containing conflict highlights and references.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt:15-30, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt:48-65
Data Model
The system utilizes PostgreSQL for persistent storage, with a focus on relationships between user content and AI-generated metadata.
| Entity | Primary Fields | Purpose |
|---|---|---|
| Source | URL, Status, Content, Metadata | Stores ingested articles or media. |
| Topic | Name, Status, Normalized Name | Groups sources into logical themes. |
| Briefing | Intent, Status, ContentMarkdown | The final research product. |
| TopicLink | topicId, targetId, status, confidence | Connects sources to topics (Suggested or Active). |
| BriefingPlanStep | personaName, task, status | Tracks individual research tasks within a briefing. |
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicService.kt:285-300, apps/api/src/test/kotlin/com/briefy/api/application/briefing/BriefingGenerationServiceTest.kt:133-150
Frontend Architecture
The frontend (apps/web) is built with React and uses TanStack Router for type-safe routing. It follows a modular structure where routes are colocated in the src/routes directory.
Core Pathing
The UI supports "Two Core Paths":
- Content Consumption: Visualizing engagement and completion metrics.
- Content Generation: Transforming the knowledge base into consistent writing ideas and themes.
Sources: apps/web/src/routes/index.tsx:64-80, AGENTS.md:20-22
State & Authentication
Authentication is managed via a useAuth hook, which gates access to private routes such as /sources, /topics, and /briefings. The frontend performs single-flight session refreshes on 401 errors to maintain persistent access.
Sources: apps/web/src/routes/index.tsx:82-85, AGENT_NOTES.md:144-148
Summary
The Briefy architecture emphasizes a robust AI-driven pipeline that leverages a multi-persona agent strategy to verify and synthesize information. By combining a Kotlin/Spring backend for heavy orchestration with a modern React frontend, the system provides a structured environment for long-term knowledge retention and high-quality research output.