Skip to main content

Monorepo Structure

CORTEX uses Turborepo with pnpm workspaces for monorepo management.

Directory Layout​

cortex-platform/
├── apps/                         # Applications
│   ├── cortex-web/               # Next.js frontend
│   ├── cortex-core/              # NestJS backend
│   ├── cortex-api-gateway/       # API gateway (future)
│   ├── cortex-agent-runner/      # Go service (future)
│   └── docs/                     # Documentation (Docusaurus)
│
├── packages/                     # Shared packages
│   ├── shared-types/             # TypeScript types
│   ├── ui-components/            # React components
│   ├── utils/                    # Utility functions
│   ├── eslint-config/            # ESLint config
│   └── tsconfig/                 # TypeScript configs
│
├── infra/                        # Infrastructure
│   ├── terraform/                # IaC modules
│   └── docker/                   # Docker configs
│
├── pipelines/                    # CI/CD
│   └── azure-pipelines.yml
│
├── docs/                         # Project docs
│   └── *.md
│
├── turbo.json                    # Turborepo config
├── pnpm-workspace.yaml           # Workspace definition
└── package.json                  # Root package

Workspace Configuration​

pnpm-workspace.yaml​

packages:
  - 'apps/*'
  - 'packages/*'

turbo.json​

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Package Dependencies​

┌────────────────┐
│  cortex-web    │
│  (Next.js)     │
└───────┬────────┘
        │
        ├─────────────────────┐
        │                     │
        ▼                     ▼
┌────────────────┐   ┌────────────────┐
│ ui-components  │   │ shared-types   │
└────────────────┘   └───────┬────────┘
                             │
                             │
        ┌────────────────────┤
        │                    │
        ▼                    ▼
┌────────────────┐   ┌────────────────┐
│  cortex-core   │   │    utils       │
│  (NestJS)      │   │                │
└────────────────┘   └────────────────┘

Application Details​

cortex-core​

apps/core/
├── prisma/
│   ├── schema.prisma        # Database schema
│   ├── migrations/          # Migration files
│   └── seed.ts              # Seed data
├── src/
│   ├── main.ts              # Entry point
│   ├── app.module.ts        # Root module
│   ├── common/              # Shared code
│   │   ├── decorators/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   └── filters/
│   └── modules/             # Feature modules
│       ├── auth/
│       ├── tenant/
│       ├── organization/
│       ├── user/
│       ├── rbac/
│       ├── audit/
│       └── health/
└── test/
    ├── unit/
    └── functional/

cortex-web​

apps/cortex-web/
├── src/
│   ├── app/                 # Next.js app router
│   ├── components/          # React components
│   ├── hooks/               # Custom hooks
│   ├── services/            # API services
│   ├── stores/              # Zustand stores
│   └── utils/               # Utilities
├── public/                  # Static assets
└── next.config.js           # Next.js config

Shared Packages​

shared-types​

// packages/shared-types/src/user.ts
export interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  tenantId: string;
  status: UserStatus;
}

export enum UserStatus {
  ACTIVE = 'ACTIVE',
  SUSPENDED = 'SUSPENDED',
  INACTIVE = 'INACTIVE',
}

ui-components​

// packages/ui-components/src/Button.tsx
export interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant, children, onClick }: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
}

Commands​

Root Level​

# Install all dependencies
pnpm install

# Build all packages
pnpm build

# Run all tests
pnpm test

# Lint all packages
pnpm lint

# Start all dev servers
pnpm dev

Package Specific​

# Run command in specific package
pnpm --filter core dev
pnpm --filter cortex-web build

# Run command in multiple packages
pnpm --filter "./apps/*" build

Adding a New Package​

  1. Create directory:

    mkdir packages/my-package

  2. Initialize package.json:

    {
      "name": "@cortex/my-package",
      "version": "0.0.0",
      "main": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }

  3. Package is automatically detected by pnpm workspace.

  4. Use in other packages:

    {
      "dependencies": {
        "@cortex/my-package": "workspace:*"
      }
    }