Developer Guidelines & Agent Notes

Relevant source files

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

• AGENTS.md
• AGENT_NOTES.md
• apps/api/src/main/resources/application.yml
• apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt
• apps/web/src/routes/index.tsx
• apps/api/src/main/kotlin/com/briefy/api/application/topic/TopicSuggestionService.kt
• apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt

Introduction

The Briefy project is a monorepo consisting of a Kotlin Spring Boot backend (apps/api) and a React Vite frontend (apps/web). This document outlines the technical standards, architectural constraints, and persistent institutional memory (Agent Notes) required for contributors and AI agents to maintain the codebase. It emphasizes a strict separation between domain, application, infrastructure, and API layers in the backend, while enforcing a React-specific style in the frontend.

Sources: AGENTS.md:1-12

Project Structure & Command Reference

The repository organizes the local multi-service stack using Docker Compose. Developers should manage individual components from their respective directories.

Backend Architecture

The API follows a layered architecture:

• domain: Core logic and entities.
• application: Service layer orchestrating domain logic.
• infrastructure: External integrations (DB, AI adapters).
• api: HTTP controllers and request/response DTOs.

Commands

Context	Action	Command
Backend	Run App	cd apps/api && ./gradlew bootRun
Backend	Run Tests	cd apps/api && ./gradlew test
Frontend	Dev Server	cd apps/web && pnpm dev
Frontend	Build	cd apps/web && pnpm build
Full Stack	Local Setup	docker compose up --build

Sources: AGENTS.md:7-25

Coding Styles & Naming Conventions

The project adheres to specific indentation and naming patterns to ensure consistency across the monorepo.

• Kotlin: 4-space indentation, PascalCase types, camelCase members. All packages must reside under com.briefy.api.
• TypeScript/React: 2-space indentation, PascalCase components, camelCase functions/hooks. Routes are colocated in src/routes.
• SQL Migrations: Managed via Flyway using the format V<timestamp>__<snake_case_description>.sql.
• Commit Messages: Short, imperative messages such as FEAT: ... (#PR) or lowercase imperatives like implement user authentication.

Sources: AGENTS.md:27-41, AGENTS.md:54-58

Persistent Agent Memory

The AGENT_NOTES.md file serves as a collaborative memory bank. It is strictly organized into three sections to prevent duplication and facilitate quick onboarding for new sessions.

1. Mistakes Log

Records real implementation errors and preventions. Key findings include:

• Gradle Collision: Running test in parallel in the same module causes XML report write collisions.
• SQL Formatting: Using @Lob for large text fields causes PostgreSQL schema mismatches; use @Column(columnDefinition = "TEXT") instead.
• Transaction Management: Avoid @Transactional on methods involving AI retries (e.g., TopicSuggestionService), as it holds DB connections open during high-latency LLM calls.

2. Non-Obvious Code Findings

Surprising behaviors that are not immediately evident from code reading:

• X Extraction: Thread filtering for X (formerly Twitter) requires checking in_reply_to_user_id == authorId to maintain the self-thread chain and exclude noise.
• Spring AI Config: ZhipuAI starters require explicitly disabling non-chat models in application.yml (e.g., spring.ai.model.embedding=none).
• Nginx Config: Directive proxy_set_header cannot be used inside if blocks.

3. User Preferences

Direct signals about workflow or UI/UX:

• Deletion: "Delete" actions in the UI must implement archive semantics (not hard deletion) for Sources.
• UX Feedback: Prefer lightweight inline feedback (icon changes) over toast notifications.
• PR Rules: Never push directly to main; always use feature branches and PRs.

Sources: AGENT_NOTES.md:1-240, AGENTS.md:65-85

AI Execution & Integration Logic

The system heavily integrates LLMs for research personas and topic suggestions.

Subagent Tool Loop

The AiSubagentExecutionRunner implements a tool-calling loop where an LLM can decide to search or fetch web content.

This runner enforces constraints such as a maximum of 3 web_fetch calls per investigation and mandatory citation of internal source titles and web URLs.

Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:33-110

Topic Suggestion Workflow

The TopicSuggestionService manages the extraction of keywords and themes from source content using three distinct phases to optimize database connection usage.

Infrastructure Configuration

Configuration is managed via application.yml, surfacing environment variables for critical integrations.

Category	Key Property	Default/Behavior
LLM	spring.ai.model.chat	Defined by LLM_PROVIDER (e.g., zhipuai, google_genai)
Search	briefing.execution.tools.web-search	Uses Brave Search API; timeout 10s
Narrate	audio.storage.bucket	Defaults to briefy-audio
Media	extraction.media.ffmpeg-path	Configurable for video transcription tasks

Sources: apps/api/src/main/resources/application.yml:1-250

Testing Guidelines

Testing is mandatory for changes to domain logic, security flows, and controllers.

• Backend: Uses JUnit 5, Spring Boot Test, and MockMvc. Tests should be named *Test.kt.
• Frontend: Tests are not currently configured; verify via pnpm lint and pnpm build.
• H2 vs PostgreSQL: When mapping UUIDs in native queries, handle both UUID and ByteArray types to ensure H2 tests behave like the production PostgreSQL database.

Sources: AGENTS.md:43-52, AGENT_NOTES.md:15-25, apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt:1-50

Conclusion

The development of Briefy relies on a disciplined monorepo approach where backend domain boundaries and frontend component patterns are strictly followed. By utilizing the AGENT_NOTES.md and following the subagent execution patterns, developers ensure that the AI-driven features of the platform remain reliable, observable, and aligned with user preferences for clear thinking and information retention.