Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1,804 Commits
.github
.github
 
 
.planning
.planning
 
 
bin
bin
 
 
deploy
deploy
 
 
docs
docs
 
 
k8s
k8s
 
 
luqen-plugins-catalogue
luqen-plugins-catalogue
 
 
packages
packages
 
 
pipelines
pipelines
 
 
plugins/packages/git-host-github
plugins/packages/git-host-github
 
 
powerbi-connector
powerbi-connector
 
 
scripts
scripts
 
 
shared/acr
shared/acr
 
 
tools
tools
 
 
.dockerignore
.dockerignore
 
 
.gitignore
.gitignore
 
 
.luqen.json
.luqen.json
 
 
.npmignore
.npmignore
 
 
.nvmrc
.nvmrc
 
 
CHANGELOG.md
CHANGELOG.md
 
 
DESIGN.md
DESIGN.md
 
 
Dockerfile
Dockerfile
 
 
LICENSE
LICENSE
 
 
PRODUCT.md
PRODUCT.md
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
install.command
install.command
 
 
install.ps1
install.ps1
 
 
install.sh
install.sh
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
start.sh
start.sh
 
 

Repository files navigation

Luqen

Know exactly where your website breaks accessibility law — and fix it before anyone else notices.

Luqen scans your entire website for WCAG violations and tells you which laws in which countries require you to fix each one. One scan covers 58 jurisdictions (EU, US, UK, and more), so your legal and dev teams see the same picture. Run it from the command line, a browser dashboard, an in-dashboard agent companion, or your IDE — it works for a solo developer checking one page or an enterprise team monitoring hundreds of sites across multiple languages.

Version License Tests Coverage WCAG TypeScript

What's new in v3.1.0

  • Agent history — stacked, AI-titled conversation list with debounced search, infinite-scroll pagination, resume, soft-delete + audit, and rename. See docs/guides/agent-history.md.
  • Multi-step tools — parallel-dispatch tool calls with a shared 3-retry budget, a 5-step iteration cap, a chip-strip transparency UI, and rationale capture across providers. See docs/guides/multi-step-tools.md.
  • Streaming UX + share permalinks — stop / retry / edit-and-resend on the most-recent turn, copy-as-markdown, and org-scoped /agent/share/:shareId permalinks with default 30-day expiry. See docs/guides/streaming-share-links.md.
  • Multi-org switching — native <select> org switcher in the drawer header (admin.system only), force-new-conversation on switch, JWT-driven ToolContext.orgId propagation. See docs/guides/multi-org-switching.md.

v3.0.0 (2026-04-24) shipped Streamable HTTP MCP endpoints + OAuth 2.1 + PKCE + DCR on every service, plus the in-dashboard agent companion (text + speech, SSE streaming, native-dialog tool confirmation, persistent history, audit log).

What is Luqen?

Luqen is an enterprise accessibility platform that gives teams visibility into digital accessibility and guides them toward being more accessible and inclusive. It orchestrates site-wide WCAG scanning, maps violations to legal obligations across 58 jurisdictions, tracks issues through assignment and remediation workflows, and monitors regulatory changes — all through a unified dashboard, agent companion, CLI, MCP servers, and REST API.

Under the hood, Luqen uses the pa11y library directly and axe-core for scanning, but wraps them in a complete platform: team management, role-based access, issue assignment lifecycles, scheduled scans, email reports, plugin ecosystem, and more. The goal is not just to find accessibility problems, but to help organizations systematically fix them.

Genuine remediation, not an overlay. Luqen finds real WCAG violations and helps you fix them in your actual source — it is the opposite of an accessibility overlay/widget. Overlays don't deliver compliance (the FTC fined a leading overlay vendor $1M in 2025 over exactly that claim) and don't stop lawsuits (~a quarter of 2025 US web-accessibility suits hit sites that already had a widget). See Why not an overlay? for the evidence and a side-by-side comparison.

Why "Luqen"? A coined name, unique to this project. Pronounced "LOO-ken".

