1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91# Architecture Overview
Equalify is a web accessibility scanning and monitoring platform built on a serverless AWS architecture. This document provides a high-level overview of the system's components and how they interact.
## System Architecture
Equalify follows a modern serverless architecture with clear separation between the frontend, backend API, and scanning microservices.
### Core Components
| Component | Technology | Purpose |
|-----------|------------|---------|
| Frontend | React + Vite | User interface for managing audits and viewing results |
| Backend API | Node.js (AWS Lambda) | Authentication, audit management, and data access |
| Scan Router | TypeScript Lambda | Routes scan requests to appropriate scanners |
| HTML Scanner | TypeScript Lambda + Chromium | Scans web pages using axe-core |
| PDF Scanner | TypeScript + Java Lambdas | Scans PDF documents using veraPDF |
| Database | PostgreSQL (via Hasura) | Stores audits, URLs, blockers, and scan results |
| Message Queue | AWS SQS (FIFO) | Manages scan job distribution |
### Data Flow
1. **User creates an audit** → Frontend sends request to Backend API
2. **Audit is saved** → Backend stores audit and URLs in PostgreSQL
3. **Scan is triggered** → Backend invokes the SQS Router Lambda
4. **Jobs are queued** → Router distributes URLs to HTML or PDF SQS queues
5. **Scanners process jobs** → Lambdas consume from SQS and perform scans
6. **Results are returned** → Scanners POST results to the webhook endpoint
7. **Data is stored** → Backend processes and stores blockers in the database
8. **User views results** → Frontend queries and displays scan results
## Repository Structure
```
equalify/
├── apps/
│ ├── backend/ # API Lambda (Express-like router)
│ │ ├── routes/ # API endpoints organized by auth level
│ │ └── utils/ # Shared utilities (DB, auth, etc.)
│ └── frontend/ # React SPA
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── routes/ # Page components
│ │ ├── queries/ # API/GraphQL queries
│ │ └── hooks/ # Custom React hooks
│ └── public/
├── services/
│ ├── aws-lambda-scan-sqs-router/ # Job distribution
│ ├── aws-lambda-scan-html/ # HTML/web scanning
│ ├── aws-lambda-scan-pdf/ # PDF scanning orchestrator
│ └── aws-lambda-verapdf-interface/ # Java PDF scanner
└── shared/
├── types/ # TypeScript types and Zod schemas
└── convertors/ # Result format converters
```
## Authentication
Equalify supports two authentication mechanisms:
- **AWS Cognito**: Traditional username/password authentication with JWT tokens
- **SSO (Single Sign-On)**: Enterprise authentication via Azure AD/MSAL
Both methods issue JWT tokens that are validated by the backend API before processing authenticated requests.
## Technology Stack
### Frontend
- **React 19** with TypeScript
- **Vite** for build tooling
- **TanStack Query** for data fetching
- **AWS Amplify** for authentication
- **Radix UI** for accessible components
- **Recharts** for data visualization
### Backend
- **Node.js** running on AWS Lambda
- **PostgreSQL** database with Hasura GraphQL
- **AWS SDK** for Lambda invocation, SES, and S3
- **Zod** for runtime validation
### Infrastructure
- **AWS Lambda** for serverless compute
- **AWS SQS** (FIFO queues) for job management
- **AWS S3** for static hosting
- **AWS CloudFront** for CDN
- **AWS Cognito** for authentication
---
*For detailed information about specific components, see the other guides in this folder.*