Welcome to Briefy AI

Relevant source files

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

• AGENTS.md
• AGENT_NOTES.md
• apps/web/src/routes/index.tsx
• apps/web/index.html
• apps/api/src/main/resources/application.yml
• 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/web/src/lib/api/types.ts

Briefy AI is a knowledge management and synthesis platform designed to help knowledge workers, founders, and creators transform scattered information into structured, actionable understanding. The system functions as a monorepo containing a Kotlin/Spring Boot backend and a React/TypeScript frontend, leveraging Large Language Models (LLMs) to automate content curation, synthesis, and long-term retention.

The platform provides a centralized library for saving articles, threads, and posts from various platforms (e.g., X/Twitter, YouTube, and generic web URLs). By applying AI-driven multi-persona research and synthesis, Briefy generates briefings that reconcile evidence from multiple sources, allowing users to move from passive consumption to active knowledge growth.

Sources: apps/web/src/routes/index.tsx:75-81, AGENTS.md:6-10

Core Product Loop

The user experience is built around a four-step loop that facilitates the transition from raw data to compounds learning.

Step	Action	Description
1	Save from anywhere	Users drop in articles, threads, and posts into a single clean reading queue.
2	Understand faster	The system generates briefings that connect ideas across multiple sources.
3	Keep what matters	Ideas are converted into reusable takeaways for decisions and strategy.
4	Remember over time	Insights are resurfaced to ensure learning compounds instead of fading.

Sources: apps/web/src/routes/index.tsx:13-33

System Architecture

Briefy follows a monorepo structure with a clear separation between the API and the Web client.

Monorepo Organization

• apps/api: Kotlin + Spring Boot backend. It follows a hexagonal-inspired architecture with boundaries for domain, application, infrastructure, and api.
• apps/web: React + TypeScript + Vite frontend. It uses TanStack Router for file-based routing and Tailwind CSS for styling.
• docker-compose.yml: Manages the local multi-service stack including the database, API, and web server.

Sources: AGENTS.md:6-14

Data and AI Flow

The system processes information through an automated pipeline involving extraction, topic suggestion, and multi-persona briefing generation.

The diagram above shows the high-level flow from URL submission to final briefing delivery.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt:33-40, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:38-55, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt:15-30

Briefing Generation System

The briefing system is a complex multi-stage process that uses AI personas to analyze information.

AI Subagents and Planning

Briefings are not generated in a single step. Instead, an AiBriefingPlanGenerator creates a plan involving 2 to 5 specific steps, each assigned to an AgentPersona (e.g., "Claim Auditor" or "The Scientist").

• Planning: The planner analyzes source content and generates a JSON-based plan containing persona names and specific tasks.
• Subagent Execution: The AiSubagentExecutionRunner executes these tasks. Subagents can use tools like web_search and web_fetch to gather evidence beyond the internal sources.

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiBriefingPlanGenerator.kt:25-45, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:45-100

AI Synthesis

Once subagents complete their research, the AiSynthesisExecutionRunner aggregates their outputs.

The synthesis phase is responsible for reconciling disagreements between different personas and ensuring claims are grounded in evidence.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSynthesisExecutionRunner.kt:40-60

Technical Configuration

The system relies on external LLM providers and extraction services configured via environment variables.

AI Provider Configuration

The API supports multiple AI providers, which are resolved at runtime based on the use case (e.g., topic_extraction, briefing_generation).

Provider	Config Key	Default Model
Google GenAI	GOOGLE_GENAI_API_KEY	gemini-2.5-flash
Zhipu AI	ZHIPUAI_API_KEY	glm-4.7-flash
Minimax	MINIMAX_API_KEY	MiniMax-M2.5

Sources: apps/api/src/main/resources/application.yml:21-45, apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:251-255

Extraction Providers

Briefy uses specialized extractors depending on the source platform:

• Firecrawl: Preferred for article-like content and clean markdown.
• X API: Used for X/Twitter posts and threads.
• YouTube (yt-dlp): Used for transcribing video content.
• Jsoup: A zero-config fallback for generic web platforms.

Sources: apps/web/src/routes/settings/index.tsx:280-350, apps/api/src/main/resources/application.yml:76-105

Security and Authentication

Briefy uses JWT-based authentication for both the web client and the API.

• Secrets: JWT_SECRET, LLM_API_KEY, and database credentials are kept in environment variables and never committed.
• Encryption: A system-level ENCRYPTION_KEY is used for sensitive data.
• Frontend Guards: Routes like /settings/ and /briefings/$briefingId are protected by a requireAuth helper.

Sources: AGENTS.md:46-51, apps/api/src/main/resources/application.yml:58-64, apps/web/src/routes/briefings/$briefingId.tsx:18-22