Key Features

  • WCAG 2.1 AA verified — all dashboard pages pass pa11y automated checks with correct color contrast, screen reader labels, and semantic markup.
  • Authenticated scanning — scan pages behind login using custom HTTP headers or pa11y pre-scan actions.
  • Site-wide scanning via built-in pa11y scanner — sitemap + crawl discovery, concurrency control, robots.txt respect.
  • Legal compliance checking against 58 jurisdictions and 62 regulations (EU EAA, Section 508, ADA, UK Equality Act, RGAA, BITV, JIS X 8341-3, …).
  • Confirmed violations vs needs-review — errors are confirmed violations; notices are flagged separately.
  • Source code mapping — maps WCAG issues to source files in Next.js, Nuxt, SvelteKit, Angular, and plain HTML projects.
  • Git host integration — GitHub, GitLab, Azure DevOps; per-developer PATs encrypted with AES-256-GCM; create PRs from accessibility fix proposals.
  • Auto-fix proposals — generates unified diffs for common issues (missing alt, aria-label, lang).
  • Template issue deduplication — issues on 3+ pages are grouped into "Template & Layout Issues", removing ~84% of duplicate noise.
  • Five interfaces — CLI for humans, per-service Streamable HTTP MCP for external AI agents (OAuth 2.1 + PKCE + DCR), in-dashboard agent companion (text + speech), OAuth2 REST API with live /docs (Swagger UI), web dashboard.
  • Regulatory monitoring — watches legal sources for changes and creates update proposals when regulations evolve.
  • Progressive authentication — start with API key (solo), add local users (team), or install an SSO plugin (enterprise).
  • Per-org compliance tokens — each organization can configure its own compliance API credentials, with global-token fallback.
  • Pluggable storage — modular StorageAdapter with 14 repository interfaces; SQLite default, PostgreSQL and MongoDB available as plugins.
  • Security hardening — @fastify/helmet (CSP, HSTS, X-Frame-Options), CSRF, XSS prevention, per-installation encryption salt, SSRF protection, global rate limiting, AES-256-GCM session cookies.
  • LLM service — dedicated @luqen/llm microservice (port 4200) for provider management, model registry, and capability-based routing with automatic fallback chains. Supports OpenAI, Anthropic, Ollama, and any OpenAI-compatible endpoint. Capabilities: extract-requirements, generate-fix, analyse-report, discover-branding.
  • LLM-powered source intelligence — upload regulation documents or add government source URLs; the LLM service routes extraction through the configured capability chain.
  • Plugin system — 11 plugins in the remote catalogue: auth (Entra ID, Okta, Google), notifications (Slack, Teams, Email), storage (S3, Azure Blob); plus 3 built-in git host plugins.
  • Granular permissions — fine-grained scopes (e.g. users.create, users.delete, mcp.use, admin.org, admin.system) assignable to custom roles.
  • Power BI custom connector — Power Query M connector wrapping the Data API for scans, trends, compliance summary, and issues data sources.
  • IdP group → team sync — auth plugins read group memberships from tokens and auto-sync to dashboard teams on SSO login.
  • Server-side PDF export — PDFKit-based generation at GET /api/v1/export/scans/:id/report.pdf (no Chromium dependency).

Agent companion

Luqen v3.0+ ships an in-dashboard conversational agent. Drawer-launched, text + speech input (Web Speech API where supported), SSE streaming, native-dialog confirmation for destructive tool calls, context hints (recent scans + active guidelines injected per turn), token-budget compaction at 85% of model max, persistent history with rolling 20-turn window, and an /admin/audit viewer with CSV export.

See docs/guides/agent-companion.md for the full surface (audience subsections for end users and admins).

MCP integration

Every Luqen service (compliance, branding, llm, dashboard) exposes a Streamable HTTP MCP endpoint at /api/v1/mcp with OAuth 2.1 Authorization Code + PKCE + Dynamic Client Registration. External MCP clients — Claude Desktop, Cursor, Windsurf, IDE plugins — connect via the documented OAuth flow; tool visibility = RBAC ∩ scope, gated by the mcp.use permission per org.

See docs/guides/mcp-integration.md for end-user and admin setup, including the mcp-remote bridge for stdio clients and direct Streamable HTTP for native clients.

The Luqen @luqen/core package also ships a stdio MCP server (packages/core/dist/mcp.js) for purely local scanning use; see docs/QUICKSTART.md#ide-integration for that legacy path.

