Systemic Accessibility Analyzer & Orchestrator

Status: Early alpha. Suitable for local analysis and static dashboard generation. Public server deployment is not yet hardened.

This repository houses an end-to-end platform for running automated accessibility scans across large digital estates and analyzing the outputs for systemic issues. Instead of treating accessibility violations as isolated page-level bugs, this system groups them by shared UI components and root causes, allowing teams to prioritize fixes that resolve issues across multiple pages simultaneously.

The system is split into two interconnected local apps:

1. Auth & Scan Service (tools/auth_service): Accepts job submissions, handles authentication, runs the selected accessibility frameworks, and exposes status pages.
2. Analysis Service (analyzer): Reads the generated reports, builds systemic issue clusters, and serves the interactive dashboards and Excel workbooks.

---

🚀 Installation

1. Create and activate the virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Install Playwright browsers (required for scanners):

python3 -m playwright install chromium

---

⚙️ Configuration Setup

Because the analyzer needs to read the reports generated by the tools directory, you must ensure the analyzer points to the correct jobs folder.

In your analyzer configuration (e.g., analyzer/app/main.py or wherever it is defined), update DEFAULT_LOCAL_JOBS_DIR to point to the new relative path inside the tools directory:

import os
from pathlib import Path

# Get the absolute path to the tools/auth_service/jobs directory relative to the analyzer
BASE_DIR = Path(os.path.abspath(__file__)).parent.parent.parent
DEFAULT_LOCAL_JOBS_DIR = BASE_DIR / "tools" / "auth_service" / "jobs"

---

🏃 Running the Services

To keep the application traffic separated, run the two services on different ports. Open two separate terminal windows. Make sure your unified venv is activated in both!

Terminal 1 — Start the Auth & Scan Service (Port 8001)

cd tools
python3 -m uvicorn main:app --reload --port 8001

Terminal 2 — Start the Analysis Service (Port 8000)

cd analyzer
python3 -m uvicorn app.main:app --reload --port 8000

---

🔄 User Workflow & URLs

Once both servers are running, follow this happy-path workflow:

1. Submit a job: Open the scanner interface at http://127.0.0.1:8001/. Enter your target URLs, select your tools, and optionally provide login credentials.
2. Monitor progress: Upon submission, you will be redirected to the public result/status page (http://127.0.0.1:8001/r/<slug>), which auto-refreshes while the scanners run. You can view all queued and historical jobs at http://127.0.0.1:8001/jobs-view.
3. View the Dashboard: When the scan completes, it will automatically redirect you to the Analysis Dashboard served on Port 8000 (http://127.0.0.1:8000/jobs/<job-id>/dashboard).

Note: Always use job-relative URLs for the dashboard (e.g., /jobs/<job-id>/dashboard). Do not use the legacy global /dashboard route.

---

🛠️ Supported Tools & WCAG Mapping

The platform automatically detects report formats, normalizes them into a canonical violation model, and maps them to WCAG 2.2 Success Criteria.

Tool Framework	WCAG 2.0 (A/AA/AAA)	WCAG 2.1 (A/AA/AAA)	WCAG 2.2 (A/AA/AAA)	WCAG 3 Draft
Playwright/Axe-core	A / AA (Partial AAA)	A / AA (Partial AAA)	A / AA	-
Axe-scan	A / AA (Partial AAA)	A / AA (Partial AAA)	A / AA	-
UUV	A / AA	A / AA	A / AA	-
Lighthouse	A / AA	A / AA	A / AA	-
IBM Accessibility Checker	A / AA	A / AA	A / AA	-
Oobee	A / AA / AAA	A / AA / AAA	Limited	-
Pa11y-CI	A / AA / AAA	A / AA / AAA	A / AA (via axe)	-
Html-sniffer	A / AA / AAA	A / AA / AAA	No	-
Siteimprove Alfa	A / AA / AAA	A / AA / AAA	No	-
Nu HTML Checker	Markup / ARIA	Markup / ARIA	No	-
SpecA11y	A / AA / AAA	A / AA / AAA	No	Draft outcomes

---

📊 Analytics & Exports

Instead of isolated page issues, violations are grouped using a unique fingerprint (ruleId + DOM/Component context) to surface recurring component defects.

Power BI Ready Exports

The generated XLSX workbooks contain dedicated sheets designed specifically for Business Intelligence ingestion:

• Power BI Findings: A flattened, row-level dataset with sorting columns and display labels.
• Power BI Patterns: Grouped, recurring-issue datasets perfect for prioritization visuals.
• Fix Once Benefit Many: A pre-ranked list exposing top_fix_rank, affected_pages_count, and owner_team intended to drive immediate developer action.
• Star Schema Support: Fact and Dimension tables (Fact Findings, Dim Page, Dim Rule, Dim Component, Dim Pattern) for advanced Power BI data modeling.

Static Netlify Deployment

The analyzer output can be compiled into a portable static dashboard using build_static_netlify.py. This reads the reports/ folder, bundles the UI into a dist/ folder, and can be instantly hosted via Netlify.