Assist_Design/docs/GETTING_STARTED.md

# 🚀 Getting Started with Customer Portal

## ✅ **Environment File Options**

We provide **environment-specific templates** for easy setup:

### 📁 **Available Templates:**

- 🔸 **`.env.example`** - Standard environment template for all environments
- 🔸 **Environment-specific values** - Adjust settings based on development vs production needs

### 🎯 **Benefits:**

- ✅ **Environment-specific**: Clear separation of dev vs prod
- ✅ **Secure defaults**: Production uses strong security settings
- ✅ **Easy setup**: Copy the right template for your needs
- ✅ **No confusion**: Clear instructions for each environment

## 🔧 **Environment File Structure**

```
📦 Customer Portal
├── .env.example          # 🔸 Environment template
├── .env                  # ✅ Your actual config (gitignored)
├── apps/
│   ├── bff/             # 🚀 Backend reads from root .env
│   └── portal/          # 🚀 Frontend reads from root .env
└── ...
```

**How it works:**

- **Frontend (Next.js)**: Automatically reads `.env` from project root
- **Backend (NestJS)**: Automatically reads `.env` from project root
- **Docker**: We pass env vars from root `.env` to containers

## 🚀 **Quick Start (2 minutes)**

### 1. Setup Environment

**🔸 For Development:**

```bash
# Copy development environment template
cp .env.dev.example .env

# Edit with your dev values (most defaults work!)
nano .env  # Configure for local development
```

**🔸 For Production:**

```bash
# Copy production environment template  
cp .env.production.example .env

# Edit with your production values (REQUIRED!)
nano .env  # Replace with secure production values
```

### 2. Start Development

```bash
# Start database and Redis services
pnpm dev:start

# In another terminal, start the applications
pnpm dev
```

**That's it!** Both frontend and backend will use the same `.env` file.

## 📋 **What Each App Reads**

### **Backend (apps/bff/)**

Reads these variables from root `.env`:

```bash
DATABASE_URL              # Database connection
REDIS_URL                 # Cache connection
JWT_SECRET                # Authentication
WHMCS_BASE_URL            # External API
SF_LOGIN_URL              # Salesforce API
PORTAL_PRICEBOOK_ID       # Salesforce pricing pricebook
LOG_LEVEL                 # Logging level
# ... and all backend variables
```

### **Frontend (apps/portal/)**

Reads these variables from root `.env`:

```bash
NEXT_PUBLIC_API_BASE      # Backend API URL
NEXT_PUBLIC_APP_NAME      # App branding
NEXT_PUBLIC_APP_VERSION   # Version display
NEXT_PUBLIC_ENABLE_DEVTOOLS  # Development tools
# ... only NEXT_PUBLIC_ variables are exposed to browser
```

## 🛠️ **Development Workflow**

### Daily Development

```bash
# 1. Start services (run once)
pnpm dev:start

# 2. Start apps (with hot reload)
pnpm dev
```

### Environment Changes

```bash
# Edit the single .env file
nano .env

# Restart apps to pick up changes
# (Services like database don't need restart)
pnpm dev
```

### Database Management

```bash
# Run migrations
pnpm dev:migrate

# Open database admin tool
pnpm dev:tools
# Visit http://localhost:8080 for Adminer
```

## 🚀 **Production Deployment**

### For Production

```bash
# 1. Copy template
cp .env.example .env

# 2. Edit for production values
nano .env
# Set strong passwords, production URLs, etc.

# 3. Deploy
pnpm prod:deploy
```

## 🔍 **Key Benefits**

### **Single Source of Truth**

- ✅ One file to rule them all
- ✅ No confusion about which file to edit
- ✅ No duplicate values to maintain
- ✅ Consistent configuration across apps

### **Standard Approach**

- ✅ Follows Next.js conventions
- ✅ Follows NestJS conventions
- ✅ Follows Docker conventions
- ✅ Industry best practice

### **Developer Friendly**

- ✅ Simple setup: copy one file
- ✅ Easy to understand structure
- ✅ No app-specific configuration needed
- ✅ Works with all tools (VS Code, Docker, etc.)

## 🚨 **Important Notes**

### **Security**

- ✅ `.env.example` is committed (safe template)
- ✅ `.env` is gitignored (contains secrets)
- ✅ Never commit actual `.env` file to git
- ✅ Use strong values for production

### **Variable Naming**

- ✅ `NEXT_PUBLIC_*` = Exposed to browser (frontend)
- ✅ Everything else = Server-side only (backend)
- ✅ Clear naming convention

### **Environment Separation**

- ✅ Development: Use local services (localhost)
- ✅ Production: Use container services (service names)
- ✅ Same file structure, different values

This approach is **simple, standard, and scalable**! 🎉