stock-bot/apps/wcag-ada/README.md

WCAG-ADA Compliance Monitoring Platform

An automated web accessibility compliance monitoring system that continuously scans websites for WCAG and ADA compliance issues, provides detailed reports, and offers remediation suggestions.

Architecture

The platform consists of four main services:

1. Scanner Service (/scanner)

• Performs accessibility scans using axe-core and Playwright
• Supports WCAG 2.0, 2.1, and 2.2 compliance levels (A, AA, AAA)
• Generates detailed violation reports with fix suggestions
• Captures screenshots of accessibility issues

2. API Service (/api)

• RESTful API built with Hono framework
• JWT-based authentication
• Redis-backed rate limiting
• PostgreSQL database with Prisma ORM
• BullMQ integration for job queuing

3. Worker Service (/worker)

• Processes scan jobs from the queue
• Runs scheduled scans based on website configurations
• Handles scan result processing and storage
• Provides health monitoring endpoints

4. Dashboard (/dashboard)

• React 18 SPA with Vite
• Real-time scan monitoring
• Compliance reporting and analytics
• Website and scan management
• Built with TailwindCSS and Radix UI

Configuration

The application uses a sophisticated configuration system that loads settings from multiple sources:

1. Default values (defined in schemas)
2. Configuration files (.env, config.json)
3. Environment variables
4. Command-line arguments

Key Configuration Files

• /config/src/schemas/ - Zod schemas defining all configuration options
• /config/src/config-instance.ts - Main configuration loader
• .env - Environment-specific settings

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL
• Redis
• Bun (recommended) or npm/yarn

Installation

1. Install dependencies:

bun install

2. Set up the database:

cd apps/wcag-ada/api
bunx prisma migrate dev

3. Configure environment variables:

cp .env.example .env
# Edit .env with your settings

Running Services

Start all services concurrently:

bun run dev

Or run individual services:

# API
cd apps/wcag-ada/api
bun run dev

# Worker
cd apps/wcag-ada/worker
bun run dev

# Dashboard
cd apps/wcag-ada/dashboard
bun run dev

# Scanner (for testing)
cd apps/wcag-ada/scanner
bun run example

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user

Websites

• GET /api/websites - List user's websites
• POST /api/websites - Add new website
• PUT /api/websites/:id - Update website
• DELETE /api/websites/:id - Delete website

Scans

• POST /api/scans - Start new scan
• GET /api/scans/:id - Get scan status
• GET /api/scans/:id/result - Get scan results
• GET /api/scans/:id/violations - Get violations
• DELETE /api/scans/:id - Cancel scan

Reports

• GET /api/reports/compliance/:websiteId - Get compliance report
• GET /api/reports/trends/:websiteId - Get trend analysis

Health

• GET /health - Service health check
• GET /health/stats - Detailed statistics

Development

Project Structure

apps/wcag-ada/
├── api/           # REST API service
├── config/        # Configuration management
├── dashboard/     # React web interface
├── scanner/       # Accessibility scanning engine
├── shared/        # Shared types and utilities
└── worker/        # Background job processor

Testing

Run tests for all services:

bun test

Building for Production

bun run build

Deployment

The application is designed to be deployed as separate microservices. Each service can be containerized and deployed independently.

Docker Support

Build Docker images:

docker build -t wcag-ada-api -f apps/wcag-ada/api/Dockerfile .
docker build -t wcag-ada-worker -f apps/wcag-ada/worker/Dockerfile .
docker build -t wcag-ada-dashboard -f apps/wcag-ada/dashboard/Dockerfile .

License

Proprietary - All rights reserved