Docker & Deployment Infrastructure
Relevant source files
The following files were used as context for generating this wiki page:
The Docker and deployment infrastructure for Briefy is designed to support a small monorepo architecture consisting of a Kotlin-based backend and a React-based frontend. The system leverages containerization to ensure consistency across local development and production environments, providing a multi-service stack that includes a database, an API server, and a web interface.
Sources: AGENTS.md:7-13, AGENT_NOTES.md:120-125
Local Development Stack
The project utilizes a docker-compose.yml configuration to orchestrate a local multi-service stack. This environment allows developers to run the entire application ecosystem with a single command, ensuring that all dependencies and networking configurations are pre-defined.
Core Services
| Service | Technology Stack | Description |
|---|---|---|
db | PostgreSQL / pgvector | Relational database with vector search capabilities for embeddings. |
api | Kotlin + Spring Boot | Backend application server handling domain logic and AI integration. |
web | React + Vite | Frontend user interface served via TypeScript. |
The local stack is initialized using the command docker compose up --build.
Sources: AGENTS.md:10-13, 20, AGENT_NOTES.md:120-125
Environment Configuration
The infrastructure relies on environment variables for sensitive configurations. Developers are required to use a .env.example template to create local .env files. Critical variables that must be excluded from source control include:
JWT_SECRET: For authentication token signing.LLM_API_KEY: For AI provider (e.g., Google GenAI, Zhipuai) access.DB_CREDENTIALS: Database access strings.
Sources: AGENTS.md:46-50, AGENT_NOTES.md:74-78
CI/CD and Verification
The project employs GitHub Actions for continuous integration, specifically focused on backend verification.
Automated Workflows
- Backend Tests: Triggered on Pull Requests (PRs) and pushes to the
mainbranch. - Workflow Path: Located at
.github/workflows/backend-tests.yml. - Validation: Includes JUnit 5 tests, Spring Boot integration tests, and Flyway migration validation.
Sources: AGENTS.md:23, 38, AGENT_NOTES.md:100-105
Deployment Architecture
The deployment infrastructure is designed for cloud-native environments, specifically referencing platforms like Railway and storage solutions like S3/R2.
The diagram shows the flow from code commit to production deployment, highlighting the relationship between services and external dependencies.
Sources: AGENTS.md:23, AGENT_NOTES.md:4-10, 110-115
Infrastructure Components & Logic
Database Migrations
Briefy uses Flyway for schema management. Migrations are stored in apps/api/src/main/resources/db/migration and follow a strict naming convention: V<timestamp>__<snake_case_description>.sql.
Sources: AGENTS.md:9, 30-31
AI Runner Configuration
The deployment infrastructure supports various AI providers through configurable runners. The AiSubagentExecutionRunner is configured with specific models and toolsets.
| Parameter | Default Value | Source |
|---|---|---|
| Provider | google_genai | AiRunnerConfig |
| Model | gemini-2.5-flash | AiRunnerConfig |
| Max Tool Calls | 8 | AiRunnerConfig |
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:205-209
Storage and Media Delivery
The infrastructure handles media delivery (e.g., narration audio) using S3-compatible storage. Public audio delivery is managed through presigned URLs, though internal notes indicate that browser-reachable delivery should be treated as a separate proxy/streaming concern.
Sources: AGENT_NOTES.md:4-9, 145-150
Infrastructure State Management
The following sequence diagram illustrates how the infrastructure handles service-level interactions during a briefing generation process, involving the API, AI runners, and external tools.
This diagram represents the execution loop within the AI runner infrastructure, specifically how it handles tool requests and final output generation.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/briefing/AiSubagentExecutionRunner.kt:33-100
Conclusion
Briefy's infrastructure provides a robust foundation for AI-driven knowledge synthesis by combining a containerized local stack with a cloud-ready deployment model. The use of standardized Docker configurations, strict environment variable management, and automated CI workflows ensures high reliability and developer productivity across the monorepo services.