Project Structure

CORTEX uses a Turborepo monorepo with pnpm workspaces. This guide explains the directory structure and how packages relate to each other.

Root Structure

cortex-platform/
├── apps/                    # Application services
├── packages/                # Shared packages
├── infra/                   # Infrastructure as Code
├── pipelines/               # CI/CD pipeline definitions
├── docs/                    # Project documentation
├── scripts/                 # Utility scripts
├── requirements/            # Requirements documents
├── turbo.json               # Turborepo configuration
├── pnpm-workspace.yaml      # pnpm workspace config
└── package.json             # Root package.json

Applications (apps/)

App	Technology	Port	Description
cortex-web	Next.js 14	3090	Frontend application
cortex-api-gateway	NestJS 10	8090	API gateway (future)
cortex-core	NestJS 10	8091	Core business logic
cortex-agent-runner	Go 1.22+	9090	AI agent execution (future)
cortex-integration-workers	NestJS 10	8092	Background workers (future)
docs	Docusaurus	3000	Documentation portal

Core Service Structure (apps/core/)

apps/core/
├── prisma/
│   ├── schema.prisma        # Database schema
│   ├── migrations/          # Database migrations
│   └── seed.ts              # Seed data script
├── src/
│   ├── main.ts              # Application entry point
│   ├── app.module.ts        # Root module
│   ├── common/              # Shared utilities
│   │   ├── decorators/      # Custom decorators
│   │   ├── guards/          # Auth guards
│   │   ├── interceptors/    # Request interceptors
│   │   └── filters/         # Exception filters
│   └── modules/             # Feature modules
│       ├── auth/            # Authentication
│       ├── tenant/          # Tenant management
│       ├── organization/    # Organization management
│       ├── user/            # User management
│       ├── rbac/            # Role-based access control
│       ├── audit/           # Audit logging
│       └── health/          # Health checks
├── test/
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── functional/          # End-to-end functional tests
└── package.json

Shared Packages (packages/)

Package	Description
shared-types	TypeScript type definitions shared across apps
ui-components	Shared React components for the frontend
utils	Common utility functions
eslint-config	Shared ESLint configuration
tsconfig	Shared TypeScript configurations

Package Dependencies

┌──────────────┐     ┌──────────────┐
│ cortex-web   │────▶│ ui-components│
│              │     └──────────────┘
│              │            │
│              │            ▼
│              │────▶┌──────────────┐
│              │     │ shared-types │◀────┐
└──────────────┘     └──────────────┘     │
                            ▲             │
┌──────────────┐            │             │
│ cortex-core  │────────────┴─────────────┤
└──────────────┘                          │
                                          │
┌──────────────┐                          │
│ cortex-api-  │──────────────────────────┘
│ gateway      │
└──────────────┘

Infrastructure (infra/)

infra/
├── terraform/               # Terraform modules
│   ├── modules/             # Reusable modules
│   │   ├── networking/      # VNet, subnets
│   │   ├── database/        # PostgreSQL
│   │   ├── redis/           # Redis cache
│   │   └── app-service/     # Container apps
│   └── environments/        # Environment configs
│       ├── dev/
│       ├── staging/
│       └── prod/
└── docker/
    ├── docker-compose.yml   # Local development
    └── Dockerfile.*         # Service Dockerfiles

Module Architecture

Each NestJS module follows a consistent structure:

modules/auth/
├── auth.module.ts           # Module definition
├── auth.controller.ts       # HTTP endpoints
├── auth.service.ts          # Business logic
├── dto/                     # Data Transfer Objects
│   ├── login.dto.ts
│   ├── register.dto.ts
│   └── index.ts
├── entities/                # Prisma model extensions
├── guards/                  # Module-specific guards
└── strategies/              # Passport strategies

Key Files

File	Purpose
turbo.json	Defines build pipeline and task dependencies
pnpm-workspace.yaml	Lists workspace packages
prisma/schema.prisma	Database schema (single source of truth)
.env	Environment variables (not committed)
.env.example	Template for environment variables

Development Workflow

# Install all dependencies
pnpm install

# Start all services in dev mode
pnpm dev

# Run tests across all packages
pnpm test

# Build all packages
pnpm build

# Lint all packages
pnpm lint

Adding a New Module

1. Create the module directory:

   mkdir -p apps/core/src/modules/my-feature

2. Create module files following the standard structure

3. Register in app.module.ts:

   @Module({
     imports: [
       // ...
       MyFeatureModule,
     ],
   })
   export class AppModule {}

4. Update Prisma schema if needed:

   cd apps/core
   pnpm db:migrate