# Development

> Daily development workflows, tools, and best practices

## 📋 Overview

This section covers everything you need for day-to-day development with Izri, from setting up your local environment to debugging complex issues. Whether you're fixing bugs, adding features, or optimizing performance, you'll find the guidance you need here.

## 🎯 What You'll Learn

- ✅ How to set up your development environment
- ✅ Managing environment variables and configuration
- ✅ Running and managing services
- ✅ Database operations and migrations
- ✅ Debugging techniques and tools
- ✅ Testing strategies and execution
- ✅ Code quality and linting

## 📚 Documentation Pages

### [Local Setup](./local-setup.md)

**Complete development environment configuration**

Topics covered:

- IDE setup (VS Code recommended)
- Extensions and plugins
- Git configuration
- Shell setup and aliases
- Performance optimization
- Recommended tools

### [Environment Variables](./environment-variables.md)

**Managing configuration across services**

Topics covered:

- Environment file structure
- Required vs optional variables
- Service-specific configuration
- Secrets management
- Development vs production configs
- Environment variable reference

### [Environment Management](./environment-management.md)

**Automated environment variable management system**

Topics covered:

- Centralized `.env.shared` configuration
- Auto-generation of project-specific `.env` files
- TypeScript configuration with type safety
- Validation and watch mode
- CI/CD integration

### [Utility Scripts](./utility-scripts.md)

**Automation scripts and development tools**

Topics covered:

- Available utility scripts
- Creating new scripts
- TypeScript script templates
- Best practices and patterns
- Common script examples
- Debugging scripts

### [Running Services](./running-services.md)

**Starting, stopping, and managing development services**

Topics covered:

- Starting all services
- Running individual services
- Service dependencies
- Port management
- Logs and output
- Restart and reload strategies
- Process management

### [Database Management](./database-management.md)

**Working with PostgreSQL and Drizzle ORM**

Topics covered:

- Schema development
- Migration workflow
- Seeding and test data
- Drizzle Studio usage
- Database inspection
- Backup and restore
- Query optimization
- Troubleshooting connections

### [Debugging](./debugging.md)

**Techniques and tools for troubleshooting**

Topics covered:

- Frontend debugging (React DevTools, Vite inspect)
- Backend debugging (Node.js inspector, logs)
- Database debugging (query logs, Drizzle Studio)
- Network debugging (tRPC traces, HTTP inspector)
- Performance profiling
- Common issues and solutions

### [Testing](./testing.md)

**Testing strategies and running tests**

Topics covered:

- Test structure and organization
- Unit testing
- Integration testing
- E2E testing (planned)
- Test data management
- Running tests
- Coverage reports
- CI/CD integration

## 🚀 Quick Reference

### Daily Commands

```bash
# Start everything
pnpm dev

# Start individual services
pnpm dev:web        # Frontend only
pnpm dev:api        # Backend only
pnpm dev:packages   # All packages (including AI service)

# Infrastructure
pnpm dev:docker     # Start PostgreSQL & Redis
pnpm docker:down    # Stop Docker services
pnpm docker:logs    # View Docker logs

# Database
pnpm db:studio      # Open Drizzle Studio
pnpm db:generate    # Generate migrations
pnpm db:migrate     # Apply migrations
pnpm db:seed        # Seed test data

# Environment
pnpm env:generate   # Generate .env files from .env.shared
pnpm env:check      # Check if .env files are up to date
pnpm env:watch      # Watch and auto-regenerate .env files

# Code quality
pnpm lint           # Run linting
pnpm type:check     # TypeScript check
pnpm format:all     # Format code
pnpm test           # Run tests

# Building
pnpm build          # Build all packages
pnpm clean          # Clean build artifacts
```

### Service Ports

| Service | Port | URL |
|---------|------|-----|
| Web Dashboard | 5173 | <http://localhost:5173> |
| API Server | 4000 | <http://localhost:4000> |
| AI Service | 8000 | <http://localhost:8000> |
| PostgreSQL | 5433 | localhost:5433 |
| Redis | 6380 | localhost:6380 |
| Drizzle Studio | 4983 | <http://localhost:4983> |

### Environment Files

| File | Purpose |
|------|---------|
| `.env.shared` | Centralized configuration - single source of truth (gitignored) |
| `.env.shared.example` | Template with all available variables (committed) |
| `env.config.ts` | Configuration defining which projects use which variables (committed) |
| `apps/web/.env` | Auto-generated from `.env.shared` (gitignored) |
| `apps/api/.env` | Auto-generated from `.env.shared` (gitignored) |
| `packages/*/.env` | Auto-generated where needed (gitignored) |

**Note**: Never edit generated `.env` files directly. Always update `.env.shared` and run `pnpm env:generate`.

## 🔧 Development Workflow

