System Architecture
Core Features
Data Management
Frontend Components
Extensibility
<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [apps/api/buildspec.yml](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml)
- [apps/api/docker-compose.yml](https://github.com/blade47/comp/blob/main/apps/api/docker-compose.yml)
- [README.md](https://github.com/blade47/comp/blob/main/README.md)
- [apps/api/src/config/load-env.ts](https://github.com/blade47/comp/blob/main/apps/api/src/config/load-env.ts)
</details>
This guide provides comprehensive instructions for deploying and running the Comp AI platform, covering both cloud-based CI/CD processes for the API and local development setups. It details the steps for building, packaging, and deploying the API service using AWS CodeBuild, as well as configuring a local development environment with Docker Compose, database setup, and environment variable management.
The document consolidates information from various configuration and setup files to offer a unified view of the deployment landscape for the Comp AI project.
## Cloud Deployment: AWS CodeBuild for API
The `apps/api` service utilizes an AWS CodeBuild pipeline for its continuous integration and deployment process. This pipeline automates the building of the application, creation of Docker images, and deployment to Amazon Elastic Container Registry (ECR) and Amazon Elastic Container Service (ECS).
### CodeBuild Pipeline Overview
The CodeBuild process is divided into three main phases: `pre_build`, `build`, and `post_build`, each executing a series of commands to prepare, build, and deploy the application.
Sources: [apps/api/buildspec.yml:1-85](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L1-L85)
### Pre-Build Phase
This phase focuses on initial setup and authentication required before the main build process begins.
- **ECR Login**: Authenticates with Amazon ECR using AWS credentials to allow pushing and pulling Docker images.
- **Variable Setup**: Defines `REPOSITORY_URI`, `COMMIT_HASH`, and `IMAGE_TAG` based on ECR repository URI and the Git commit hash. The `IMAGE_TAG` defaults to `latest` if no commit hash is available.
- **Dependency Manager Installation**: Installs `bun`, the JavaScript runtime and package manager used across the project.
Sources: [apps/api/buildspec.yml:4-12](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L4-L12)
### Build Phase
The core of the pipeline, where the application is built, packaged, and a Docker image is created.
#### Environment Setup and Validation
Critical environment variables are set and validated to ensure the build environment is correctly configured. The build will fail if any of these required variables are not present.
<Callout title="Required Environment Variables" variant="danger">
The following environment variables are critical for the API build and deployment. Their absence will cause the CodeBuild process to fail.
</Callout>
| Environment Variable | Description |
| :---------------------------- | :----------------------------------------------------------------------- |
| `DATABASE_URL` | Connection string for the PostgreSQL database. |
| `BASE_URL` | Base URL for the application. |
| `BETTER_AUTH_URL` | URL for the authentication service. |
| `TRUST_APP_URL` | URL for the trust application. |
| `APP_AWS_BUCKET_NAME` | AWS S3 bucket name for application assets. |
| `APP_AWS_ACCESS_KEY_ID` | AWS access key ID for S3 access. |
| `APP_AWS_SECRET_ACCESS_KEY` | AWS secret access key for S3 access. |
Other environment variables set during this phase include:
- `PATH`: Updated to include Bun's binary directory.
- `PGSSLMODE`: Set to `require` for PostgreSQL SSL.
- `NODE_ENV`: Set to `production`.
- `NEXT_TELEMETRY_DISABLED`: Set to `1` to disable Next.js telemetry.
- `UV_THREADPOOL_SIZE`: Set to `36`.
- `NODE_OPTIONS`: Set to `--max-old-space-size=65536` to increase Node.js memory limit.
Sources: [apps/api/buildspec.yml:15-30](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L15-L30)
#### Application Build Process
1. **Dependency Installation**: Installs only the API workspace dependencies using `bun install --filter=@comp/api`.
2. **Workspace Package Build**: Builds shared packages (`packages/db`, `packages/integration-platform`) that the API depends on.
3. **NestJS Application Build**: Navigates to `apps/api` and executes `bun run build` to compile the NestJS application.
4. **Build Output Handling**: Copies the compiled API application files (`dist/`) into a temporary `../docker-build` directory, handling potential variations in the output structure (`dist/apps/api/src` or `dist/src`).
5. **Prisma Schema Copy**: Copies the `prisma` directory to the Docker build context.
6. **Node Modules & Workspace Symlink Resolution**:
* Copies the root `node_modules` directory.
* Removes workspace symlinks for `@trycompai/utils`, `@trycompai/db`, and `@comp/integration-platform`.
* Replaces these symlinks with the actual built output and `package.json` files from their respective `packages/` directories.
7. **Dockerfile Preparation**: Copies the `Dockerfile` to the Docker build context and modifies `package.json` to remove the workspace dependency for `@comp/integration-platform` (as it's handled manually).
8. **Docker Image Build**: Constructs the Docker image using the prepared `../docker-build` context and tags it with the ECR repository URI and the generated `IMAGE_TAG`. It also tags the image with `latest`.
Sources: [apps/api/buildspec.yml:33-77](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L33-L77)
### Post-Build Phase
This phase handles the final deployment steps after the Docker image is successfully built.
- **ECR Push**: Pushes the newly built Docker image (both tagged and `latest`) to Amazon ECR.
- **ECS Service Update**: Triggers a forced new deployment for the specified ECS service, ensuring the ECS cluster pulls the latest image.
- **Image Definitions**: Generates an `imagedefinitions.json` file, which is used by AWS CodePipeline or other services to specify the image URI for the deployed container.
Sources: [apps/api/buildspec.yml:80-85](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L80-L85)
### Caching and Artifacts
The CodeBuild configuration includes caching paths for `node_modules` and Bun's install cache to speed up subsequent builds. The `imagedefinitions.json` file is specified as a build artifact.
Sources: [apps/api/buildspec.yml:87-95](https://github.com/blade47/comp/blob/main/apps/api/buildspec.yml#L87-L95)
## Local Development & Testing
Setting up the Comp AI project for local development involves several steps, including installing prerequisites, configuring environment variables, and initializing the database.
### Prerequisites
To run Comp AI locally, ensure you have the following installed:
- **Node.js**: Version `>=20.x`
- **Bun**: Version `>=1.1.36`
- **Postgres**: Version `>=15.x`
Sources: [README.md:94-98](https://github.com/blade47/comp/blob/main/README.md#L94-L98)
### Initial Setup
<Steps>
<Step>
### Clone the Repository
Clone the Comp AI repository from GitHub.
\`\`\`sh
git clone https://github.com/trycompai/comp.git
cd comp
\`\`\`
</Step>
<Step>
### Install Dependencies
Install all project dependencies using Bun.
\`\`\`sh
bun install
\`\`\`
</Step>
<Step>
### Prepare Environment Files
Copy the example environment files for the `app`, `portal`, and `db` workspaces.
<Tabs items={["Linux / macOS", "Windows (Command Prompt)", "Windows (PowerShell)"]}>
<Tab value="Linux / macOS">
\`\`\`sh
cp apps/app/.env.example apps/app/.env
cp apps/portal/.env.example apps/portal/.env
cp packages/db/.env.example packages/db/.env
\`\`\`
</Tab>
<Tab value="Windows (Command Prompt)">
\`\`\`cmd
copy apps\app\.env.example apps\app\.env
copy apps\portal\.env.example apps\portal\.env
copy packages\db\.env.example packages\db\.env
\`\`\`
</Tab>
<Tab value="Windows (PowerShell)">
\`\`\`powershell
Copy-Item apps\app\.env.example -Destination apps\app\.env
Copy-Item apps\portal\.env.example -Destination apps\portal\.env
Copy-Item packages\db\.env.example -Destination packages\db\.env
\`\`\`
</Tab>
</Tabs>
</Step>
<Step>
### Generate Prisma Types
Navigate to each application directory and generate the Prisma client.
\`\`\`sh
cd apps/app
bun run db:generate
cd ../portal
bun run db:generate
cd ../api
bun run db:generate
\`\`\`
</Step>
</Steps>
Sources: [README.md:104-142](https://github.com/blade47/comp/blob/main/README.md#L104-L142)
### Environment Variables
After copying the `.env.example` files, you must fill them with your credentials. Additionally, ensure the following variables are present in `comp/apps/app/.env`:
| Variable | Description | Example Value |
| :------------------------ | :------------------------------------------------------------------------------------------------------ | :------------------------------------------- |
| `AUTH_SECRET` | Secret key for authentication. Generate using `openssl rand -base64 32`. | `your_auth_secret` |
| `DATABASE_URL` | PostgreSQL connection string. | `postgresql://user:password@host:port/database` |
| `RESEND_API_KEY` | API key for Resend email service. | `re_your_resend_api_key` |
| `NEXT_PUBLIC_PORTAL_URL` | Public URL for the portal application. | `http://localhost:3002` |
| `REVALIDATION_SECRET` | Secret key for revalidation. Generate using `openssl rand -base64 32`. | `your_revalidation_secret` |
<Callout title="Important Note" variant="warning">
Some environment variables might not load correctly from `.env` files. In such cases, you may need to hard-code their values directly into the relevant source files as indicated in the "Cloud & Auth Configuration" section.
</Callout>
Sources: [README.md:144-166](https://github.com/blade47/comp/blob/main/README.md#L144-L166)
### Cloud & Authentication Configuration
Several external services require specific configuration for local development.
#### Trigger.dev
1. Create an account on [https://cloud.trigger.dev](https://cloud.trigger.dev).
2. Create a project and copy its Project ID.
3. Update `comp/apps/app/trigger.config.ts` with your Project ID:
\`\`\`typescript
project: 'proj_****az***ywb**ob*';
\`\`\`
Sources: [README.md:170-176](https://github.com/blade47/comp/blob/main/README.md#L170-L176)
#### Google OAuth
1. Go to [Google Cloud OAuth Console](https://console.cloud.google.com/auth/clients).
2. Create an OAuth client of type "Web Application".
3. Add the following Authorized Redirect URIs:
- `http://localhost`
- `http://localhost:3000`
- `http://localhost:3002`
- `http://localhost:3000/api/auth/callback/google`
- `http://localhost:3002/api/auth/callback/google`
- `http://localhost:3000/auth`
- `http://localhost:3002/auth`
4. Copy the `GOOGLE_ID` and `GOOGLE_SECRET` and add them to your `.env` files.
5. If environment variables are not recognized, hard-code them in `comp/apps/portal/src/app/lib/auth.ts`.
Sources: [README.md:178-197](https://github.com/blade47/comp/blob/main/README.md#L178-L197)
#### Redis (Upstash)
1. Go to [https://console.upstash.com](https://console.upstash.com).
2. Create a Redis database.
3. Copy the Redis URL and TOKEN.
4. Add them to your `.env` file.
5. If environment variables are not recognized, hard-code them in `comp/packages/kv/src/index.ts`.
Sources: [README.md:199-207](https://github.com/blade47/comp/blob/main/README.md#L199-L207)
### Database Setup
The project uses PostgreSQL, managed with Prisma. Docker is used to run the database locally.
<Steps>
<Step>
### Start Database Container
Navigate to the `packages/db` directory and start the PostgreSQL container.
\`\`\`sh
cd packages/db
bun docker:up
\`\`\`
Default credentials:
- Database name: `comp`
- Username: `postgres`
- Password: `postgres`
</Step>
<Step>
### Change Default Password (Optional)
To change the default `postgres` user password:
\`\`\`sql
ALTER USER postgres WITH PASSWORD 'new_password';
\`\`\`
</Step>
<Step>
### Fix Function Definition Error (If encountered)
If you see a "No function matches the given name and argument types..." error, run the following fix:
\`\`\`sh
psql "postgresql://postgres:<your_password>@localhost:5432/comp" -f ./packages/db/prisma/functionDefinition.sql
\`\`\`
</Step>
<Step>
### Apply Schema and Seed Data
Generate the Prisma client, push the schema to the database, and optionally seed with initial data.
\`\`\`sh
bun db:generate # Generate Prisma client
bun db:push # Push the schema to the database
bun db:seed # Optional: Seed the database with initial data
\`\`\`
</Step>
</Steps>
<Accordions>
<Accordion title="Other Useful Database Commands">
- `bun db:studio`: Open Prisma Studio to view/edit data.
- `bun db:migrate`: Run database migrations.
- `bun docker:down`: Stop the database container.
- `bun docker:clean`: Remove the database container and volume.
</Accordion>
</Accordions>
Sources: [README.md:211-256](https://github.com/blade47/comp/blob/main/README.md#L211-L256)
### Starting Development Servers
Once all configurations are complete, you can start the development servers.
\`\`\`sh
bun run dev
\`\`\`
Alternatively, if you have Turbo installed globally, you can use the Turbo repo script:
\`\`\`sh
turbo dev
\`\`\`
Sources: [README.md:258-267](https://github.com/blade47/comp/blob/main/README.md#L258-L267)
### Docker Compose for Local API Testing
The `apps/api/docker-compose.yml` file is provided **for local testing only**. It defines a service to build and run the API in a Docker container.
The `api` service is configured as follows:
| Configuration Item | Value / Description
</a>
<h3 align="center">Comp AI</h3>
The open-source compliance platform.
<br />
<a href="https://trycomp.ai"><strong>Learn more »</strong></a>
<br />
<br />
<a href="https://discord.gg/compai">Discord</a>
·
<a href="https://trycomp.ai">Website</a>
·
<a href="https://trycomp.ai/docs">Documentation</a>
·
<a href="https://github.com/trycompai/comp/issues">Issues</a>
·
<a href="https://roadmap.trycomp.ai/roadmap">Roadmap</a>
<a href="https://www.producthunt.com/products/comp-ai-get-soc-2-iso-27001-gdpr/launches/comp-ai"><img src="https://img.shields.io/badge/Product%20Hunt-%231%20Product%20of%20the%Day%23DA552E" alt="Product Hunt"></a>
<a href="https://github.com/trycompai/comp/stargazers"><img src="https://img.shields.io/github/stars/trycompai/comp" alt="Github Stars"></a>
<a href="https://github.com/trycompai/comp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPLv3-purple" alt="License"></a>
<a href="https://github.com/trycompai/comp/pulse"><img src="https://img.shields.io/github/commit-activity/m/trycompai/comp" alt="Commits-per-month"></a>
<a href="https://github.com/trycompai/comp/issues"><img src="https://img.shields.io/badge/Help%20Wanted-Contribute-blue"></a>
## About
### AI that handles compliance for you in hours.
Comp AI is the fastest way to get compliant with frameworks like SOC 2, ISO 27001, HIPAA and GDPR. Comp AI automates evidence collection, policy management, and control implementation while keeping you in control of your data and infrastructure.
## Recognition
#### [ProductHunt](https://www.producthunt.com/posts/comp-ai)
<a href="https://www.producthunt.com/posts/comp-ai?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_souce=badge-comp-ai" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=944698&theme=light&period=daily&t=1745500415958" alt="Comp AI - The open source Vanta & Drata alternative | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
#### [Vercel](https://vercel.com/)
<a href="https://vercel.com/oss">
<img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge.svg" />
</a>
### Built With
- [Next.js](https://nextjs.org/?ref=trycomp.ai)
- [Trigger.dev](https://trigger.dev/?ref=trycomp.ai)
- [Prisma](https://prisma.io/?ref=trycomp.ai)
- [Tailwind CSS](https://tailwindcss.com/?ref=trycomp.ai)
- [Upstash](https://upstash.com/?ref=trycomp.ai)
- [Vercel](https://vercel.com/?ref=trycomp.ai)
## Contact us
Contact our founders at hello@trycomp.ai to learn more about how we can help you achieve compliance.
## Stay Up-to-Date
Get access to the cloud hosted version of [Comp AI](https://trycomp.ai).
## Getting Started
To get a local copy up and running, please follow these simple steps.
### Prerequisites
Here is what you need to be able to run Comp AI.
- Node.js (Version: >=20.x)
- Bun (Version: >=1.1.36)
- Postgres (Version: >=15.x)
## Development
To get the project working locally with all integrations, follow these extended development steps
### Setup
## Add environment variables and fill them out with your credentials
\`\`\`sh
cp apps/app/.env.example apps/app/.env
cp apps/portal/.env.example apps/portal/.env
cp packages/db/.env.example packages/db/.env
\`\`\`
## Get code running locally
1. Clone the repo
\`\`\`sh
git clone https://github.com/trycompai/comp.git
\`\`\`
2. Navigate to the project directory
\`\`\`sh
cd comp
\`\`\`
3. Install dependencies using Bun
\`\`\`sh
bun install
\`\`\`
4. Get Database Running
\`\`\`sh
cd packages/db
bun run docker:up # Spin up docker container
bun run db:migrate # Run migrations
\`\`\`
5. Generate Prisma Types for each app
\`\`\`sh
cd apps/app
bun run db:generate
cd ../
\`\`\`