Assist_Design/docs/getting-started/setup.md

# 🚀 Getting Started

## ✅ **Environment File Options**

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

### 📁 **Available Templates:**

Located in the `env/` folder:

- 🔸 **`env/dev.env.sample`** - Development environment template
- 🔸 **`env/portal-backend.env.sample`** - Backend-specific variables reference
- 🔸 **`env/portal-frontend.env.sample`** - Frontend-specific variables reference

### 🎯 **Benefits:**

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

## 🔧 **Environment File Structure**

```
📦 Customer Portal
├── env/
│   ├── dev.env.sample           # 🔸 Development template
│   ├── portal-backend.env.sample   # Backend variables
│   └── portal-frontend.env.sample  # Frontend variables
├── .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.env.sample .env

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

**🔸 For Production:**

```bash
# Start from the development template and adjust for production
cp env/dev.env.sample .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**! 🎉