# kvnq-poza/a11y-live architecture

> Architecture diagram of the GitHub repository kvnq-poza/a11y-live, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kvnq-poza/a11y-live
- Repository: https://github.com/kvnq-poza/a11y-live

## Overview

##### Project Type and Purpose
- This is a front-end JavaScript library/application (“A11y Live”) that runs in the browser to provide real-time WCAG accessibility feedback. It bundles a core engine (mutation observer, rule engine, reporter) and a UI layer (overlay, panel, tutorial).

##### File Structure Analysis
- Top level: HTML entry points (index.html, demo.html), assets (CSS/JS for demos), package.json (npm support), and src folder.
- src/core: engine.js (main class), rules.js (rule definitions), reporter.js (aggregates results)
- src/ui: overlay.js, panel.js, tutorial.js, ui-Manager.js (coordinates UI components)

##### README Insights
- Core classes: A11yEngine, RuleEngine, Reporter
- UI components: PanelComponent, OverlayComponent, TutorialComponent
- Browser APIs: MutationObserver, IntersectionObserver
- Events: custom DOM events for engine start/stop and violation updates
- Integration methods: direct script include or ES/CJS import

##### Main Components
a. Core Layer
- A11yEngine
- RuleEngine (holds & executes accessibility rules)
- Reporter (aggregates violations, formats exports)
b. UI Layer
- UIManager (initializes & wires UI components)
- PanelComponent (list & filter violations)
- OverlayComponent (highlights elements)
- TutorialComponent (guided walkthrough)
c. Browser APIs (external services)
- MutationObserver (feeds DOM changes into A11yEngine)
- IntersectionObserver, getComputedStyle, etc.
d. Host Page
- HTML entry point(s)
- User code (integration scripts or modules)
e. Optional Build/Dev Tooling
- package.json → npm scripts (install, start, test)

##### Relationships and Data Flow
1. Host Page loads engine.js → instantiate A11yEngine
2. A11yEngine
→ registers MutationObserver on target (default document.body)
→ on mutation batch, invokes RuleEngine.test(elementList)
→ collects AnalysisResult objects
→ passes results to Reporter
→ emits custom events (a11y-live-started, violation-found, a11y-live-stopped)
3. UIManager listens to engine events
→ updates PanelComponent (lists violations)
→ commands OverlayComponent to highlight elements
→ manages TutorialComponent lifecycle
4. Reporter can export data (JSON/CSV/HTML) on demand

##### Architectural Patterns & Design Principles
- Modular separation: core engine vs. UI
- Observer pattern: browser MutationObserver + custom DOM events
- Strategy/Plugin pattern: rules are pluggable objects in RuleEngine
- MVC-like pattern: Engine (Model), UIManager/View components → decoupled via events
- Single responsibility: each module has a clear domain (analysis vs. rendering vs. reporting)

##### Technologies & Frameworks
- Vanilla ES6 modules (engine, reporter, ui modules)
- Browser native APIs (MutationObserver, IntersectionObserver)
- npm for packaging/testing (Jest)
- CSS/JS for UI overlays and panel styling

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Host & Tooling"
        HostPage["Host Page (index.html, demo.html)"]:::host
        Package["Build/Dev Tooling (package.json)"]:::tooling
    end

    subgraph "External Services"
        MutObs["MutationObserver"]:::external
        IntObs["IntersectionObserver"]:::external
        UA["User Actions (keyboard shortcuts)"]:::external
    end

    subgraph "Core Layer"
        AE["A11yEngine"]:::core
        RE["RuleEngine"]:::core
        RP["Reporter"]:::core
    end

    subgraph "UI Layer"
        UI["UIManager"]:::ui
        Panel["PanelComponent"]:::ui
        Overlay["OverlayComponent"]:::ui
        Tutorial["TutorialComponent"]:::ui
    end

    HostPage -->|"loads engine.js"| AE
    Package -->|"npm scripts"| HostPage

    MutObs -->|"MutationObserver callback"| AE
    AE -->|"registers MutationObserver"| MutObs

    AE -->|"test(elements)"| RE
    RE -->|"AnalysisResult objects"| RP

    RP -->|"emitEvent('violation-found')"| UI
    AE -->|"emitEvent('a11y-live-started')"| UI
    AE -->|"emitEvent('a11y-live-stopped')"| UI

    UI -->|"updatePanel"| Panel
    UI -->|"highlightElements"| Overlay
    UI -->|"manageTutorial"| Tutorial

    UA -->|"trigger UI actions"| UI
    UA -->|"exportRequest"| RP

    Overlay -->|"uses IntersectionObserver"| IntObs

    click AE "https://github.com/kvnq-poza/a11y-live/blob/main/src/core/engine.js"
    click RE "https://github.com/kvnq-poza/a11y-live/blob/main/src/core/rules.js"
    click RP "https://github.com/kvnq-poza/a11y-live/blob/main/src/core/reporter.js"
    click UI "https://github.com/kvnq-poza/a11y-live/blob/main/src/ui/ui-Manager.js"
    click Panel "https://github.com/kvnq-poza/a11y-live/blob/main/src/ui/panel.js"
    click Overlay "https://github.com/kvnq-poza/a11y-live/blob/main/src/ui/overlay.js"
    click Tutorial "https://github.com/kvnq-poza/a11y-live/blob/main/src/ui/tutorial.js"
    click MutObs "https://github.com/kvnq-poza/a11y-live/blob/main/src/core/engine.js"
    click IntObs "https://github.com/kvnq-poza/a11y-live/blob/main/src/ui/overlay.js"
    click HostPage "https://github.com/kvnq-poza/a11y-live/blob/main/index.html"
    click HostPage "https://github.com/kvnq-poza/a11y-live/blob/main/demo.html"
    click Package "https://github.com/kvnq-poza/a11y-live/blob/main/package.json"

    classDef core fill:#f9f,stroke:#333;
    classDef ui fill:#ccf,stroke:#333;
    classDef external fill:#efe,stroke:#333,stroke-dasharray:5 5;
    classDef host fill:#fee,stroke:#333;
    classDef tooling fill:#eec,stroke:#333;
```
