# 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

```bash
# 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:

   ```bash
   # 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:
   ```bash
   source infra/scripts/azure-load-env.sh
   ```

## Development Workflow

### Running Services

```bash
# Start all services
pnpm dev

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

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

### Building

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
docker-compose up -d
```

Services available:

- **PostgreSQL**: `localhost:5432`
- **Redis**: `localhost:6379`
- **OpenSearch**: `localhost:9200`

Stop services:

```bash
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](https://www.conventionalcommits.org/):

- `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:

```bash
# 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

```bash
# 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:

```bash
# Find process using port
lsof -i :4002

# Kill process
kill -9 <PID>
```

### Dependency Issues

```bash
# 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`:

```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](../PROJECT_STRUCTURE.md)
   - [Architecture](../docs/architecture/README.md)
   - [Navigation Guide](../docs/NAVIGATION.md)

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