Queue-it Style Virtual Waiting Room System

A production-ready virtual waiting room system built with MERN stack, Next.js, and AWS infrastructure.

🏗️ Architecture

• Frontend: Next.js 14 (client app) + React + Vite (admin UI)
• Backend: Node.js 20 + Express + TypeScript
• Database: MongoDB Atlas (persistent data) + Redis/ElastiCache (sessions & queue state)
• Infrastructure: AWS ECS Fargate + ElastiCache + CloudFront + S3
• Realtime: Socket.IO with Redis adapter + SSE fallback

🚀 Quick Start

Prerequisites

• Node.js 20+
• pnpm 8+
• Docker & Docker Compose
• AWS CLI (for deployment)

Local Development

1. Clone and install dependencies:

   git clone <repository>
   cd queue-it-monorepo
   pnpm install:all

2. Set up environment variables:

   # Root environment (for docker compose and shared config)
   cp env.example .env
      
   # Admin API environment
   cd apps/admin-api
   cp env.example .env
      
   # Admin UI environment
   cd ../admin-ui
   cp env.example .env
      
   # Client App environment
   cd ../client-app
   cp env.example .env
      
   # Queue SDK environment (if developing the package)
   cd ../../packages/queue-sdk
   cp env.example .env
      
   # Return to root
   cd ../..

3. Start development environment:

   pnpm dev

   This starts:

   • MongoDB on port 27017
   • Redis on port 6379
   • Admin API on port 4000
   • Admin UI on port 5173
   • Client App on port 3000

4. Access applications:

   • Admin UI: http://localhost:5173
   • Client App: http://localhost:3000
   • Admin API: http://localhost:4000

🔧 Environment Configuration

Root Environment (.env)

The root env.example file contains shared configuration for the entire system:

# Database Configuration
MONGODB_URI=mongodb://admin:password@localhost:27017/queueit?authSource=admin

# Redis Configuration
REDIS_URL=redis://:redispassword@localhost:6379
REDIS_PASSWORD=redispassword

# JWT and HMAC Secrets (CHANGE THESE IN PRODUCTION!)
JWT_SECRET=local-jwt-secret-change-in-production
HMAC_SECRET=local-hmac-secret-change-in-production

# Cookie Configuration
COOKIE_DOMAIN=localhost
COOKIE_SECURE=false

# CORS Configuration
CORS_ORIGIN=http://localhost:3000,http://localhost:5173

# Server Configuration
PORT=4000
NODE_ENV=development

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

# Logging
LOG_LEVEL=debug

# Metrics
METRICS_ENABLED=true
METRICS_PORT=9090

# Admin API URLs (for frontend apps)
ADMIN_API_URL=http://localhost:4000
WS_URL=ws://localhost:4000

# Queue Configuration
DEFAULT_QUEUE_ID=limited-sneakers

Admin API Environment (apps/admin-api/.env)

Contains backend-specific configuration:

# Same as root env.example - copy from there
# Database, Redis, JWT, CORS, etc.

Admin UI Environment (apps/admin-ui/.env)

Contains frontend admin interface configuration:

# Vite Configuration
VITE_ADMIN_API_URL=http://localhost:4000
VITE_WS_URL=ws://localhost:4000

# Development Server
VITE_DEV_SERVER_PORT=5173
VITE_DEV_SERVER_HOST=localhost

# Build Configuration
VITE_BUILD_OUTPUT_DIR=dist
VITE_BUILD_SOURCEMAP=true

# Feature Flags
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_DEBUG=true

Client App Environment (apps/client-app/.env)

Contains public-facing app configuration:

# Next.js Configuration
NEXT_PUBLIC_ADMIN_API_URL=http://localhost:4000
NEXT_PUBLIC_WS_URL=ws://localhost:4000

# Development Server
NEXT_PUBLIC_DEV_SERVER_PORT=3000
NEXT_PUBLIC_DEV_SERVER_HOST=localhost

# Build Configuration
NEXT_PUBLIC_BUILD_OUTPUT_DIR=.next
NEXT_PUBLIC_BUILD_SOURCEMAP=true

# Feature Flags
NEXT_PUBLIC_ENABLE_ANALYTICS=false
NEXT_PUBLIC_ENABLE_DEBUG=true

# Queue Configuration
NEXT_PUBLIC_DEFAULT_QUEUE_ID=limited-sneakers

Queue SDK Environment (packages/queue-sdk/.env)

Contains SDK development configuration:

# API Configuration
QUEUE_API_URL=http://localhost:4000
QUEUE_WS_URL=ws://localhost:4000

# Authentication
QUEUE_AUTH_ENABLED=true
QUEUE_AUTH_COOKIE_NAME=queue-auth

# Queue Configuration
QUEUE_DEFAULT_TIMEOUT=30000
QUEUE_MAX_RETRIES=3

# Development
QUEUE_DEBUG_ENABLED=true
QUEUE_LOG_LEVEL=info

