# Single Source of Truth - Moyos Wedding App

**Version:** 2.0  
**Last Updated:** January 2025  
**Status:** Production Ready  
**Purpose:** Comprehensive documentation for the Moyos Wedding App

---

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Local Development Setup](#local-development-setup)
4. [Environment Configuration](#environment-configuration)
5. [Database & Supabase](#database--supabase)
6. [Deployment (Proxmox)](#deployment-proxmox)
7. [Troubleshooting](#troubleshooting)
8. [Operations & Runbooks](#operations--runbooks)

---

## Overview

### Project Description

The Moyos Wedding App is a premium, invite-only wedding management platform built for Lerato Molema and Denver Moyo. It provides a "Shock & Awe" digital experience featuring glassmorphism design, real-time AI assistance, and immersive storytelling.

### Design Language

**Garden Sanctuary Aesthetic:**
- **Palette:** Sage Hint (#BFCFBB), Mint (#BFCFBB), Sage (#8EA58C), Moss (#738A6E), Evergreen (#344C3D)
- **Typography:** Great Vibes (calligraphy), Inter (modern legibility)
- **Aesthetic:** High-density glassmorphism, botanical parallax, liquid silver accents

### Technology Stack

**Frontend:**
- Next.js 16.1.1 (App Router)
- React 19.2.1
- TypeScript 5.x
- Tailwind CSS 4
- Radix UI & Shadcn UI
- Framer Motion
- Lucide React

**Backend:**
- Node.js 20.x
- Next.js API Routes
- Prisma 7.2.0 (PostgreSQL ORM)
- Supabase (Auth, Storage, Realtime)
- Redis (required in production for rate limiting)

**Infrastructure:**
- Self-hosted on Proxmox VE 8.x+
- PostgreSQL (via Supabase or standalone)
- Docker Compose (optional)
- Nginx (reverse proxy)
- PM2 (process manager)

**Development Tools:**
- npm (package manager)
- ESLint (linting)
- Jest & React Testing Library (testing)
- Playwright (E2E testing)
- TypeScript (type checking)
- Sentry (error tracking)

### Key Features

1. **Guest RSVP System** - Invite code authentication, RSVP submission with dietary preferences
2. **Music Request & Voting** - Apple Music integration, song requests, voting system
3. **Photo Gallery** - Guest photo uploads, moderation, comments, reactions
4. **Guestbook** - Text, audio, and video guestbook entries
5. **Guest Directory** - "Who's Who" directory with opt-in profiles
6. **Admin Dashboard** - Comprehensive wedding management
7. **Real-time Updates** - WebSocket/SSE integration for live updates
8. **PWA Support** - Progressive Web App with offline capabilities
9. **AI Concierge** - Self-hosted Ollama integration (optional)
10. **Wedding Information Hub** - Timeline, venue, dress code, FAQs

---

## Architecture

### System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        Client Browser                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Next.js    │  │   React 19   │  │  Tailwind   │       │
│  │  App Router  │  │  Components  │  │     CSS     │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTPS
┌───────────────────────▼─────────────────────────────────────┐
│                    Next.js Server                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  API Routes  │  │  Server      │  │  Middleware  │       │
│  │  (67 routes) │  │  Components  │  │  (Auth/CSRF) │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
│  PostgreSQL  │ │  Supabase   │ │   Redis    │
│   (Prisma)   │ │   (Auth)    │ │  (Cache)   │
└──────────────┘ └─────────────┘ └─────────────┘
```

### Directory Structure

```
app/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/             # Protected routes
│   │   │   ├── dashboard/      # Guest dashboard
│   │   │   └── rsvp/           # RSVP page
│   │   ├── (public)/           # Public routes
│   │   │   └── wedding/        # Wedding info hub
│   │   ├── admin/              # Admin dashboard
│   │   ├── api/                # API routes
│   │   └── invite/            # Invite code entry
│   ├── components/
│   │   ├── features/           # Feature components
│   │   ├── layout/             # Layout components
│   │   └── ui/                 # Reusable UI components
│   ├── context/                # React Context
│   ├── hooks/                  # Custom hooks
│   ├── lib/                    # Utilities and services
│   └── types/                  # TypeScript definitions
├── prisma/
│   ├── schema.prisma          # Database schema
│   └── migrations/             # Database migrations
├── supabase/                   # Supabase configuration
│   └── migrations/             # Supabase migrations
├── public/                     # Static assets
└── scripts/                    # Deployment scripts
```

### Data Flow

**Guest Authentication Flow:**
```
Guest → Invite Code Entry → POST /api/guest/auth
  → Validate Code → Create Session → Set Cookie
  → Return Guest Data → Update Context → Redirect to Dashboard
```

**RSVP Submission Flow:**
```
Guest → RSVP Form → POST /api/rsvp/submit
  → Verify CSRF → Check Rate Limit → Validate Input
  → Sanitize Data → Save to Database → Send Confirmation
  → Update Context → Show Success Message
```

**Real-time Updates:**
```
Event (RSVP/Music/Gallery) → Database Change
  → Supabase Realtime → WebSocket Broadcast
  → Client Receives Update → UI Refresh
```

### Database Schema

**Key Models:**
- `Guest` - Guest information, RSVP status, preferences
- `Song` - Music requests with voting
- `SongVote` - Individual votes on songs
- `GuestbookEntry` - Guestbook messages (text/audio/video)
- `GalleryPhoto` - Photo uploads with moderation
- `PhotoComment` - Comments on photos
- `Table` - Seating table assignments
- `Admin` - Admin users with TOTP support

See `prisma/schema.prisma` for complete schema definition.

---

## Local Development Setup

### Prerequisites

- **Node.js:** 20.x or later
- **npm:** 10.x or later (or yarn/pnpm)
- **PostgreSQL:** 14+ (or Supabase account)
- **Git:** For version control

### Installation Steps

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd moyosApp/app
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Set up environment variables:**
   ```bash
   cp .env.local.example .env.local
   # Edit .env.local with your configuration
   ```
   See [Environment Configuration](#environment-configuration) for details.

4. **Generate Prisma client:**
   ```bash
   npm run dev
   # This automatically runs: prisma generate && next dev
   ```

5. **Set up database:**
   ```bash
   # For development (creates schema)
   npm run db:push
   
   # For production (runs migrations)
   npm run db:migrate
   ```

6. **Seed database (optional):**
   ```bash
   npm run db:seed
   ```

7. **Start development server:**
   ```bash
   npm run dev
   ```

8. **Open in browser:**
   ```
   http://localhost:3000
   ```

### Development Commands

```bash
# Development server
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Testing
npm test
npm run test:watch
npm run test:coverage

# E2E testing
npm run test:e2e
npm run test:e2e:ui

# Database
npm run db:studio        # Prisma Studio
npm run db:push          # Push schema changes
npm run db:migrate       # Run migrations
npm run db:seed          # Seed database
npm run db:reset         # Reset database

# Build
npm run build
npm run start            # Production server

# Security
npm run security:audit
npm run security:audit:fix
```

### Local Supabase Setup (Optional)

For local development with Supabase:

1. **Install Supabase CLI:**
   ```bash
   npm install -g supabase
   ```

2. **Initialize Supabase:**
   ```bash
   supabase init
   ```

3. **Start local Supabase:**
   ```bash
   supabase start
   ```

4. **Get local credentials:**
   ```bash
   supabase status
   ```

5. **Update `.env.local`:**
   ```bash
   NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
   NEXT_PUBLIC_SUPABASE_ANON_KEY=<from supabase status>
   SUPABASE_SERVICE_ROLE_KEY=<from supabase status>
   DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
   ```

See [Database & Supabase](#database--supabase) for more details.

---

## Environment Configuration

### Required Variables

#### Authentication & Security

**`ADMIN_PASSWORD`**
- **Type:** String
- **Required:** Yes
- **Min Length:** 8 characters
- **Default (Dev):** `wedding2026admin`
- **Description:** Password for admin dashboard access
- **Security:** Must be changed in production
- **Example:** `StrongPassword123!`

**`SESSION_SECRET`**
- **Type:** String
- **Required:** Yes
- **Min Length:** 32 characters
- **Description:** Secret key for session encryption
- **Security:** Must be strong random string in production
- **Generation:** `openssl rand -base64 32`
- **Example:** `f3ERSdncczdgAruOxCKXqqd5O6KIn81VQDlZ0nOARteUQ9nq6YBJi6MqJgzqazVQ`

#### Database

**`DATABASE_URL`**
- **Type:** PostgreSQL Connection String
- **Required:** Yes (Production), No (Development)
- **Format:** `postgresql://user:password@host:port/database`
- **Description:** PostgreSQL database connection string
- **Example:** `postgresql://wedding_user:password@localhost:5432/wedding_db`
- **Note:** Direct connection (port 5432)

**`SHADOW_DATABASE_URL`** (Optional)
- **Type:** PostgreSQL Connection String
- **Required:** No
- **Description:** Shadow database for Prisma migrations (Supabase)
- **Note:** Only needed for Supabase migrations

**`RUNTIME_DATABASE_URL`** (Optional)
- **Type:** PostgreSQL Connection String
- **Required:** No
- **Default:** `DATABASE_URL`
- **Description:** Runtime database URL (pgbouncer, port 6543)
- **Use Case:** Production connection pooling

#### Supabase

**`NEXT_PUBLIC_SUPABASE_URL`**
- **Type:** URL String
- **Required:** Yes
- **Description:** Supabase project URL
- **Example:** `https://your-project-id.supabase.co`
- **Local:** `http://127.0.0.1:54321`

**`NEXT_PUBLIC_SUPABASE_ANON_KEY`**
- **Type:** String
- **Required:** Yes
- **Description:** Supabase anonymous/public key (safe for client-side)
- **Note:** Exposed to browser, use anon key only

**`SUPABASE_SERVICE_ROLE_KEY`**
- **Type:** String
- **Required:** Yes
- **Description:** Supabase service role key (server-side only)
- **Security:** NEVER expose to client - server-side only
- **Note:** Has admin privileges, keep secret

### Optional Variables

**`NEXT_PUBLIC_APP_URL`**
- **Type:** URL String
- **Required:** No
- **Default:** `http://localhost:3000`
- **Description:** Public URL of the application
- **Example:** `https://themoyos.co.za`
- **Usage:** Used for absolute URLs, email links, etc.

**`NODE_ENV`**
- **Type:** Enum (`development` | `production` | `test`)
- **Required:** No
- **Default:** `development`
- **Description:** Node.js environment

**`CSRF_SECRET`**
- **Type:** String
- **Required:** Yes (Production)
- **Default:** None
- **Description:** CSRF token secret
- **Generation:** `openssl rand -base64 24`

**SMTP Settings** (Optional, for email notifications)
- `SMTP_HOST` - SMTP server hostname (e.g., `smtp.sendgrid.net`)
- `SMTP_PORT` - SMTP server port (e.g., `587`)
- `SMTP_USER` - SMTP username (e.g., `apikey`)
- `SMTP_PASS` - SMTP password/API key

**Twilio Settings** (Optional, for SMS notifications)
- `TWILIO_ACCOUNT_SID` - Twilio account SID
- `TWILIO_AUTH_TOKEN` - Twilio auth token
- `TWILIO_PHONE_NUMBER` - Twilio phone number

**Redis** (Required in production, for rate limiting)
- `REDIS_URL` - Redis connection string (e.g., `redis://localhost:6379`)

**Error Tracking & Analytics** (Optional)
- `NEXT_PUBLIC_SENTRY_DSN` - Sentry error tracking DSN
- `NEXT_PUBLIC_GA_MEASUREMENT_ID` - Google Analytics Measurement ID

**Feature Flags**
- `ENABLE_NOTIFICATIONS` - Enable email/SMS notifications (default: `true`)
- `ENABLE_ANALYTICS` - Enable analytics tracking (default: `false`)

### Environment-Specific Configuration

#### Development (`.env.local`)

```bash
# Required
ADMIN_PASSWORD=wedding2026admin
SESSION_SECRET=your-dev-secret-here-min-32-chars

# Database (optional in dev)
# DATABASE_URL=postgresql://user:pass@localhost:5432/wedding_db

# Supabase (local or cloud)
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-key

# Optional
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development
ENABLE_NOTIFICATIONS=true
ENABLE_ANALYTICS=false
```

#### Production (`.env.production`)

```bash
# Required
ADMIN_PASSWORD=your-strong-production-password
SESSION_SECRET=your-strong-random-secret-min-32-chars
DATABASE_URL=postgresql://user:pass@host:5432/wedding_db
NEXT_PUBLIC_APP_URL=https://themoyos.co.za

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-production-service-key

# Optional but Recommended
NEXT_PUBLIC_SENTRY_DSN=https://your-sentry-dsn
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

# Redis (REQUIRED for rate limiting in production)
REDIS_URL=redis://your-redis-host:6379

# Email (if using)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key

# Feature Flags
ENABLE_NOTIFICATIONS=true
ENABLE_ANALYTICS=true
NODE_ENV=production

# Ollama AI (Wedding Concierge)
# Use internal Docker network URL if Ollama is in same Coolify stack
# Or external URL if Ollama is on a different service
OLLAMA_URL=http://ollama-CONTAINER_ID:11434
# Or: OLLAMA_URL=https://ollama.yourdomain.com
OLLAMA_MODEL=jarvis-concierge
OLLAMA_TEMPERATURE=0.7
```

### Security Best Practices

1. **Never Commit Secrets**
   - `.env.local` is in `.gitignore`
   - `.env.production` should never be committed
   - Use `.env.example` for documentation

2. **Strong Secrets**
   - `SESSION_SECRET`: Use `openssl rand -base64 32`
   - `ADMIN_PASSWORD`: Minimum 12 characters, mix of letters, numbers, symbols
   - Database passwords: Strong, unique passwords

3. **Security Headers & CSP**
   - **Single Source of Truth:** All security headers (CSP, CORS, HSTS, etc.) are set in `src/proxy.ts` middleware
   - **Why Middleware:** Middleware runs for all routes (pages and API), ensuring consistent security headers
   - **Do NOT set headers in `next.config.ts`:** This would create conflicts and maintenance issues
   - **CSP Policy:** Configured in `src/proxy.ts` with route-specific permissions (e.g., camera/mic for guestbook/gallery)
   - **Headers Set:**
     - Content-Security-Policy (CSP)
     - Cross-Origin-Opener-Policy (COOP)
     - Cross-Origin-Resource-Policy (CORP)
     - X-Frame-Options
     - X-Content-Type-Options
     - Referrer-Policy
     - Permissions-Policy (route-specific)
     - Strict-Transport-Security (production only)

4. **Production Secrets**
   - Use secrets management service (AWS Secrets Manager, Vault)
   - Rotate secrets regularly
   - Use different secrets per environment

4. **Public Variables**
   - `NEXT_PUBLIC_*` variables are exposed to client
   - Only use for non-sensitive configuration
   - Never put secrets in `NEXT_PUBLIC_*` variables

### Validation

All environment variables are validated using Zod schema in `src/lib/env.ts`.

**Validation happens:**
- On application startup
- Type checking
- Format validation
- Required field checking

**Errors:**
- Invalid variables cause application to fail on startup
- Clear error messages indicate which variables are invalid

---

## Database & Supabase

### Database Setup

#### Using Supabase (Recommended)

1. **Create Supabase Project:**
   - Go to [supabase.com](https://supabase.com)
   - Create a new project
   - Wait for project to be ready

2. **Get Connection String:**
   - Go to Settings → Database
   - Copy the "Connection string" (URI format)
   - Update `DATABASE_URL` in `.env.local`:
     ```bash
     DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF].supabase.co:5432/postgres
     ```

3. **Get Supabase Keys:**
   - Go to Settings → API
   - Copy Project URL → `NEXT_PUBLIC_SUPABASE_URL`
   - Copy anon/public key → `NEXT_PUBLIC_SUPABASE_ANON_KEY`
   - Copy service_role key → `SUPABASE_SERVICE_ROLE_KEY`

4. **Run Migrations:**
   ```bash
   npm run db:migrate
   ```

#### Using Local PostgreSQL

1. **Install PostgreSQL:**
   ```bash
   # macOS
   brew install postgresql@14
   
   # Ubuntu/Debian
   sudo apt-get install postgresql-14
   ```

2. **Create Database:**
   ```bash
   createdb wedding_app
   ```

3. **Update `DATABASE_URL`:**
   ```bash
   DATABASE_URL=postgresql://postgres:password@localhost:5432/wedding_app
   ```

4. **Run Migrations:**
   ```bash
   npm run db:migrate
   ```

### Supabase Integration

#### Client-Side Usage

```typescript
import { getSupabaseClient } from '@/lib/supabase';

// In a React component or client component
const supabase = getSupabaseClient();

// Example: Fetch data
const { data, error } = await supabase
  .from('guests')
  .select('*')
  .eq('isAttending', true);

// Example: Real-time subscription
const subscription = supabase
  .channel('guests')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'guests' },
    (payload) => {
      console.log('New guest added:', payload.new);
    }
  )
  .subscribe();
```

#### Server-Side Usage

```typescript
import { createSupabaseAdminClient } from '@/lib/supabase';

// In API routes or server components
const supabase = createSupabaseAdminClient();

// Example: Admin operation
const { data, error } = await supabase
  .from('guests')
  .delete()
  .eq('id', guestId);
```

### Database Migrations

**Development:**
```bash
# Push schema changes (creates migration automatically)
npm run db:push

# Or create migration manually
npx prisma migrate dev --name migration_name
```

**Production:**
```bash
# Run migrations
npm run db:migrate
```

**Supabase Migrations:**
```bash
# Create Supabase migration
supabase migration new migration_name

# Apply migrations
supabase db push
```

### Database Management

**Prisma Studio:**
```bash
npm run db:studio
```

**Seed Database:**
```bash
npm run db:seed
```

**Reset Database:**
```bash
npm run db:reset
```

---

## Deployment (Proxmox)

### Prerequisites

- Proxmox VE 8.x+ installed
- Access to Proxmox web interface or CLI
- Domain name configured (for SSL)
- Basic Linux administration knowledge

### Quick Deployment (30 minutes)

#### Step 1: Create LXC Containers

**Next.js App Container:**
```bash
pct create 190 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-wedding-app \
  --memory 8192 \
  --cores 4 \
  --swap 2048 \
  --rootfs local-lvm:50 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.90/24,gw=172.20.40.1 \
  --unprivileged 1 \
  --start 1
```

**Supabase Container/VM:**
```bash
# Option A: LXC Container (if Docker support enabled)
pct create 191 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-supabase \
  --memory 8192 \
  --cores 4 \
  --swap 2048 \
  --rootfs local-lvm:50 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.91/24,gw=172.20.40.1 \
  --privileged 1 \
  --start 1

# Option B: VM (Recommended for Docker)
# Create VM in Proxmox Web UI:
# - OS: Debian 12
# - Resources: 4 vCPU, 8GB RAM, 50GB disk
# - Network: Bridge (vmbr0)
# - IP: 172.20.40.91/24
# - Gateway: 172.20.40.1
```

**Redis Container (Optional):**
```bash
pct create 192 \
  local:vztmpl/debian-12-standard_*.tar.zst \
  --hostname moyos-redis \
  --memory 2048 \
  --cores 1 \
  --swap 512 \
  --rootfs local-lvm:10 \
  --net0 name=eth0,bridge=vmbr0,ip=172.20.40.92/24,gw=172.20.40.1 \
  --unprivileged 1 \
  --start 1
```

#### Step 2: Setup Next.js Container

```bash
# Enter container
pct enter 190

# Install Node.js & PM2
apt-get update && apt-get upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs postgresql-client redis-tools git
npm install -g pm2
pm2 startup systemd
```

#### Step 3: Setup Supabase Container/VM

```bash
# SSH to VM or enter container
ssh root@172.20.40.91
# Or: pct enter 191

# Run Supabase setup script
cd /opt
git clone https://github.com/moyoza/moyosApp.git moyosApp
cd moyosApp/app
chmod +x scripts/*.sh
./scripts/setup-supabase-proxmox.sh

# Start Supabase
supabase start

# IMPORTANT: Save the keys from output!
```

#### Step 4: Deploy Application

```bash
# On Next.js container (190)
cd /opt
git clone https://github.com/moyoza/moyosApp.git moyosApp
cd moyosApp/app

# Configure environment
cp .env.local.example .env.production
nano .env.production  # Edit with your values

# Deploy
chmod +x scripts/*.sh
./scripts/deploy.sh --production
```

**Required Environment Variables:**
```bash
# Application
NODE_ENV="production"
NEXT_PUBLIC_APP_URL="https://your-domain.com"

# Supabase (self-hosted on Proxmox - pct 191)
NEXT_PUBLIC_SUPABASE_URL="http://172.20.40.91:54321"
NEXT_PUBLIC_SUPABASE_ANON_KEY="sb_publishable_<from-supabase-status>"
SUPABASE_SERVICE_ROLE_KEY="sb_secret_<from-supabase-status>"

# Database (from Supabase)
DATABASE_URL="postgresql://postgres:postgres@172.20.40.91:54322/postgres"

# Session & Security
SESSION_SECRET="your-32-char-secret"
CSRF_SECRET="your-csrf-secret"
ADMIN_PASSWORD="your-secure-admin-password"

# Redis (required)
REDIS_URL="redis://172.20.40.92:6379"
```

#### Step 5: Setup Nginx

```bash
# On host or Nginx container
apt-get update && apt-get install -y nginx certbot python3-certbot-nginx

# Copy config
cp /opt/moyos-wedding-app/app/nginx.conf /etc/nginx/sites-available/moyos-wedding-app

# Update domain name
sed -i 's/your-domain.com/actual-domain.com/g' /etc/nginx/sites-available/moyos-wedding-app

# Enable site
ln -s /etc/nginx/sites-available/moyos-wedding-app /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default

# Test and reload
nginx -t
systemctl reload nginx

# Get SSL certificate
certbot --nginx -d your-domain.com -d www.your-domain.com
```

### Post-Deployment

**Verify Deployment:**
```bash
# Health check
curl https://your-domain.com/api/health

# Run smoke tests
cd /opt/moyos-wedding-app/app
./scripts/smoke-tests.sh --base-url https://your-domain.com
```

**Setup Backups:**
```bash
# Add to crontab
crontab -e

# Database backup (daily at 2 AM)
0 2 * * * /opt/moyos-wedding-app/app/scripts/backup-db.sh

# Storage backup (daily at 3 AM)
0 3 * * * /opt/moyos-wedding-app/app/scripts/backup-storage.sh
```

**Monitor Application:**
```bash
# PM2 status
pm2 status

# View logs
pm2 logs moyos-wedding-app

# Monitor resources
pm2 monit

# Health check
./scripts/health-check.sh
```

### Detailed Deployment Procedures

For comprehensive deployment procedures, see:
- [Deployment Runbook](deployment-runbook.md) - Detailed step-by-step procedures
- [Backup Procedures](backup-procedures.md) - Backup and restore procedures

---

## Troubleshooting

### Common Issues

#### Application Won't Start

**Symptoms:** PM2 shows app as "errored" or "stopped"

**Solutions:**
```bash
# Check logs
pm2 logs moyos-wedding-app --err

# Check environment
cat .env.production

# Verify database connection
psql $DATABASE_URL -c "SELECT 1;"

# Restart
pm2 restart moyos-wedding-app
```

#### Database Connection Issues

**Symptoms:** "Database connection failed" errors

**Solutions:**
```bash
# Test connection from app container
psql -h 172.20.40.91 -p 54322 -U postgres -d postgres

# Check Supabase status (on Supabase container)
supabase status

# Check Supabase logs
supabase logs

# Verify firewall rules
iptables -L -n
```

#### Nginx Errors

**Symptoms:** 502 Bad Gateway, connection refused

**Solutions:**
```bash
# Test configuration
nginx -t

# Check error logs
tail -f /var/log/nginx/error.log

# Reload
systemctl reload nginx
```

#### useSearchParams Error (Turbopack)

**Symptoms:** `useSearchParams is not defined` runtime error

**Solutions:**
```bash
# Stop dev server
# Press Ctrl+C

# Clear build cache
rm -rf .next

# Restart dev server
npm run dev
```

#### Build Errors

**Symptoms:** Build fails with TypeScript or dependency errors

**Solutions:**
```bash
# Clean install
rm -rf node_modules package-lock.json
npm install

# Regenerate Prisma client
npx prisma generate

# Type check
npm run typecheck

# Build
npm run build
```

#### Environment Variable Issues

**Symptoms:** "Environment variable validation failed"

**Solutions:**
1. Check all required variables are set
2. Verify variable formats (URLs, booleans)
3. Check for typos in variable names
4. Ensure `SESSION_SECRET` is at least 32 characters
5. Verify `DATABASE_URL` format: `postgresql://user:password@host:port/database`

### Getting Help

1. Check application logs: `pm2 logs moyos-wedding-app`
2. Check Nginx logs: `tail -f /var/log/nginx/error.log`
3. Check database logs: `supabase logs`
4. Review [Deployment Runbook](deployment-runbook.md) troubleshooting section
5. Check GitHub issues or documentation

---

## Operations & Runbooks

### Backup Procedures

**Automated Backups:**
- Database: Daily at 2:00 AM
- Storage: Daily at 3:00 AM
- Configuration: Weekly (Sunday at 1:00 AM)

**Manual Backup:**
```bash
# Database backup
./scripts/backup-db.sh

# Storage backup
./scripts/backup-storage.sh
```

**Restore:**
```bash
# Restore database
./scripts/restore-db.sh /opt/backups/db/wedding_app_backup_YYYYMMDD_HHMMSS.sql.gz
```

For detailed backup procedures, see [Backup Procedures](backup-procedures.md).

### Monitoring

**Health Checks:**
```bash
# Application health
curl https://your-domain.com/api/health

# Metrics
curl https://your-domain.com/api/metrics

# Automated health check script
./scripts/health-check.sh
```

**PM2 Monitoring:**
```bash
# Status
pm2 status

# Logs
pm2 logs moyos-wedding-app

# Monitor
pm2 monit
```

### Maintenance

**Update Application:**
```bash
# Pull latest code
git pull origin main

# Install dependencies
npm ci --production=false

# Run migrations
npm run db:migrate

# Build
npm run build

# Restart
pm2 reload moyos-wedding-app
```

**Update Dependencies:**
```bash
# Check for updates
npm outdated

# Update dependencies
npm update

# Security audit
npm run security:audit
npm run security:audit:fix
```

### Useful Commands

```bash
# Application
pm2 status                    # Check status
pm2 logs moyos-wedding-app    # View logs
pm2 restart moyos-wedding-app # Restart
pm2 monit                     # Monitor

# Database
psql $DATABASE_URL            # Connect to database
./scripts/backup-db.sh        # Backup database
./scripts/restore-db.sh <file> # Restore database

# Deployment
./scripts/deploy.sh --production  # Deploy
./scripts/health-check.sh          # Health check
./scripts/smoke-tests.sh          # Smoke tests

# Nginx
nginx -t                      # Test config
systemctl reload nginx        # Reload
systemctl status nginx       # Status
```

---

## Additional Resources

- [Documentation Index](DOCS_INDEX.md) - Complete documentation index
- [Deployment Runbook](deployment-runbook.md) - Detailed deployment procedures
- [Backup Procedures](backup-procedures.md) - Backup and restore procedures
- [Coding Standards](coding-standards.md) - Development guidelines

---

**Last Updated:** January 2025  
**Maintained By:** Development Team  
**Questions?** Check [DOCS_INDEX.md](DOCS_INDEX.md) or create an issue.