### Typical Development Day

```bash
# 1. Start your day - pull latest changes
git pull origin main

# 2. Install any new dependencies
pnpm install

# 3. Apply any new migrations
pnpm db:migrate

# 4. Start infrastructure
pnpm dev:docker

# 5. Start all services
pnpm dev

# 6. Open your editor and start coding
code .

# 7. Make changes, test, commit, push
git add .
git commit -m "feat: add new feature"
git push

# 8. End your day - stop services
# Ctrl+C to stop pnpm dev
pnpm docker:down
```

### Feature Development Workflow

```mermaid
graph TD
    A[Create Feature Branch] --> B[Make Changes]
    B --> C{Need DB Changes?}
    C -->|Yes| D[Update Schema]
    C -->|No| E[Write Code]
    D --> F[Generate Migration]
    F --> E
    E --> G[Test Locally]
    G --> H{Tests Pass?}
    H -->|No| B
    H -->|Yes| I[Commit Changes]
    I --> J[Push Branch]
    J --> K[Create PR]
```

### Database Change Workflow

```bash
# 1. Update schema
# Edit packages/database/src/schema.ts

# 2. Generate migration
pnpm db:generate

# 3. Review generated SQL
# Check packages/database/migrations/

# 4. Apply migration locally
pnpm db:migrate

# 5. Test the changes
pnpm db:studio  # Verify schema

# 6. Update seed script if needed
# Edit packages/database/src/seed.ts

# 7. Test seeding
pnpm db:seed

# 8. Commit migration files
git add packages/database/migrations/
git commit -m "feat: add new table"
```

## 🐛 Common Development Tasks

### Adding a New Package Dependency

```bash
# Add to specific workspace package
pnpm --filter @izri/web add react-query

# Add to all packages
pnpm add -w some-shared-tool

# Add as dev dependency
pnpm --filter @izri/api add -D @types/node
```

### Creating a New Workspace Package

```bash
# 1. Create package directory
mkdir packages/my-new-package

# 2. Create package.json
cd packages/my-new-package
pnpm init

# 3. Update package.json with workspace config
# Add "name": "@izri/my-new-package"

# 4. Create src/ and tsconfig.json

# 5. Add to pnpm-workspace.yaml (if needed)

# 6. Install from root
cd ../..
pnpm install
```

### Clearing Cache and Rebuilding

```bash
# Nuclear option - complete clean
pnpm clean
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install
pnpm build

# Turbo cache clean
rm -rf .turbo

# pnpm store clean
pnpm store prune

# Docker volume clean
pnpm docker:down -v
```

## 🎯 IDE Setup

### VS Code (Recommended)

**Required Extensions**:

- ESLint
- Prettier - Code formatter
- TypeScript and JavaScript Language Features
- Tailwind CSS IntelliSense

**Recommended Extensions**:

- Docker
- Database Client JDBC
- GitLens
- Error Lens
- Auto Rename Tag
- Path Intellisense

**Settings** (`.vscode/settings.json`):

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}
```

## 📊 Performance Tips

### Build Performance

```bash
# Use Turbo caching
pnpm build  # First build: ~20s
pnpm build  # Cached build: <5s

# Build only what changed
pnpm build --filter=@izri/web

# Skip type checking for faster builds (dev only)
# Edit tsconfig.json: "skipLibCheck": true
```

### Development Server Performance

```bash
# Use pnpm workspace links
# Already configured in package.json

# Enable SWC/ESBuild if available
# Already using Vite with ESBuild

# Reduce file watching
# Add to .gitignore: node_modules, .turbo, dist, lib
```

## 🔗 Related Documentation

- **Getting Started**: [Installation Guide](../getting-started/installation.md)
- **Architecture**: [System Overview](../architecture/overview.md)
- **Frontend**: [Frontend Development](../frontend/README.md)
- **Backend**: [Backend Development](../backend/README.md)

## 🆘 Troubleshooting

### Services Won't Start

1. Check if ports are available: `lsof -ti:5173`
2. Ensure Docker is running: `docker ps`
3. Check environment variables: `cat .env`
4. Review logs for errors: `pnpm docker:logs`

### Build Errors

1. Clean and rebuild: `pnpm clean && pnpm install && pnpm build`
2. Check Node version: `node --version` (should be 18+)
3. Check pnpm version: `pnpm --version` (should be 8+)
4. Clear Turbo cache: `rm -rf .turbo`

### Database Connection Issues

1. Ensure PostgreSQL is running: `docker ps | grep postgres`
2. Check DATABASE_URL in .env
3. Restart Docker: `pnpm docker:down && pnpm dev:docker`
4. Check migrations: `pnpm db:migrate`

---

*Ready to dive deep? Start with [Local Setup](./local-setup.md) →*