Architecture

                       ┌──────────────────────────┐
    Users / CI   ────► │     @luqen/dashboard     │ ◄──── Plugins
    Web browser        │         (port 5000)      │       (auth · notify · storage)
    Power BI           │   Web UI · REST · MCP    │
                       │   Agent companion        │
                       │   Scan orchestrator      │
                       └──┬────────┬──────────┬───┘
                          │        │          │         All service calls over
                          ▼        ▼          ▼          OAuth2 + RS256 JWT
                  ┌──────────┐ ┌──────────┐ ┌──────────┐
                  │  @luqen  │ │  @luqen  │ │  @luqen  │
                  │compliance│ │ branding │ │   llm    │
                  │  (4000)  │ │  (4100)  │ │  (4200)  │
                  │          │ │          │ │          │
                  │ jurisdic.│ │  colors  │ │ providers│
                  │  regs.   │ │  fonts   │ │  models  │
                  │  WCAG    │ │  logos   │ │ routing  │
                  │   MCP    │ │   MCP    │ │   MCP    │
                  └────┬─────┘ └──────────┘ └────▲─────┘
                       │                         │
                       └──── LLM capabilities ───┘
                              (embedded lib)

       ┌─────────────────────┐         ┌─────────────────────┐
       │    @luqen/core      │         │   @luqen/monitor    │
       │  CLI · stdio MCP    │         │  watches legal src  │
       │  pa11y scanner      │         │  creates proposals  │
       └─────────────────────┘         └─────────────────────┘

Request flow at a glance

From To Purpose
Dashboard Compliance Check scans against WCAG obligations; map issues to regulations
Dashboard Branding Store guidelines; retag historical scans; discover brand from URL
Dashboard LLM AI fix suggestions · report summaries · brand discovery curation
Compliance LLM Route regulation extraction through capability chains (embedded library)
Monitor Compliance Submit update proposals when legal sources change
External MCP client Any service /api/v1/mcp Tool calls over Streamable HTTP, gated by OAuth 2.1 scopes + mcp.use
Core CLI — Scan sites locally with no backend dependency

Composition Paths

Pick the path that matches your use case:

Path Persona Components Time
Quick scan Developer Core CLI 30 sec
IDE / agent integration Developer Per-service MCP + OAuth 2.1 5 min
CI/CD gate Dev/QA Core CLI 10 min
Compliance check Dev/Legal Core + Compliance 10 min
Compliance API Automation Compliance 5 min
Full dashboard All All services 15 min
Regulatory monitoring Legal Monitor + Compliance 10 min
Everything Org-wide All packages 5 min

See docs/paths/ for detailed guides on each path.

Quick start

The canonical end-to-end install walkthrough lives at docs/getting-started/installation.md, with per-environment-variable detail in docs/deployment/installer-env-vars.md and the per-version installer changelog at docs/deployment/installer-changelog.md.

One-line install (Linux)

curl -fsSL https://raw.githubusercontent.com/trunten82/luqen/master/install.sh | bash

The wizard offers three modes:

Mode What it installs Best for
Developer tools CLI only (luqen command) Quick scans from the terminal
Full platform All services on bare metal (systemd / launchd / NSSM) Production servers without Docker
Docker All services via Docker Compose Fastest full deployment

macOS users run install.command; Windows users run install.ps1. All three scripts cover the v3.1.0 env-var set (including *_PUBLIC_URL for OAuth issuer + MCP discovery) and migrate to head migration 061 in one pass.

Docker install

git clone https://github.com/trunten82/luqen.git
cd luqen
export SESSION_SECRET="$(openssl rand -base64 32)"
docker compose up -d

Services start on ports 4000 (compliance), 4100 (branding), 4200 (LLM), and 5000 (dashboard). Scanning is built in — no external pa11y-webservice required.

CLI-only

cd packages/core && npm link
luqen scan https://example.com --format both

Reports are written to ./luqen-reports/.

Service setup

Each service follows the same pattern: generate JWT keys, create an OAuth2 client, then start. The end-to-end install guide covers this for all four services in one pass; per-service details live in the package READMEs:

Service Port Setup guide
@luqen/compliance 4000 docs/reference/compliance-config.md
@luqen/branding 4100 docs/branding/README.md
@luqen/llm 4200 packages/llm/README.md
@luqen/dashboard 5000 docs/reference/dashboard-config.md
@luqen/monitor — docs/reference/monitor-config.md

