Local Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Briefy repository is structured as a small monorepo containing a Kotlin-based API and a React-based web frontend. Setting up the local environment requires configuring the backend services, the frontend development server, and the necessary environment variables for external integrations such as LLMs and extraction providers. Sources: AGENTS.md:7-12
Project Architecture Overview
The project consists of two primary applications and a set of utility scripts. The backend handles domain logic, application services, and infrastructure concerns, while the frontend provides the user interface for content consumption and generation. Sources: AGENTS.md:7-14
The diagram above illustrates the high-level architecture of the local development stack, including the relationship between the database, backend, and frontend. Sources: AGENTS.md:7-14, apps/web/src/routes/settings/index.tsx:105-115
Prerequisites and Installation
Backend Requirements
The API is built using Kotlin and Spring Boot. It uses Gradle as the build tool and Flyway for database migrations. Sources: AGENTS.md:8-14
| Component | Technology | Command |
|---|---|---|
| Runtime | Kotlin / Spring Boot | ./gradlew bootRun |
| Testing | JUnit 5 / MockMvc | ./gradlew test |
| Migrations | Flyway | SQL in src/main/resources/db/migration |
Sources: AGENTS.md:8-23
Frontend Requirements
The web application is built with React, TypeScript, and Vite. It uses pnpm for package management. Sources: AGENTS.md:9-10, apps/web/package.json:1-10
| Action | Command |
|---|---|
| Install Dependencies | pnpm install |
| Development Server | pnpm dev |
| Production Build | pnpm build |
| Linting | pnpm lint |
Sources: AGENTS.md:19-23, apps/web/package.json:6-9
Configuration and Secrets
Local configuration is managed through environment variables. Developers must copy .env.example to create a local .env file. Sources: AGENTS.md:46-50
Required Environment Variables
The following categories of configuration are required for full functionality:
- Security:
JWT_SECRETfor authentication. - Database: Credentials for the local PostgreSQL instance.
- AI Integration:
LLM_API_KEYfor briefing generation and topic extraction. - External Tools: API keys for providers like Firecrawl, X API, or ElevenLabs if enabled.
Sources: AGENTS.md:46-50, apps/web/src/routes/settings/index.tsx:130-180
Multi-Service Stack (Docker)
For a simplified setup of the entire local stack, the project provides a Docker Compose configuration. Sources: AGENTS.md:11-12
# Launch the full local stack (db, api, web)
docker compose up --build
Sources: AGENTS.md:24
Development Workflow
Database Migrations
Migrations follow a specific naming convention: V<timestamp>__<snake_case_description>.sql. Utility scripts like scripts/genDDLFile.sh are available for managing schema changes. Sources: AGENTS.md:12-32
Component Development Flow
The following sequence diagram represents the typical flow when adding a new source through the local environment:
Testing the Setup
To ensure the local environment is correctly configured, run the following test suites:
- Backend:
cd apps/api && ./gradlew test. This executes JUnit 5 tests, including controller tests that mock extraction providers and security context. Sources: AGENTS.md:20, apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt:50-65 - Frontend:
cd apps/web && pnpm lint && pnpm build. While a specific test framework for the UI is not yet configured, passing these commands ensures type safety and style compliance. Sources: AGENTS.md:22-42
Summary
The Briefy local environment setup is designed around a monorepo structure utilizing Docker for orchestration and standard language tools (Gradle, pnpm) for application development. Successful setup requires local instances of PostgreSQL, configuration of LLM API keys, and adherence to the defined coding styles and module boundaries. Sources: AGENTS.md:7-50