Development

Development Setup

Setting up your local development environment for contributing to Cortex.

Overview

This guide covers setting up a local development environment for contributing to the Cortex project. If you're looking to use Cortex in your project, see the Installation Guide instead.

Prerequisites

System Requirements

Operating System: Linux, macOS, or Windows (WSL2)
Python: 3.12+ (required)
Node.js: 18+ (for Studio development)
Git: 2.34+ (for version control)
PostgreSQL: 13+ (for metadata storage)

Required Tools

Python and Poetry

# Install Python 3.12+
# macOS with Homebrew
brew install python@3.12

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-pip

# Install Poetry for dependency management
curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"

# Verify installation
python3.12 --version
poetry --version

Node.js (for Studio Development)

# macOS with Homebrew
brew install node@18

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Project Setup

1. Clone Repository

# Clone the repository
git clone https://github.com/TelescopeAI/cortex.git
cd cortex

# Verify clone
ls -la

2. Backend Development Setup

Install Dependencies

# Install all dependencies (main, API, dev, test)
poetry install

# For development with API support
poetry install --with api

# Verify installation
poetry show

Environment Configuration

Setting up development environment variables

# Copy local environment file
cp local.env .env

# Edit environment variables if needed
nano local.env

Example local.env configuration:

ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
EXECUTION_ENV=local
CORE_DB_TYPE=postgresql+psycopg
CORE_DB_USERNAME=root
CORE_DB_PASSWORD=password
CORE_DB_HOST=localhost
CORE_DB_PORT=5432
CORE_DB_NAME=cortex
API_BASE_URL=http://localhost:9002
CORTEX_CACHE_ENABLED=true
CORTEX_CACHE_BACKEND=redis
CORTEX_CACHE_REDIS_URL=redis://localhost:6379
CORTEX_PREAGGREGATIONS_ENABLED=false

Database Setup

PostgreSQL setup and migration process

# Install PostgreSQL
# macOS with Homebrew
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt install postgresql-15 postgresql-contrib-15
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create development database and user
createdb cortex
psql -c "CREATE USER root WITH PASSWORD 'password';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE cortex TO root;"

# Run database migrations
# Migrations are auto-applied when starting the API server with CORTEX_AUTO_APPLY_DB_MIGRATIONS=true
# For manual migration, use:
poetry shell
cd cortex/migrations && alembic upgrade head

# Verify setup
psql -h localhost -U root -d cortex -c "SELECT version();"

Start Backend Server

# Activate poetry shell
poetry shell

# Start API server with auto-reload
python -m cortex.api

# Alternative: Start with uvicorn directly
uvicorn cortex.api.main:app --reload --host 0.0.0.0 --port 9002

# Verify server is running
curl http://localhost:9002/health

The API server will be available at http://localhost:9002

3. Studio Development Setup

Studio frontend development setup

Install Studio Dependencies

# Navigate to Studio directory
cd frontend/cortex

# Install dependencies with yarn (recommended)
yarn install

# Or with npm
npm install

# Verify installation
yarn list --depth=0

Configure Studio Environment

Studio gets its configuration from the nuxt.config.ts file. The API base URL is set to http://localhost:9002 by default.

You can override this by setting environment variables:

# Set API base URL (optional)
export API_BASE_URL="http://localhost:9002"

Start Studio Development Server

# Start development server
yarn dev

# Or with npm
npm run dev

# Verify Studio is running
curl http://localhost:3000

Studio will be available at http://localhost:3000

Development Workflow

Complete development workflow from setup to deployment

Backend Development

# Activate poetry shell
poetry shell

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=cortex --cov-report=html

# Run linting
poetry run black cortex/
poetry run isort cortex/
poetry run flake8 cortex/

# Type checking
poetry run mypy cortex/

# Database operations (run from cortex/migrations directory)
cd cortex/migrations
alembic revision --autogenerate -m "migration description"
alembic upgrade head
alembic downgrade -1

Studio Development

# Install dependencies
yarn install

# Start development server
yarn dev

# Build for production
yarn build

