Assist_Design/docs/DEVELOPMENT_SETUP.md

# 🛠️ Development Setup Guide

## 🔒 Environment Files Security

### ✅ Safe for Development

Your `.env` files are **automatically excluded** from git commits via `.gitignore`. This means you can:

- ✅ Keep real credentials in `.env` files locally
- ✅ Develop with actual API connections
- ✅ Test with real data safely
- ✅ Never worry about committing secrets

### 📁 Environment File Structure

```
apps/bff/
├── .env                 # Your actual credentials (git ignored)
├── .env.example         # Template with placeholder values (committed)
├── .env.production      # Production template (committed)
└── .env.production.example # Production example (committed)

apps/portal/
├── .env.local           # Your local overrides (git ignored)
├── .env.example         # Template (committed)
└── .env.production      # Production template (committed)
```

## 🚀 Quick Setup

### 1. Backend Environment Setup

```bash
cd apps/bff
cp .env.example .env
nano .env  # Update with your actual values
```

### 2. Frontend Environment Setup

```bash
cd apps/portal
cp .env.example .env.local
nano .env.local  # Update if needed (usually defaults are fine)
```

### 3. Salesforce Private Key

```bash
# Create secrets directory if not exists
mkdir -p secrets

# Add your Salesforce private key
nano secrets/sf-private.key
chmod 600 secrets/sf-private.key
```

## 🔧 Configuration Checklist

### Backend (.env)
- [ ] `DATABASE_URL` - Your PostgreSQL connection
- [ ] `REDIS_URL` - Your Redis connection  
- [ ] `WHMCS_BASE_URL` - Your WHMCS installation URL
- [ ] `WHMCS_API_IDENTIFIER` - Your WHMCS API identifier
- [ ] `WHMCS_API_SECRET` - Your WHMCS API secret
- [ ] `SF_LOGIN_URL` - Salesforce login URL
- [ ] `SF_CLIENT_ID` - Salesforce Connected App consumer key
- [ ] `SF_USERNAME` - Salesforce integration user email
- [ ] `JWT_SECRET` - Generate with: `openssl rand -hex 64`

### Frontend (.env.local)
- [ ] `NEXT_PUBLIC_API_BASE` - Usually `http://localhost:4000` for development

## 🎯 Development Commands

```bash
# Install dependencies
pnpm install

# Start development servers
pnpm dev

# Type checking
pnpm type-check

# Build for production test
pnpm build
```

## 🔒 Security Best Practices

### ✅ DO:
- Keep `.env` files for local development
- Use strong, unique passwords
- Generate secure JWT secrets
- Set proper file permissions (`chmod 600`) for private keys
- Test with real but non-production data when possible

### ❌ DON'T:
- Ever commit `.env` files to git
- Share credentials in chat/email
- Use production secrets in development
- Hardcode secrets in source code
- Use weak or default passwords

## 🚨 If You Accidentally Commit Secrets

1. **Immediately rotate** all exposed credentials
2. **Remove from git history**:
   ```bash
   git filter-branch --force --index-filter \
     "git rm --cached --ignore-unmatch path/to/secret/file" \
     --prune-empty --tag-name-filter cat -- --all
   ```
3. **Force push** to overwrite history: `git push --force`
4. **Update** all team members

## 🌍 Environment-Specific Configuration

### Development
- Uses `.env` files
- Connects to local/development services
- Verbose logging enabled
- CORS permissive for localhost

### Production
- Uses environment variables from deployment platform
- Connects to production services
- Structured logging
- Strict CORS and security headers

## 🛠️ Troubleshooting

### "Environment variable not found"
1. Check `.env` file exists and has the variable
2. Restart development server
3. Check variable name spelling

### "Database connection failed"
1. Verify PostgreSQL is running
2. Check `DATABASE_URL` format
3. Test connection manually

### "Salesforce authentication failed"
1. Verify private key file exists and permissions
2. Check Connected App configuration
3. Verify user permissions in Salesforce

### "WHMCS API errors"
1. Verify API credentials are correct
2. Check IP whitelist in WHMCS
3. Test API endpoints manually with curl

## 📖 Additional Resources

- [Environment Configuration Guide](./ENVIRONMENT_CONFIGURATION.md)
- [Quick Start Deployment Guide](./QUICK_START.md)
- [Plesk Deployment Guide](./PLESK_DEPLOYMENT.md)
- [Salesforce Setup Guide](./SALESFORCE_SETUP.md)
- [WHMCS Integration Guide](./WHMCS_INTEGRATION.md)