# sclavijosuero/wick-a11y architecture

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

- Interactive diagram: https://gitdiagram.com/sclavijosuero/wick-a11y
- Repository: https://github.com/sclavijosuero/wick-a11y

## Overview

##### Main Components
- Cypress Integration Layer – This includes integration hooks in the Cypress configuration (e.g., the import and registration of accessibility tasks in cypress.config.js) as well as custom commands (imported in cypress/support/e2e.js or tests).
- Accessibility Analysis Engine – Built on top of the axe-core and cypress-axe plugins, this is where the actual accessibility tests, rule configurations, and violation aggregations take place.
- Reporting Module – Responsible for generating HTML reports (with graphs, screenshots, and accessibility violation details) and terminal reports. This is also linked to the custom styling logic (impactStyling) that visually differentiates violation levels.
- Voice Feedback Module – Provides audible accessibility alerts and summaries levels (suite, test, violation type and DOM element) in the Cypress Log and on the webpage.
- Cypress Tests & Configuration – Contains sample test files under the “cypress” directory with example usage of the “cy.checkAccessibility()” command and a configuration setup (cypress.config.js, cypress.env.json).
- Core Source Files – Found in the “src” folder, which include various accessibility command and logging utilities (i.e., accessibility-commands.js, accessibility-report.js, etc.) that help drive the plugin functionality.

##### Out the Interactions
- From the Cypress Runner, show how the Cypress configuration file (cypress.config.js) registers the plugin’s accessibility tasks and imports the core source modules.
- How test files (in the cypress/e2e/ directory) call the custom “cy.checkAccessibility()” command.
- Reporting pathway, branching off from the analysis step to generate:
– HTML Reports (in the accessibility reports folder, configurable via cypress.config.js)
– Terminal Logs (with detailed summaries and severity highlights)
- Voice feature as a parallel module activated when the Cypress runner is in interactive mode and when the “enableAccessibilityVoice” environment variable is true.
- Integration with image assets (screenshots) related to accessibility violations, with the “images” folder supplying resources for diagrammatic representation of severity levels (red, orange, yellow, blue).

##### Architectural Patterns & Design Principles
- Modular Design: Different components (analysis engine, reporting, voice feedback) are encapsulated in their own source files.
- Plugin Pattern: The solution extends Cypress functionality via custom commands and tasks that integrate seamlessly with the existing testing framework.
- Configurability: The plugin makes heavy use of configuration parameters (both in code and through environment variables) to modify behavior as needed.
- Separation of Concerns: The file structure divides concern areas (source code versus tests, GitHub workflows for CI/CD, report generation logic, etc.).

##### Specify Relevant Technologies & Libraries
- Cypress (for end-to-end test execution)
- axe-core® and cypress-axe (for performing and configuring the accessibility tests)
- Node.js (for plugin execution and integration with Cypress)
- GitHub Actions (.github/workflows/main.yml for CI/CD automation)
- Reporting Technologies (HTML/CSS for report generation and layout)
- Optional Voice APIs (for the voice feedback module)

- Each Component should have a clear label (e.g., “Cypress Runner”, “Accessibility Analysis Engine”, “Reporting Module”, “Voice Feedback Module”).
– From the Cypress Runner to the custom command layer.
– From the command layer to the analysis engine.
– From the analysis engine to both report generators and the voice feedback module.
– Backwards flow if necessary to show how detailed logs are returned to the runner.
- Use annotations or side notes to indicate key configuration options such as “includedImpacts”, “onlyWarnImpacts”, and paths to reports.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level Components
    CR("Cypress Runner"):::runner

    subgraph "Cypress Tests & Configuration"
        ATS("Accessibility Tests Sample"):::testConfig
        CENV("cypress.env.json"):::config
    end

    subgraph "Cypress Integration Layer"
        CConfig("cypress.config.js"):::config
        E2E("cypress/support/e2e.js"):::support
        Commands("cypress/support/commands.js"):::support
    end

    subgraph "Accessibility Analysis Engine"
        AA("src/accessibility-commands.js"):::analysis
    end

    subgraph "Reporting Module"
        AR("src/accessibility-report.js"):::report
        IMG("images"):::reportAssets
    end

    subgraph "Voice Feedback Module"
        VF("src/accessibility-voice.js"):::voice
    end

    subgraph "Core Source Files"
        AL("src/accessibility-log.js"):::core
        AT("src/accessibility-tasks.js"):::core
        IDX("src/index.js"):::core
        IDT("src/index.d.ts"):::core
    end

    %% Connections
    CR -->|"initializes"| CConfig
    CENV -->|"setsEnv"| CConfig
    ATS -->|"invokesCommand"| Commands

    CConfig -->|"registersTasks"| AA
    E2E -->|"loadsCommands"| AA
    Commands -->|"definesCommands"| AA

    AA -->|"generatesReport"| AR
    AA -->|"triggersVoiceAlerts"| VF
    AR -->|"logsReport"| CR

    %% Utilization of Core Utilities (dashed lines)
    AA -.->|"utilizes"| AL
    AR -.->|"utilizes"| AT
    AR -.->|"utilizes"| IDX
    AR -.->|"utilizes"| IDT

    %% Click Events
    click CConfig "https://github.com/sclavijosuero/wick-a11y/blob/main/cypress.config.js"
    click E2E "https://github.com/sclavijosuero/wick-a11y/blob/main/cypress/support/e2e.js"
    click Commands "https://github.com/sclavijosuero/wick-a11y/blob/main/cypress/support/commands.js"
    click AA "https://github.com/sclavijosuero/wick-a11y/blob/main/src/accessibility-commands.js"
    click AR "https://github.com/sclavijosuero/wick-a11y/blob/main/src/accessibility-report.js"
    click IMG "https://github.com/sclavijosuero/wick-a11y/tree/main/images"
    click VF "https://github.com/sclavijosuero/wick-a11y/blob/main/src/accessibility-voice.js"
    click ATS "https://github.com/sclavijosuero/wick-a11y/blob/main/cypress/e2e/accessibility-tests-samples.js"
    click CENV "https://github.com/sclavijosuero/wick-a11y/blob/main/cypress.env.json"
    click AL "https://github.com/sclavijosuero/wick-a11y/blob/main/src/accessibility-log.js"
    click AT "https://github.com/sclavijosuero/wick-a11y/blob/main/src/accessibility-tasks.js"
    click IDX "https://github.com/sclavijosuero/wick-a11y/blob/main/src/index.js"
    click IDT "https://github.com/sclavijosuero/wick-a11y/blob/main/src/index.d.ts"

    %% Styles
    classDef runner fill:#f9f,stroke:#333,stroke-width:2px;
    classDef testConfig fill:#C6E5FF,stroke:#333,stroke-width:1px;
    classDef config fill:#E5F9C6,stroke:#333,stroke-width:1px;
    classDef support fill:#C6F9E5,stroke:#333,stroke-width:1px;
    classDef analysis fill:#F9E5C6,stroke:#333,stroke-width:1px;
    classDef report fill:#E5C6F9,stroke:#333,stroke-width:1px;
    classDef reportAssets fill:#C6E5FF,stroke:#333,stroke-width:1px;
    classDef voice fill:#F9C6E5,stroke:#333,stroke-width:1px;
    classDef core fill:#E6E6E6,stroke:#333,stroke-dasharray: 5 5,stroke-width:1px;
```
