# 📚 Customer Portal Documentation

## 🚀 Quick Start

### Development Setup

```bash
# Copy development environment template
cp .env.dev.example .env
# Edit .env with your development values

# Start development
pnpm dev:start    # Start services (PostgreSQL + Redis)
pnpm dev         # Start apps with hot reload
```

### Production Deployment

```bash
# Configure for production
cp .env.production.example .env
# Edit .env with production values

# Deploy to production
pnpm prod:deploy
```

## 📁 Project Structure

```
📦 Customer Portal
├── 🚀 apps/                     # Applications
│   ├── portal/                  # Next.js frontend
│   └── bff/                     # NestJS backend
├── 🐳 docker/                   # Docker configurations
│   ├── dev/                     # Development (services only)
│   └── prod/                    # Production (complete stack)
├── 🛠️ scripts/                  # Management scripts
│   ├── dev/manage.sh            # Development manager
│   ├── prod/manage.sh           # Production manager
│   └── plesk-deploy.sh          # Plesk deployment
├── 📚 docs/                     # Documentation
├── 📦 packages/shared/          # Shared utilities
└── 🔧 Configuration files
```

## 🔧 Development Workflow

### Environment Setup

- **Environment-specific templates**: `.env.dev.example` or `.env.production.example`
- **Development database**: PostgreSQL in Docker
- **Cache**: Redis in Docker
- **Apps**: Run locally with hot reload

### Commands

```bash
# Development
pnpm dev:start      # Start services
pnpm dev:apps       # Start services + apps
pnpm dev:tools      # Start with admin tools
pnpm dev:migrate    # Run migrations
pnpm dev:reset      # Reset environment

# Production
pnpm prod:deploy    # Full deployment
pnpm prod:update    # Update deployment
pnpm prod:status    # Health checks
pnpm prod:backup    # Database backup
```

## 🚀 Production Deployment

### Docker Production Stack

- **Frontend**: Next.js in optimized container
- **Backend**: NestJS in optimized container
- **Database**: PostgreSQL with performance tuning
- **Cache**: Redis with production config
- **Health checks**: Built-in monitoring
- **Security**: Non-root containers, proper networking

### Plesk Integration

1. **Update Plesk Git action** to use: `./scripts/plesk-deploy.sh`
2. **Configure environment**: Create `.env` from template
3. **Deploy**: Push to GitHub triggers automatic deployment

## 🔍 Key Features

### Development

- ✅ **Fast startup**: Services in containers, apps local
- ✅ **Hot reload**: Full debugging and development tools
- ✅ **Admin tools**: Database and Redis management
- ✅ **Clean separation**: No production configs mixed in

### Production

- ✅ **Enterprise-grade**: Complete containerization
- ✅ **Performance optimized**: Tuned PostgreSQL + Redis
- ✅ **Security hardened**: Non-root users, health checks
- ✅ **Zero-downtime**: Rolling updates supported
- ✅ **Monitoring ready**: Built-in health endpoints

### Architecture

- ✅ **BFF Pattern**: Backend for Frontend with NestJS
- ✅ **Type Safety**: Shared TypeScript types
- ✅ **Modern Stack**: Next.js 15, React 19, PostgreSQL, Redis
- ✅ **Monorepo**: PNPM workspaces for code sharing

## 🔐 Security & Best Practices

- **Environment isolation**: Clear dev/prod separation
- **Secret management**: Secure key storage
- **Container security**: Non-root users, minimal images
- **Database security**: Connection pooling, prepared statements
- **API security**: JWT authentication, CORS protection

## 📊 Monitoring & Logging

- **Health checks**: All services have health endpoints
- **Structured logging**: JSON logs in production
- **Performance monitoring**: Built-in metrics
- **Error tracking**: Comprehensive error handling

## 🎯 Clean Structure Benefits

- ✅ **No duplicates**: Single source of truth
- ✅ **No clutter**: Only necessary files
- ✅ **Clear organization**: Intuitive directory structure
- ✅ **Easy onboarding**: Self-explanatory setup
- ✅ **Professional**: Enterprise best practices

This setup provides **enterprise-grade deployment** with **developer-friendly workflows**! 🚀