From 99fdd17287c40b466ab15b60089e65951a038404 Mon Sep 17 00:00:00 2001
From: defiQUG <defi@defi-oracle.io>
Date: Thu, 13 Nov 2025 09:38:20 -0800
Subject: [PATCH] docs: add comprehensive development setup guide

---
 docs/DEVELOPMENT_SETUP.md | 281 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 281 insertions(+)
 create mode 100644 docs/DEVELOPMENT_SETUP.md

diff --git a/docs/DEVELOPMENT_SETUP.md b/docs/DEVELOPMENT_SETUP.md
new file mode 100644
index 0000000..8bd34e7
--- /dev/null
+++ b/docs/DEVELOPMENT_SETUP.md
@@ -0,0 +1,281 @@
+# 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