# Preview production build
yarn preview

# Generate static files
yarn generate

# Run linting and formatting
yarn lint
yarn lint:fix

# Type checking
yarn typecheck

IDE Configuration

VS Code configuration for Cortex development

Visual Studio Code

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  },
  "[typescript]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Create .vscode/extensions.json:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.black-formatter",
    "ms-python.isort",
    "ms-python.mypy-type-checker",
    "vue.volar",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss"
  ]
}

Testing

Comprehensive testing approach for both backend and frontend

Backend Testing

# Run all tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=cortex --cov-report=html --cov-report=term

# Run specific test categories
poetry run pytest tests/unit/
poetry run pytest tests/integration/
poetry run pytest tests/api/

# Run tests in parallel
poetry run pytest -n auto

Studio Testing

# Run unit tests
yarn test:unit

# Run end-to-end tests
yarn test:e2e

# Run tests in watch mode
yarn test:unit:watch

# Generate coverage reports
yarn test:coverage

Architecture Overview

The project follows a modular monorepo structure:

High-level architecture showing core components and their relationships

Core Components

API Layer (cortex/api/): FastAPI-based REST API server
Core Engine (cortex/core/): Business logic and semantic layer
Studio Interface (frontend/cortex/): Vue.js/Nuxt.js admin interface
Database Layer: PostgreSQL for metadata storage

Technology Stack

Component	Technology	Purpose
Backend Framework	FastAPI	REST API development with async support
Data Validation	Pydantic	Type safety and data validation
Database ORM	SQLAlchemy 2.0	Database abstraction and query building
Database Driver	psycopg3	PostgreSQL connectivity
Migrations	Alembic	Database schema management
Frontend Framework	Nuxt.js 4 + Vue.js 3	Studio interface
UI Components	Shadcn/ui + Reka UI	Component library
Chart Library	ECharts	Data visualization
Form Validation	VeeValidate + Zod	Form handling and validation
Styling	Tailwind CSS	Utility-first CSS framework
Package Manager	Poetry (Python), Yarn (Node.js)	Dependency management

Contributing

Step-by-step contribution workflow

Development Workflow

Fork the repository

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes

Run tests and linting

poetry run pytest
poetry run black cortex/
yarn lint

Commit your changes

git add .
git commit -m "feat: add your feature description"

Push to your fork

git push origin feature/your-feature-name

Create a Pull Request

Code Quality

Pre-commit Hooks

# Install pre-commit
poetry run pre-commit install

# Run pre-commit on all files
poetry run pre-commit run --all-files

Troubleshooting

Common development issues and their solutions

Common Issues

Poetry Issues

# Clear Poetry cache
poetry cache clear --all pypi

# Reinstall dependencies
poetry lock --no-update
poetry install --sync

# Update Poetry
poetry self update

Database Issues

# Check database connection
psql -h localhost -U root -d cortex -c "SELECT 1;"

# Reset database (run from cortex/migrations directory)
cd cortex/migrations
alembic downgrade base
alembic upgrade head

# Check migration status
alembic current
alembic history

Studio Issues

# Clear node_modules and reinstall
rm -rf node_modules yarn.lock
yarn install

# Clear Nuxt cache
rm -rf .nuxt

# Check for port conflicts
lsof -ti:3000
kill -9 $(lsof -ti:3000)

API Server Issues

# Check if API server is running
curl http://localhost:9002/health

# Check for port conflicts
lsof -ti:9002
kill -9 $(lsof -ti:9002)

# Start with verbose logging
python -m cortex.api --log-level debug

Getting Help

If you encounter issues during development:

Check existing issues: GitHub Issues
Review documentation: Cortex Docs
Community forum: Join our community discussions
Stack Overflow: Tag questions with cortex-analytics

Next Steps

Explore Architecture: Learn about Cortex architecture
Studio Development: Understand Studio patterns
API Reference: Review API documentation
Contributing Guidelines: Read the full contributing guide in the repository

Edit this pageorReport an issue

Data Flow

Understanding how data flows through Studio's reactive architecture and component hierarchy.