Live OpenAPI docs are served at /docs per service (Swagger UI). Committed JSON snapshots live under docs/reference/openapi/.

For the LLM service in particular, run bash packages/llm/installer/install-llm.sh from the project root for an interactive setup that configures JWT keys, an OAuth client, providers, and capability assignments.

Update & restart

cd ~/luqen
git pull && npm install && npm run build --workspaces
systemctl restart luqen-compliance luqen-branding luqen-llm luqen-dashboard

For full service-management commands (status, logs, stop/start, disable, clean reinstall) see docs/QUICKSTART.md#update--restart.

Packages

Package Description Docs
@luqen/core Site scanner, source mapper, fix engine, CLI, stdio MCP server docs/reference/core-config.md
@luqen/compliance Compliance rule engine, REST API, MCP endpoint, source intelligence docs/reference/compliance-config.md
@luqen/branding Brand-guideline matching service — colour, font, selector matching; image upload; scan retag docs/branding/README.md
@luqen/dashboard Web dashboard — scan management, agent companion, admin UI, MCP endpoint docs/reference/dashboard-config.md
@luqen/llm LLM microservice — providers, model registry, capability-based routing with retry/fallback, per-org prompt overrides packages/llm/README.md
@luqen/monitor Regulatory monitor agent — watches legal sources, creates update proposals docs/reference/monitor-config.md

Plugins (11 available)

Catalogue plugins are distributed via the plugin catalogue and installed from the dashboard UI, CLI (luqen-dashboard plugin install <name>), or REST API. Git host plugins are built-in and auto-activated.

Plugin Type Description
auth-entra Auth Azure Entra ID SSO (MSAL)
auth-okta Auth Okta OIDC
auth-google Auth Google Workspace OAuth 2.0
notify-slack Notification Slack webhook alerts
notify-teams Notification Microsoft Teams webhook alerts
notify-email Notification SMTP email reports
storage-s3 Storage AWS S3 report storage
storage-azure Storage Azure Blob report storage
git-host-github Git Host GitHub / GitHub Enterprise PR creation
git-host-gitlab Git Host GitLab / self-hosted merge request creation
git-host-azure-devops Git Host Azure DevOps pull request creation

LLM providers (OpenAI, Anthropic, Ollama, OpenAI-compatible) are managed directly through the @luqen/llm service — no plugins required. Configure them from Admin → LLM.

See docs/plugins/README.md for plugin development.

Documentation

Test suite

npm test --workspaces

The project maintains 85%+ statement coverage across 2,300+ tests. Run with coverage:

npm run test:coverage --workspaces

Built on

Luqen is built on proven open-source components.

Accessibility scanning

Component Role
pa11y Core WCAG scanner — Luqen drives pa11y directly, no webservice required
axe-core Secondary accessibility rule engine (used via pa11y)
Puppeteer Headless Chrome for page rendering during scans

Web framework

Component Role
Fastify HTTP server for the dashboard and all microservices
@fastify/secure-session Encrypted cookie sessions (AES-256-GCM)
@fastify/csrf-protection CSRF token generation and verification
@fastify/helmet Security headers (CSP, HSTS, X-Frame-Options)
@fastify/rate-limit Per-route rate limiting
@fastify/multipart File upload handling (CSS import, fixtures)
@fastify/swagger OpenAPI spec generation across all services

Frontend

Component Role
HTMX Hypermedia-driven UI — partial page swaps without a JS build step
Handlebars Server-side HTML templating

Database

Component Role
better-sqlite3 Synchronous SQLite driver — primary storage backend
ioredis Redis client for job queues and distributed rate limiting

Auth & security

Component Role
jose RS256 JWT signing and verification for OAuth2 service auth
bcrypt Password hashing for local user accounts
Zod Runtime schema validation for API inputs

AI / LLM

Component Role
Ollama Local LLM inference — default provider for the @luqen/llm service
OpenAI Node SDK API client for OpenAI and any OpenAI-compatible endpoint

Export & reporting

Component Role
PDFKit Server-side PDF report generation (no Chromium dependency)
ExcelJS Excel export for scan results and trends

Testing

Component Role
Vitest Unit and integration test runner
Playwright End-to-end browser testing

License

MIT — see LICENSE.

About

Accessibility testing agent using pa11y

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages