Project Structure

Understand the CodePilot monorepo layout — apps, packages, and how they work together.

CodePilot is organized as a Turborepo monorepo with pnpm workspaces. This page documents the directory structure and the role of each package.

Top-Level Structure

docker-compose.yml

docker-compose.prod.yml

turbo.json

pnpm-workspace.yaml

Applications

`apps/api` — Express REST API

The API server handles all HTTP requests, authentication, and job enqueueing.

apps/api/src/
├── modules/        # Feature modules (auth, ai, github, repository, user)
├── queue/          # BullMQ job producers
├── routes/         # Express route definitions
├── middlewares/    # Auth, rate-limiting, error handling, logging
├── jobs/           # Scheduled cron jobs
└── index.ts        # Server entry point

Key responsibilities:

GitHub OAuth login and session management
REST API endpoints for repositories, users, and AI chat
BullMQ job producers for repository ingestion
GitHub webhook handlers for push events and PR reviews
Zod request validation middleware

`apps/web` — Next.js Frontend

The frontend is a Next.js 16 application using React 19, Tailwind CSS, and shadcn/ui.

apps/web/
├── app/            # App Router (dashboard, marketing pages)
├── components/     # React components
├── hooks/          # Custom React hooks
├── store/          # Zustand state management
├── providers/      # Context providers
└── Dockerfile

`apps/worker` — Background Job Processor

The worker consumes BullMQ jobs for repository ingestion, embedding generation, and AI-powered PR reviews.

apps/worker/src/
├── infrastructure/     # BullMQ consumers & processors
├── service/            # Core services (ai, github, repository, email)
├── internal-queue/     # Internal job orchestration
└── index.ts            # Worker entry point

`apps/docs` — Documentation

This documentation site, built with Fumadocs and Next.js.

Packages

`packages/database` (`@repo/db`)

Contains the Prisma schema, database migrations, and the generated Prisma client. All apps that need database access import from @repo/db.

packages/database/
├── prisma/
│   ├── schema.prisma    # Database schema
│   └── migrations/      # Migration history
├── src/
│   └── index.ts         # Re-exports Prisma client
└── package.json

`packages/shared` (`@repo/shared`)

Shared TypeScript types, Zod schemas, constants, and utility functions used across all applications.

`packages/ui` (`@repo/ui`)

Reusable React components shared between the web app and potentially other frontends.

`packages/eslint-config`

Shared ESLint configuration extending Next.js and TypeScript rules. Used by all apps via workspace dependencies.

`packages/typescript-config`

Base TypeScript configuration (tsconfig.json) that all apps extend. Ensures consistent compiler settings across the monorepo.

Turborepo Configuration

Turborepo orchestrates builds, linting, and development across the monorepo. The turbo.json configuration defines task dependencies:

turbo.json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}

Workspace Configuration

The pnpm workspace is defined in pnpm-workspace.yaml:

pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

This allows any app or package to reference others using workspace protocol:

{
  "dependencies": {
    "@repo/db": "workspace:*",
    "@repo/shared": "workspace:*",
    "@repo/ui": "workspace:*"
  }
}

On this page