Environment Setup Checklist

1. Copy all env.example files to their respective .env files
2. Update database credentials (MongoDB and Redis passwords)
3. Generate secure secrets for JWT and HMAC (use strong random strings)
4. Configure CORS origins for your development domains
5. Set cookie domain to match your local development setup
6. Verify API URLs point to correct local development ports

Production Environment Variables

For production deployment, ensure:

• Strong secrets: Use cryptographically secure random strings
• Secure cookies: Set COOKIE_SECURE=true and proper domain
• Restricted CORS: Only allow production domains
• Environment: Set NODE_ENV=production
• Logging: Set LOG_LEVEL=info or warn

🐳 Docker Compose Services

• mongodb: MongoDB 7.0 with persistent volume
• redis: Redis 7.2 with persistence
• admin-api: Express API with hot-reload
• admin-ui: Vite dev server
• client-app: Next.js dev server

🏗️ Infrastructure (Terraform)

Prerequisites

• Terraform 1.5+
• AWS CLI configured
• S3 bucket for Terraform state (optional)

Deployment

1. Configure AWS credentials:

   aws configure

2. Initialize Terraform:

   cd terraform
   terraform init

3. Configure variables:

   cp terraform.tfvars.example terraform.tfvars
   # Edit with your domain, AWS region, etc.

4. Deploy infrastructure:

   terraform plan
   terraform apply

Infrastructure Components

• VPC: 3 AZs with public/private subnets
• ECS: Fargate cluster with admin-api and worker services
• ElastiCache: Redis cluster for sessions and queue state
• ALB: Application Load Balancer with HTTPS termination
• CloudFront: CDN for static assets
• S3: Static hosting and asset storage
• Secrets Manager: Secure credential storage
• Route53: DNS management (optional)

🔄 CI/CD (GitHub Actions)

Workflows

• CI: Lint, typecheck, and test on PRs
• Build & Push: Build Docker images and push to ECR
• Deploy Infrastructure: Terraform plan/apply
• Deploy Apps: Update ECS services
• Deploy Static: Build and deploy frontend apps

GitHub OIDC Setup

1. Create IAM role for GitHub Actions:

   # Use the provided Terraform configuration
   cd terraform
   terraform apply -target=module.iam

2. Configure GitHub repository secrets:

   • AWS_REGION: Your AWS region
   • AWS_ROLE_ARN: ARN of the IAM role created above

3. Update workflow files with your AWS account details

🔐 Security Features

• Secrets Management: AWS Secrets Manager for all sensitive data
• IAM: Least-privilege access with OIDC authentication
• Network Security: VPC with private subnets, security groups
• TLS: ACM certificates with ALB and CloudFront
• Redis Security: AUTH enabled with security groups

📊 Monitoring & Operations

CloudWatch Alarms

• Redis CPU/Memory utilization
• ECS service health
• ALB target health

Prometheus Metrics

• Queue metrics endpoint: /metrics
• Health check: /healthz

Scaling

• ECS: Auto-scaling based on CPU/Memory
• ElastiCache: Manual scaling with zero-downtime
• ALB: Target group health checks

🧪 Testing

# Run all tests
pnpm test:all

# Run specific app tests
cd apps/admin-api && pnpm test
cd apps/admin-ui && pnpm test
cd apps/client-app && pnpm test
cd packages/queue-sdk && pnpm test

📁 Project Structure

├── apps/
│   ├── admin-api/          # Express API server
│   ├── admin-ui/           # React admin dashboard
│   └── client-app/         # Next.js client application
├── packages/
│   └── queue-sdk/          # Shared types and utilities
├── terraform/              # Infrastructure as Code
├── .github/                # GitHub Actions workflows
├── docker compose.yml      # Local development
└── README.md              # This file

🔄 Zero-Downtime Deployments

Application Updates

1. Build new Docker image
2. Update ECS task definition
3. Perform rolling update with health checks

Infrastructure Updates

1. Terraform plan to review changes
2. Apply changes during maintenance window
3. Use blue-green deployment for major changes

Secret Rotation

1. Create new secrets in AWS Secrets Manager
2. Update ECS task definitions
3. Deploy with new secret ARNs
4. Remove old secrets after verification

🚨 Troubleshooting

Common Issues

1. Redis Connection Failed

   • Check security groups and subnet configuration
   • Verify Redis AUTH credentials in Secrets Manager

2. ECS Tasks Not Starting

   • Check task definition and IAM roles
   • Verify secrets and environment variables

3. Terraform State Lock

   • Check DynamoDB lock table (if enabled)
   • Force unlock if necessary: terraform force-unlock <lock-id>

Support

• Check CloudWatch logs for application errors
• Review ECS task logs for container issues
• Monitor ElastiCache metrics for Redis performance

📝 License

MIT License - see LICENSE file for details

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📞 Support

For issues and questions:

• Create a GitHub issue
• Check the troubleshooting section
• Review CloudWatch logs and metrics