Frontend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The frontend of Briefy is a modern React application built with TypeScript and Vite, following a monorepo structure where the web client resides in apps/web. It serves as the primary interface for knowledge workers to manage a library of sources, organize them into topics, and generate AI-driven briefings. The architecture emphasizes a type-safe, component-driven approach with a focus on seamless routing and asynchronous data fetching.
Sources: AGENTS.md:7-10, apps/web/package.json:1-15
Tech Stack and Core Dependencies
The application leverages a curated set of libraries to manage state, routing, and UI components.
| Category | Technology / Library | Description |
|---|---|---|
| Framework | React 19 | UI library for building component-based interfaces. |
| Build Tool | Vite | Next-generation frontend tooling for fast development and bundling. |
| Language | TypeScript | Provides static typing for improved maintainability and developer experience. |
| Routing | TanStack Router | Type-safe routing system with file-based route generation. |
| Styling | Tailwind CSS 4 | Utility-first CSS framework for rapid UI development. |
| Icons | Lucide React | Clean and consistent icon set. |
| Components | Radix UI | Unstyled, accessible UI primitives. |
Sources: apps/web/package.json:17-57, AGENTS.md:18-20
Project Structure and Module Organization
The frontend codebase is organized into several key directories within apps/web/src:
components/: Shared UI components, including specialized wrappers likeMarkdownContentand standard primitives incomponents/ui.features/: Domain-specific logic and components (e.g.,features/sources,features/audio,features/chat).lib/: Core utilities, API clients, and authentication hooks (lib/auth,lib/api).routes/: File-based routing structure using TanStack Router.
Component Organization Diagram
This diagram illustrates how domain-specific features and shared UI components interact with the routing layer.
Routing and Navigation
Briefy uses TanStack Router for type-safe, file-based routing. Routes are colocated in the src/routes directory, and the route tree is automatically generated.
Key Routes
/: Homepage featuring marketing content and entry points for authenticated users./sources: The main Library view for managing active and archived sources./sources/$sourceId: Detail view for a specific source, showing content, metadata, and topic links./topics: Management interface for both "Active" and AI-"Suggested" topics./share/$token: Publicly accessible pages for shared source content.
Sources: apps/web/src/routes/index.tsx:1-15, apps/web/src/routes/sources/index.tsx:43-48, apps/web/src/routes/topics/index.tsx:21-27, apps/web/src/routes/share/$token.tsx:10-12
Authentication Guard Flow
Routes often implement a beforeLoad hook to ensure users are authenticated before accessing protected pages.
Data Management and API Interaction
The frontend interacts with a Kotlin/Spring Boot backend via a centralized API client.
Data Fetching Patterns
Data fetching is typically handled using useEffect and useCallback within components or specialized hooks like useSourceData. The application manages various states including loading, error, and the primary data object.
Source Retrieval Sequence
This diagram shows how source details and their associated topics are retrieved.
Shared Infrastructure Features
- Markdown Rendering: The
MarkdownContentcomponent usesreact-markdownwithremark-gfmandremark-breaksto render formatted text with support for external links. - Audio Narration: Integration with an audio player feature allows users to listen to source narrations, using presigned URLs from the backend.
- Infinite Loading: The Sources and Topics lists implement intersection observers to trigger "Load More" functionality via cursor-based pagination.
Sources: apps/web/src/components/content/MarkdownContent.tsx:20-45, apps/web/src/routes/sources/index.tsx:129-144, apps/web/src/features/sources/components/SourceHeader.tsx:64-70
User Interface and Styling
The UI follows a clean, "serious reader" aesthetic using Tailwind CSS and Radix UI.
- Design Tokens: Custom design tokens are managed via Tailwind, including specialized background gradients (
bg-[radial-gradient(...)]) and translucent card treatments (bg-card/45). - Animations: The app uses
tw-animate-cssfor entry animations likeanimate-fade-in,animate-slide-up, andanimate-scale-into improve perceived performance. - Responsive Design: Layouts use standard Tailwind breakpoints (e.g.,
md:grid-cols-2,sm:flex-row) to ensure usability across mobile and desktop devices.
Sources: apps/web/src/routes/index.tsx:66-72, apps/web/src/routes/sources/index.tsx:465-475, apps/web/package.json:49-49
Conclusion
The Frontend Architecture of Briefy is built for scalability and developer velocity by utilizing a type-safe stack. By leveraging TanStack Router for navigation and a feature-based structure for domain logic, the application maintains a clear separation of concerns while providing a rich, interactive experience for knowledge management and synthesis.
Sources: AGENTS.md:7-12, AGENT_NOTES.md:144-148