System Architecture
Core Features
Data Management
Frontend Components
Extensibility
The following files were used as context for generating this wiki page:
This document outlines the build pipelines for the api application, covering both the traditional CodeBuild approach and a more streamlined multi-stage Docker build process. It also details the local development setup using Docker Compose and the project's dependency management strategy. The primary goal of these pipelines is to build the api service, package it into a Docker image, and deploy it to an Amazon ECS cluster.
The project utilizes two distinct CodeBuild specifications for the api service: buildspec.yml for a standard, step-by-step build within the CodeBuild environment, and buildspec.multistage.yml which offloads most of the build logic to a multi-stage Dockerfile. For local development and testing, docker-compose.yml provides a convenient way to run the api service using the same multi-stage Docker build approach. Dependency consistency across the monorepo is enforced using syncpack as configured in .syncpackrc.json.
buildspec.yml)The apps/api/buildspec.yml file defines a comprehensive CodeBuild pipeline for the api application. This pipeline is responsible for fetching dependencies, building the application, creating a Docker image, pushing it to Amazon ECR, and finally updating the Amazon ECS service.
The build process is divided into three main phases: pre_build, build, and post_build.
This phase focuses on initial setup, including logging into Amazon ECR and preparing environment variables for the build process. It also installs bun, the JavaScript runtime and package manager used in the project.
Key Actions:
REPOSITORY_URI based on $ECR_REPOSITORY_URI.COMMIT_HASH from $CODEBUILD_RESOLVED_SOURCE_VERSION and set IMAGE_TAG.bun using its official installation script.This is the core of the pipeline, where the application is built and packaged into a Docker image. It involves environment configuration, validation, dependency installation, workspace package building, the main API application build, and meticulous preparation of build artifacts for Docker.
Key Actions:
PATH, PGSSLMODE, NODE_ENV, NEXT_TELEMETRY_DISABLED, UV_THREADPOOL_SIZE, and NODE_OPTIONS.DATABASE_URL, BASE_URL, AWS credentials) are set, failing the build if any are missing.api workspace dependencies using bun install --filter=@comp/api.packages/db, packages/integration-platform).apps/api and builds the NestJS application using bun run build.main.js in the build output.docker-build directory.api application artifacts (handling both dist/apps/api/src and dist/src output structures).prisma directory.node_modules directory.@trycompai/utils, @trycompai/db, and @comp/integration-platform with their actual built output and package.json files.Dockerfile to the docker-build directory.package.json to remove the workspace dependency for @comp/integration-platform before copying.bun.lock.docker-build context and tags it with the commit hash and latest.This phase handles the deployment of the newly built Docker image.
Key Actions:
IMAGE_TAG and latest.imagedefinitions.json for ECS deployment.The build process critically depends on several environment variables, which are validated during the build phase. These include database connection strings, base URLs for various services, and AWS credentials for S3 access.
The following flowchart illustrates the detailed steps within the build phase of the standard CodeBuild pipeline.
Sources: apps/api/buildspec.yml:1-105
buildspec.multistage.yml)This alternative pipeline simplifies the CodeBuild process by leveraging a multi-stage Dockerfile (Dockerfile.multistage) to handle the entire build process within a Docker container. CodeBuild's role is reduced to orchestrating the Docker build, pushing the image, and updating the ECS service.
Similar to the standard pipeline, this phase handles ECR login and image tagging.
Key Actions:
COMMIT_HASH and set IMAGE_TAG.The core difference lies here: the actual application build is performed by Docker.
Key Actions:
apps/api.docker build using Dockerfile.multistage with the production target. The build context is set to the monorepo root (../..), allowing the Dockerfile to access all necessary files.This phase is identical to the standard pipeline, handling deployment.
Key Actions:
imagedefinitions.json.docker-compose.yml)The apps/api/docker-compose.yml file is designed for local development and testing of the api service. It utilizes the same multi-stage Dockerfile (Dockerfile.multistage) as the simplified CodeBuild pipeline to ensure consistency between local and production builds.
The api service is configured with the following properties:
This docker-compose.yml is explicitly marked for local testing only. It should not be used for production deployments.
The healthcheck defined in docker-compose.yml ensures that the api service is running and responsive before marking the container as healthy.
Sources: apps/api/docker-compose.yml:1-24
.syncpackrc.json)The .syncpackrc.json file configures syncpack, a tool used to maintain consistency in package dependencies across the monorepo. This ensures that all packages using a particular dependency (e.g., React, Next.js) are on the same version, and that internal workspace packages are correctly referenced.
source: Specifies the locations of package.json files to be managed. This includes the root package.json and those within apps/*/package.json and packages/*/package.json.dependencyTypes: Defines which types of dependencies syncpack should manage: prod (dependencies), dev (devDependencies), and peer (peerDependencies).semverGroups: Defines rules for semantic versioning ranges.
@comp/) always use workspace:* for their version range, indicating they are part of the monorepo.versionGroups: Defines groups of packages that must have consistent versions across all package.json files in the monorepo. This is crucial for avoiding dependency hell and ensuring a stable build environment.lintRules: Defines rules for forbidden dependencies. For example, it prevents direct dependencies on Node.js built-in modules like crypto, fs, or path, which might indicate a misunderstanding of module bundling or environment.The following table lists some of the key dependency groups enforced by syncpack to maintain consistency:
Sources: .syncpackrc.json:1-55