Ada SnapFix Worker

A standalone worker service for performing full accessibility scans using Playwright and axe-core. This worker is designed to run on a Linux VPS and can be synchronized with your main Ada SnapFix application.

🚀 Features

• Full Accessibility Scanning: Uses Playwright + axe-core for comprehensive WCAG compliance testing
• Multiple Fallback Strategies: Robust browser launch with multiple fallback options
• Streaming Logs: Real-time progress updates during scans
• Free Scan Fallback: HTML-based scanning when Playwright fails
• External Browser Service: Can connect to external Playwright browser services
• CORS Enabled: Ready for cross-origin requests from your main application

📋 Prerequisites

• Node.js 18+
• Linux VPS with sufficient memory (2GB+ recommended)
• Git

🛠️ Installation

1. Clone and Setup

# Clone the worker repository
git clone <your-worker-repo-url>
cd ada-snapfix-worker

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install chromium

2. Environment Variables

Create a .env file:

# Server configuration
PORT=3000
NODE_ENV=production

# Optional: External browser service (if using separate browser service)
PLAYWRIGHT_BROWSER_WS_ENDPOINT=wss://your-browser-service.com/browser

# Optional: Custom Chromium executable path
PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium-browser

3. System Dependencies (Linux VPS)

Install required system packages:

# Ubuntu/Debian
sudo apt update
sudo apt install -y \
  chromium-browser \
  libnss3 \
  libatk-bridge2.0-0 \
  libdrm2 \
  libxkbcommon0 \
  libxcomposite1 \
  libxdamage1 \
  libxrandr2 \
  libgbm1 \
  libasound2

# CentOS/RHEL
sudo yum install -y \
  chromium \
  nss \
  atk \
  libdrm \
  libxkbcommon \
  libXcomposite \
  libXdamage \
  libXrandr \
  mesa-libgbm \
  alsa-lib

🚀 Running the Worker

Development Mode

npm run dev

Production Mode

npm start

Using PM2 (Recommended for Production)

# Install PM2 globally
npm install -g pm2

# Start the worker
pm2 start server.js --name "ada-snapfix-worker"

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

📡 API Endpoints

Health Check

GET /health

Returns service status and version information.

Browser Service (WebSocket)

GET /browser

Launches a Playwright browser and returns WebSocket endpoint.

Fullscan (Streaming)

POST /api/scan
Content-Type: application/json
Accept: text/event-stream

{
  "url": "https://example.com"
}

Performs full accessibility scan with real-time streaming logs.

Fullscan (Synchronous)

POST /api/scan-sync
Content-Type: application/json

{
  "url": "https://example.com"
}

Performs full accessibility scan and returns results in single response.

🔧 Integration with Main App

1. Update Main App Configuration

In your main Ada SnapFix application, update the environment variable:

PLAYWRIGHT_BROWSER_WS_ENDPOINT=wss://your-worker-vps.com/browser

2. Update API Calls

Modify your main app to call the worker's scan endpoint:

// Example: Call worker for fullscan
const response = await fetch('https://your-worker-vps.com/api/scan', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ url: 'https://example.com' })
});

// Handle streaming response
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}

🔍 Monitoring and Logs

PM2 Monitoring

# View logs
pm2 logs ada-snapfix-worker

# Monitor processes
pm2 monit

# Restart service
pm2 restart ada-snapfix-worker

Health Monitoring

# Check service health
curl https://your-worker-vps.com/health

# Expected response:
{
  "status": "healthy",
  "service": "ada-snapfix-worker",
  "version": "1.0.0",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

🚨 Troubleshooting

Browser Launch Issues

1. Check system dependencies:

   ldd $(which chromium-browser)

2. Verify Playwright installation:

   npx playwright install chromium

3. Check available memory:

   free -h

Network Issues

1. Check firewall settings:

   sudo ufw status
   sudo ufw allow 3000

2. Verify CORS configuration:

   • Ensure your main app domain is allowed
   • Check browser console for CORS errors

Performance Issues

1. Monitor resource usage:

   htop

2. Adjust browser arguments in lib/fullscan.js:

   • Reduce memory usage
   • Disable unnecessary features

🔄 Deployment Options

1. Direct VPS Deployment

• Deploy directly on your Linux VPS
• Use PM2 for process management
• Configure nginx as reverse proxy

2. Docker Deployment

FROM node:18-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    chromium \
    libnss3 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY package*.json ./
RUN npm install
RUN npx playwright install chromium

COPY . .
EXPOSE 3000
CMD ["npm", "start"]

3. Cloud Platform Deployment

• Railway: Supports Playwright out of the box
• Render: Free tier available
• Fly.io: Good for global distribution

📊 Performance Optimization

Memory Optimization

• Monitor memory usage during scans
• Adjust browser launch arguments
• Implement scan queuing for high traffic

Network Optimization

• Use CDN for axe-core script
• Implement request caching
• Optimize response streaming

🔐 Security Considerations

1. Firewall Configuration: Only expose necessary ports
2. Rate Limiting: Implement request rate limiting
3. Input Validation: Validate URLs before scanning
4. CORS Configuration: Restrict to trusted domains
5. HTTPS: Use SSL/TLS in production

📈 Scaling

Horizontal Scaling

• Deploy multiple worker instances
• Use load balancer for distribution
• Implement health checks

Vertical Scaling

• Increase VPS resources
• Optimize browser configurations
• Implement connection pooling

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes
4. Test thoroughly
5. Submit pull request

📄 License

MIT License - see LICENSE file for details

---

Need help? Check the logs first, then create an issue with specific error messages!