the_order/docs/DEVELOPMENT_SETUP.md

Development Setup Guide

Last Updated: 2025-01-27
Status: Complete Setup Instructions

Quick Start

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0
• Docker & Docker Compose (for local services)
• Git with SSH configured

Initial Setup

# Clone repository
git clone <repository-url>
cd the-order

# Install dependencies
pnpm install

# Start local services (PostgreSQL, Redis, OpenSearch)
docker-compose up -d

# Build all packages
pnpm build

# Start development servers
pnpm dev

Environment Configuration

.env File Setup

1. Copy .env.example to .env (if available)

2. Configure required variables:

   # Azure Configuration
   AZURE_SUBSCRIPTION_ID="your-subscription-id"
   AZURE_TENANT_ID="your-tenant-id"
   AZURE_LOCATION="westeurope"
   
   # Database
   DATABASE_URL="postgresql://user:pass@localhost:5432/theorder_dev"
   
   # Redis
   REDIS_URL="redis://localhost:6379"
   

3. Load environment:

   source infra/scripts/azure-load-env.sh
   

Development Workflow

Running Services

# Start all services
pnpm dev

# Start specific service
pnpm --filter @the-order/identity-service dev

# Start specific app
pnpm --filter portal-public dev

Building

# Build all packages and services
pnpm build

# Build specific package
pnpm --filter @the-order/database build

# Build specific service
pnpm --filter @the-order/identity-service build

Testing

# Run all tests
pnpm test

# Test specific package
pnpm --filter @the-order/database test

# Test with coverage
pnpm --filter @the-order/database test -- --coverage

Linting

# Lint all code
pnpm lint

# Lint specific package
pnpm --filter @the-order/database lint

# Fix linting issues
pnpm lint --fix

# Batch linting for large file sets
pnpm lint:batch file1.ts file2.ts ...

Type Checking

# Type check all code
pnpm type-check

# Type check specific package
pnpm --filter @the-order/database type-check

Local Development Services

Docker Compose

Start local services:

docker-compose up -d

Services available:

• PostgreSQL: localhost:5432
• Redis: localhost:6379
• OpenSearch: localhost:9200

Stop services:

docker-compose down

Manual Service Setup

See scripts/dev/setup-dev.sh for automated setup.

Git Workflow

Pre-commit Hooks

Husky runs lint-staged on commit:

• ESLint with 4GB memory limit
• Prettier formatting
• Type checking (if configured)

Commit Messages

Use Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• chore: - Maintenance
• refactor: - Code refactoring

Branching Strategy

• main - Production-ready code
• develop - Development branch
• feature/* - Feature branches
• fix/* - Bug fix branches

Troubleshooting

Memory Issues with ESLint

If ESLint runs out of memory:

# Use batch linting script
pnpm lint:batch <files>

# Or increase memory limit manually
NODE_OPTIONS='--max-old-space-size=4096' pnpm lint

Database Connection Issues

# Check PostgreSQL is running
docker-compose ps

# Restart PostgreSQL
docker-compose restart postgres

# Check connection
psql $DATABASE_URL

Port Conflicts

If ports are already in use:

# Find process using port
lsof -i :4002

# Kill process
kill -9 <PID>

Dependency Issues

# Clean install
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Clear Turbo cache
pnpm turbo clean

IDE Setup

VS Code

Recommended extensions:

• ESLint
• Prettier
• TypeScript
• Docker
• GitLens

Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": ["javascript", "typescript", "typescriptreact"],
  "typescript.tsdk": "node_modules/typescript/lib"
}

Next Steps

1. Read Documentation:

   • Project Structure
   • Architecture
   • Navigation Guide

2. Explore Codebase:

   • Start with services/identity/ for backend
   • Check apps/portal-public/ for frontend
   • Review packages/shared/ for utilities

3. Run Tests:

   • Ensure all tests pass
   • Check test coverage
   • Add tests for new features

Getting Help

• Documentation: See docs/ directory
• Architecture: docs/architecture/
• API Docs: Service-specific READMEs
• Issues: GitHub Issues

---

Last Updated: 2025-01-27