Overview GAIA uses Nx to manage commands across the monorepo. All commands follow the pattern nx <target> <project> or nx run-many -t <target> for multiple projects.
Quick Reference
Development Start development servers with hot reload
Building Build projects for production
Quality Checks Lint, format, and type check code
Testing Run tests and verify functionality
Setup Commands Install Dependencies Install Node.js dependencies using pnpm:
Sync Python Dependencies Sync Python packages for API and voice agent:
This uses uv to install dependencies defined in pyproject.toml into isolated virtual environments.
Development Commands Start Development Servers Run applications with hot reload:
Web App
API Backend
Desktop App
Mobile App
Voice Agent
nx dev web # Runs on http://localhost:3000 # Uses Next.js with Turbopack for fast refresh
Run Background Workers Start background task workers for async job processing:
nx worker api # Runs ARQ worker for Redis-based task queue
The worker processes background tasks like:
Email processing
Scheduled jobs
Long-running operations
Webhook deliveries
Docker Development Start All Services Start all infrastructure services with Docker Compose:
cd infra/docker docker compose up
This starts PostgreSQL, MongoDB, Redis, ChromaDB, and RabbitMQ.
Start Specific Profiles Run only the services you need:
Backend Services
Worker Services
Voice Services
docker compose --profile backend up # PostgreSQL, MongoDB, Redis, ChromaDB
Stop Services docker compose down # Stop and remove containers docker compose down -v # Also remove volumes (deletes all data)
The -v flag removes volumes, which will delete all data in your local databases. Use this carefully.
Build Commands Build Individual Projects Build specific projects for production:
Web App
API Backend
Desktop App
Mobile App
nx build web # Creates optimized Next.js production build # Output: apps/web/.next
Build Multiple Projects Build all projects in parallel:
nx run-many -t build # Builds all projects that have a build target # Runs up to 3 in parallel (configured in nx.json)
Build specific projects:
nx run-many -t build -p web,api # Only builds web and api projects
Quality Commands Linting Check code for style and quality issues:
Lint All
Lint Specific
Lint and Fix
nx run-many -t lint # Lints all projects
Frontend linting uses Biome (replaces ESLint + Prettier):nx lint web # Checks JavaScript/TypeScript with Biome
Backend linting uses Ruff (extremely fast Python linter):nx lint api # Runs: uvx ruff check .
Format code according to project standards:
Format All
Format Specific
Check Formatting
nx run-many -t format # Formats all projects
Frontend formatting uses Biome:
Line width: 80 characters
Indentation: 2 spaces
Automatic import sorting
Backend formatting uses Ruff:
Follows PEP 8 style guide
Line width: 88 characters (Black-compatible)
Automatic import sorting
Type Checking Verify type safety:
Type Check All
Type Check Specific
nx run-many -t type-check
Frontend uses TypeScript compiler:nx type-check web # Runs: tsc --noEmit
Backend uses mypy:nx type-check api # Runs: mypy app --ignore-missing-imports
Run All Quality Checks Run linting, formatting, and type checking together:
nx run-many -t lint format:check type-check # Runs all quality checks in parallel
Quality checks run in parallel by default (max 3 concurrent). This is configured with "parallel": 3 in nx.json.
Testing Commands Python Tests Run pytest tests for Python applications:
cd apps/api uv run pytest # With coverage uv run pytest --cov=app --cov-report=html # Specific test file uv run pytest tests/test_agents.py # With verbose output uv run pytest -v
Frontend Tests If Jest or other test runners are configured:
nx test web nx test mobile
Database Commands Run Migrations Apply database schema changes:
nx run api:migrate # Runs database migrations
Create Migration Generate a new migration file:
cd apps/api uv run alembic revision -m "description"
Docker Commands Build Docker Images Build production Docker images:
API Image
Voice Agent Image
All Images
nx docker:build api # Builds and pushes to ghcr.io
Utility Commands Clean Build Artifacts Remove generated files and caches:
Clean Specific Project
Clean API Artifacts
nx clean web nx clean api
Reset Nx Cache Clear Nx cache if you encounter caching issues:
nx reset # Clears Nx cache and restarts daemon
The Nx daemon is disabled in this project (useDaemonProcess: false), but the cache is still used for faster builds.
View Project Graph Visualize dependencies between projects:
nx graph # Opens interactive dependency graph in browser
See dependencies for a specific project:
nx graph --focus=web # Shows only web app and its dependencies
View Task Graph Visualize task execution order:
nx graph --target=build # Shows build task dependencies
Python-Specific Commands These commands work inside Python app directories:
API Development cd apps/api # Start development server uv run uvicorn app.main:app --reload # Start with custom port uv run uvicorn app.main:app --port 8080 --reload # Run worker uv run arq app.worker.WorkerSettings # Lint uvx ruff check . # Format uvx ruff format . # Type check uv run mypy app --ignore-missing-imports # Tests uv run pytest
Security Checks Run security audits on dependencies:
cd apps/api # Audit dependencies uvx pip-audit # Check for security issues uvx bandit -r app # Detect secrets uvx detect-secrets scan --all-files
Workflow Examples Starting Development Typical workflow to start developing:
# 1. Start infrastructure cd infra/docker && docker compose up -d # 2. Start API nx dev api # 3. In another terminal, start web app nx dev web # 4. In another terminal, start worker nx worker api
Before Committing Run quality checks before committing:
# Check everything nx run-many -t lint format:check type-check # Fix issues nx run-many -t lint:fix format # Verify fixes nx run-many -t lint format:check
Building for Production Prepare for production deployment:
# 1. Run quality checks nx run-many -t lint format:check type-check # 2. Build all projects nx run-many -t build # 3. Build Docker images nx run-many -t docker:build -p api,voice-agent
Troubleshooting When things go wrong:
# Reset everything nx reset pnpm install nx run api:sync nx run voice-agent:sync # Rebuild nx run-many -t build # Restart Docker cd infra/docker docker compose down -v docker compose up -d
Advanced Nx Features Affected Commands Run commands only for affected projects:
# Lint only changed projects nx affected -t lint # Build only affected projects nx affected -t build # Compare against specific branch nx affected -t test --base=origin/master
Parallel Execution Control how many tasks run in parallel:
# Run with max 5 parallel tasks nx run-many -t build --parallel=5 # Run sequentially nx run-many -t build --parallel=1
Output Options Control command output:
# Minimal output nx run-many -t build --output-style=compact # Stream output nx run-many -t build --output-style=stream # Static output (default) nx run-many -t build --output-style=static
Skip Cache Force re-execution without cache:
nx build web --skip-nx-cache
Environment Variables Some commands respect environment variables:
# Development mode NODE_ENV = development nx dev web # Production mode NODE_ENV = production nx build web # Custom API URL NEXT_PUBLIC_API_URL = http://api.example.com nx dev web # Python debug mode PYTHON_ENV = development nx dev api
Next Steps