Developer's Guide — Accellens AI Accessibility Compliance Platform

Version: 1.0 (MVP → v1) Update Date: November 23, 2025 MVP Status: Stage 1 completed, core components implemented, transitioning to Stage 2 Developer: Tridention

Goal: to provide developers with a single reference for architecture, codebase, standards, building, and deployment of Accellens — a platform for AI-driven web and mobile accessibility audits, user scenario modeling, and automated remediation.

1. System Overview

The platform provides:

Web Audit: headless scanning (Playwright) with axe-core, Lighthouse, and vision/AI analysis of DOM/ARIA/contrast.
Mobile Audit: analysis of Android/iOS builds via Appium/XCUITest/Espresso with accessibility API access.
Assistive Technology Emulation: text and audio scenarios for NVDA/JAWS/VoiceOver/TalkBack, and keyboard navigation.
AI Interpretation: prioritization, explanations, Accessibility Accuracy Score (AAS), and technical problem descriptions with code fix examples.
Integrations: CI/CD (GitHub/GitLab/Jenkins), IDE plugins, Jira/Slack, and reports (PDF/SARIF/JSON).

Environment Links: Swagger /api/docs (JSON /api/docs/json, YAML /api/docs/yaml), GraphQL Playground /graphql, Storybook /storybook.

2. Platform Architecture

Detailed architecture is described in ../architecture/architecture.md.

3. Repository and Structure

The project is organized as an Nx-based monorepo.

Nx provides a unified workflow, build caching, and orchestration.
Shared packages (libs/) are published as local dependencies (TS + Python stubs).
Terraform/Helm structures are split by environment (dev/qa/staging/prod).
Nx enforces modular boundaries: npm run validate:nx-tags is automatically executed before lint, verifying that each project is tagged with type:* and scope:*.
The API Gateway stores organizations in an in-memory repository (organization.repository.ts) with a default demo entry — suitable for local UI work before connecting a real database.

3.1 Project Structure

⚠️ Important: When changing the project structure (adding/removing directories, files, modules), you must update this section so it corresponds to the actual repository structure. For more details, see agent-instructions.md.

The project is organized as an Nx-based monorepo:

accellens/
├─ apps/                          # Applications and services
│  ├─ gateway/                    # Node.js API Gateway (Fastify)
│  │  ├─ src/
│  │  │  ├─ config/               # Configuration (environment)
│  │  │  ├─ modules/               # REST/GraphQL modules (projects, scans, findings, organizations, etc.)
│  │  │  │  ├─ ai/                 # AI routes (explain, impact, effort, fix)
│  │  │  │  │  └─ ai.routes.ts     # AI endpoints registration
│  │  │  │  ├─ scans/              # Scan management routes
│  │  │  │  │  ├─ scans.routes.ts  # Main scan routes (create, list, get)
│  │  │  │  │  ├─ scan-findings-loader.ts  # Findings loading utilities
│  │  │  │  │  ├─ scan-summary.ts  # Summary extraction utilities
│  │  │  │  │  ├─ scan-validation.ts  # Request validation utilities
│  │  │  │  │  └─ scan-converter.ts  # Data conversion utilities
│  │  │  ├─ guards/               # Auth guards, rate limiting
│  │  │  ├─ filters/              # Exception filters
│  │  │  ├─ middleware/           # Middleware (audit-log, organization-isolation)
│  │  │  ├─ plugins/              # Fastify plugins (Swagger)
│  │  │  ├─ services/             # Business logic services (audit-log, event-bus, SSO, etc.)
│  │  │  ├─ types/                # TypeScript type definitions
│  │  │  ├─ utils/                 # Utility functions (validation, rate-limiting, etc.)
│  │  │  ├─ main.ts               # Entry point
│  │  │  └─ server.ts             # Server setup
│  │  ├─ Dockerfile               # Dockerfile for gateway
│  │  ├─ package.json
│  │  └─ tsconfig.json
│  ├─ services/                   # Python microservices
│  │  ├─ audit/                   # Audit Engine (FastAPI + Celery)
│  │  │  ├─ src/
│  │  │  │  ├─ main.py            # Entry point for audit service
│  │  │  │  ├─ audit_engine.py    # Main Audit Engine service
│  │  │  │  ├─ parsers/            # Artifact parsers
│  │  │  │  │  ├─ axe_parser.py   # Axe-core results parser
│  │  │  │  │  ├─ dom_parser.py   # DOM snapshot parser
│  │  │  │  │  ├─ lighthouse_parser.py  # Lighthouse results parser
│  │  │  │  │  └─ tree_parser.py  # Accessibility tree parser
│  │  │  │  └─ services/          # Audit services
│  │  │  │     ├─ aas_calculator.py  # AAS score calculator
│  │  │  │     ├─ context_extractor.py  # Context extraction for findings
│  │  │  │     ├─ metrics.py          # Audit metrics
│  │  │  │     ├─ rule_cache.py       # Rule caching
│  │  │  │     ├─ rule_engine.py      # Rule engine for compliance checks
│  │  │  │     ├─ rule_fetcher.py     # Rule fetching from sources
│  │  │  │     ├─ rule_importer.py    # Rule importer from axe-core
│  │  │  │     ├─ rule_updater.py     # Rule updater service
│  │  │  │     └─ storage.py          # Storage service for artifacts
│  │  ├─ simulation/              # Screen Reader Announcement Analyzer
│  │  │  ├─ src/
│  │  │  │  ├─ main.py            # Entry point for announcement analyzer service
│  │  │  │  ├─ simulation_engine.py  # Main Announcement Analyzer service (legacy name)
│  │  │  │  ├─ atree_normalizer.py   # Unified ATree normalizer
│  │  │  │  ├─ mappers/            # Assistive technology mappers (for specificity analysis)
│  │  │  │  │  ├─ base.py          # ATMapper base class
│  │  │  │  │  ├─ nvda_mapper.py   # NVDA mapper
│  │  │  │  │  ├─ jaws_mapper.py   # JAWS mapper
│  │  │  │  │  ├─ voiceover_mapper.py  # VoiceOver mapper
│  │  │  │  │  ├─ talkback_mapper.py   # TalkBack mapper
│  │  │  │  │  └─ keyboard_mapper.py   # Keyboard navigation mapper
│  │  │  │  ├─ generators/        # Generators (legacy, used for demonstration)
│  │  │  │  │  ├─ audio_generator.py  # Audio generator for demonstration (TTS)
│  │  │  │  │  └─ text_generator.py   # Text generator (legacy, for demonstration)
│  │  │  │  ├─ providers/         # TTS providers (only for demonstration, not for analysis)
│  │  │  │  │  ├─ base.py         # TTSProvider interface
│  │  │  │  │  ├─ elevenlabs_provider.py  # ElevenLabs TTS provider
│  │  │  │  │  ├─ openai_provider.py      # OpenAI TTS provider
│  │  │  │  │  ├─ polly_provider.py       # AWS Polly TTS provider
│  │  │  │  │  └─ router.py        # TTS provider router
│  │  │  │  ├─ constants.py        # Simulation constants
│  │  │  │  └─ types.py            # Type definitions
│  │  ├─ ai/                      # AI Orchestration (LLM, Vision, Learning)
│  │  │  ├─ src/
│  │  │  │  ├─ main.py            # Entry point for AI service
│  │  │  │  ├─ api.py             # REST API endpoints for AI services
│  │  │  │  ├─ constants.py       # AI constants and configuration
│  │  │  │  ├─ dependencies.py    # FastAPI dependencies
│  │  │  │  ├─ langchain_router.py  # LangChain router for AI providers
│  │  │  │  ├─ metrics.py         # AI metrics and monitoring
│  │  │  │  ├─ otel_init.py       # OpenTelemetry initialization
│  │  │  │  ├─ prompt_loader.py   # YAML prompt template loader
│  │  │  │  ├─ rate_limiter.py    # AI rate limiting
│  │  │  │  ├─ router.py          # AIProviderRouter with fallback mechanism
│  │  │  │  ├─ safety.py          # Safety filters (PII, toxicity)
│  │  │  │  ├─ telemetry.py       # Telemetry and tracing
│  │  │  │  ├─ providers/         # AI providers (Strategy pattern)
│  │  │  │  │  ├─ base.py         # AIProvider interface
│  │  │  │  │  ├─ openai_provider.py      # OpenAI provider
│  │  │  │  │  ├─ anthropic_provider.py   # Anthropic provider
│  │  │  │  │  ├─ ollama_provider.py      # Ollama local provider
│  │  │  │  │  └─ __init__.py
│  │  │  │  ├─ services/          # AI services
│  │  │  │  │  ├─ base_service.py         # Base AI service class
│  │  │  │  │  ├─ explanation_service.py      # AI explanation generation
│  │  │  │  │  ├─ effort_estimation_service.py  # Fix effort assessment
│  │  │  │  │  ├─ fix_suggestions_service.py   # Fix suggestion generation
│  │  │  │  │  ├─ impacted_users_service.py     # Affected users analysis
│  │  │  │  │  └─ __init__.py
│  │  │  │  ├─ generators/        # Platform-specific fix suggestion generators
│  │  │  │  │  ├─ base.py          # BaseFixGenerator abstract class
│  │  │  │  │  ├─ html_aria.py     # HTML/ARIA fix generator
│  │  │  │  │  ├─ react.py         # React.js fix generator
│  │  │  │  │  ├─ react_native.py  # React Native fix generator
│  │  │  │  │  ├─ flutter.py       # Flutter fix generator
│  │  │  │  │  ├─ angular.py       # Angular fix generator
│  │  │  │  │  ├─ vue.py           # Vue.js fix generator
│  │  │  │  │  ├─ svelte.py        # Svelte fix generator
│  │  │  │  │  ├─ generic_framework.py  # Generic framework fallback
│  │  │  │  │  └─ __init__.py
│  │  │  │  └─ utils/             # AI utilities
│  │  │  │     ├─ imports.py      # Import helpers
│  │  │  │     └─ token_counter.py  # Token counting utilities
│  │  ├─ models/                  # SQLAlchemy models
│  │  │  ├─ base.py               # Base model class
│  │  │  ├─ aas_history.py       # AAS history model
│  │  │  ├─ audit_log.py         # Audit log model
│  │  │  ├─ compliance_rule.py   # Compliance rule model
│  │  │  ├─ finding.py            # Finding model
│  │  │  ├─ organization.py       # Organization model
│  │  │  ├─ project.py            # Project model
│  │  │  ├─ run.py                # Run model
│  │  │  └─ user.py               # User model
│  │  ├─ schemas/                 # Pydantic schemas
│  │  │  ├─ audit_log.py          # Audit log schemas
│  │  │  ├─ axe.py                # Axe results schemas
│  │  │  ├─ finding.py             # Finding schemas
│  │  │  ├─ organization.py       # Organization schemas
│  │  │  ├─ project.py            # Project schemas
│  │  │  ├─ run.py                # Run schemas
│  │  │  ├─ scan.py               # Scan schemas
│  │  │  └─ user.py                # User schemas
│  │  ├─ crud/                    # CRUD operations
│  │  │  ├─ base.py               # Base CRUD class
│  │  │  ├─ audit_log.py          # Audit log CRUD
│  │  │  ├─ finding.py            # Finding CRUD
│  │  │  ├─ organization.py       # Organization CRUD
│  │  │  ├─ project.py            # Project CRUD
│  │  │  ├─ run.py                # Run CRUD
│  │  │  └─ user.py               # User CRUD
│  │  ├─ routers/                 # FastAPI routers
│  │  │  ├─ audit_logs.py         # Audit logs router
│  │  │  ├─ project_settings.py   # Project settings router
│  │  │  └─ users.py              # Users router
│  │  ├─ services/                # Business logic services
│  │  │  ├─ cache.py              # Cache service (Redis)
│  │  │  ├─ encryption.py         # Encryption service
│  │  │  └─ storage.py            # Storage service (S3)
│  │  ├─ middleware/              # FastAPI middleware
│  │  │  └─ rate_limit.py         # Rate limiting middleware
│  │  ├─ migrations/              # Alembic migrations
│  │  │  ├─ env.py                # Migration environment
│  │  │  └─ versions/              # Migration versions
│  │  ├─ tests/                   # Tests
│  │  │  ├─ unit/                 # Unit tests
│  │  │  └─ integration/          # Integration tests
│  │  ├─ utils/                   # Utilities
│  │  │  └─ scan_params.py        # Scan parameters utilities
│  │  ├─ main.py                  # Main entry point for services
│  │  ├─ celery_app.py            # Celery application configuration
│  │  ├─ tasks/                   # Celery tasks package
│  │  ├─ common.py                # Common utilities
│  │  ├─ config.py                # Configuration settings
│  │  ├─ database.py              # Database connection
│  │  ├─ logger.py                # Logging configuration
│  │  ├─ alembic.ini              # Alembic configuration
│  │  ├─ pyproject.toml           # Python project configuration
│  │  └─ Dockerfile               # Dockerfile for services
│  ├─ scanner-web/                # Web scanner (Playwright + axe-core)
│  │  ├─ src/
│  │  │  ├─ auth/                 # Authentication handlers
│  │  │  │  ├─ auth-handler.ts    # Base auth handler
│  │  │  │  ├─ basic-auth-handler.ts    # Basic auth handler
│  │  │  │  ├─ form-auth-handler.ts     # Form auth handler
│  │  │  │  └─ header-auth-handler.ts   # Header auth handler
│  │  │  ├─ artifacts.ts          # Artifact path builders
│  │  │  ├─ auth.ts               # Authentication utilities
│  │  │  ├─ axe-core.ts           # Axe-core integration
│  │  │  ├─ axe-utils.ts          # Axe utilities
│  │  │  ├─ browser-comparison.ts # Multi-browser comparison
│  │  │  ├─ config.ts             # Scanner configuration
│  │  │  ├─ interactions.ts       # User interaction simulation
│  │  │  ├─ js-comparison.ts      # JavaScript comparison
│  │  │  ├─ lighthouse-audits.ts  # Lighthouse audit definitions
│  │  │  ├─ lighthouse.ts         # Lighthouse integration
│  │  │  ├─ main.ts               # Entry point
│  │  │  ├─ parameter-detection.ts  # Parameter detection utilities
│  │  │  ├─ partial-scan.ts       # Partial page scanning
│  │  │  ├─ scanner.ts            # Scanner implementation
│  │  │  ├─ scanner.spec.ts       # Scanner tests
│  │  │  ├─ storage.ts            # Storage service (S3)
│  │  │  ├─ types.ts              # Type definitions
│  │  │  └─ viewport.ts           # Viewport configuration
│  │  ├─ Dockerfile               # Dockerfile for scanner-web
│  │  ├─ package.json
│  │  ├─ README.md
│  │  └─ tsconfig.json
│  ├─ scanner-mobile/             # Mobile scanners (Appium/XCUITest/Espresso) [roadmap]
│  │  ├─ src/
│  │  │  ├─ android/              # Android scanner
│  │  │  ├─ ios/                   # iOS scanner
│  │  │  └─ main.ts
│  │  └─ Dockerfile
│  ├─ frontend/                   # Next.js 15 dashboard (React 19, TypeScript)
│  │  ├─ src/
│  │  │  ├─ app/                   # Next.js App Router
│  │  │  ├─ components/            # React components (Settings/RulesTable, Scans/FindingsBar)
│  │  │  ├─ lib/                   # Utilities, hooks, API factories
│  │  │  └─ styles/                # Global CSS (animations, variables)
│  │  └─ package.json
│  └─ cli/                        # Accellens CLI (Node.js)
│     ├─ src/
│     │  ├─ api/                  # API client
│     │  │  └─ client.ts
│     │  ├─ commands/             # CLI commands
│     │  │  ├─ login.ts           # Authentication commands
│     │  │  ├─ logout.ts
│     │  │  ├─ scan.ts            # Scan commands
│     │  │  ├─ scan/               # Scan subcommands
│     │  │  └─ report.ts           # Report commands
│     │  ├─ config/               # Configuration management
│     │  │  └─ config.ts
│     │  ├─ utils/                # Utilities
│     │  │  ├─ auth-validator.ts
│     │  │  └─ selector-validator.ts
│     │  └─ index.ts
│     ├─ package.json
│     ├─ README.md
│     └─ tsconfig.json
│
├─ libs/                          # Shared libraries
│  ├─ common/                     # Common models and DTOs
│  │  ├─ src/
│  │  │  ├─ models/                # TypeScript/Python models (Project, Run, Finding)
│  │  │  └─ dto/                   # Data Transfer Objects
│  │  ├─ ai/                         # AI providers, prompts, embeddings
│  │  ├─ src/
│  │  │  ├─ providers/             # LangChain router, provider abstractions
│  │  │  ├─ prompts/               # Prompt templates
│  │  │  └─ embeddings/            # SentenceTransformers, vector operations
│  │  ├─ sim/                        # Assistive simulation logic
│  │  ├─ src/
│  │  │  ├─ atree/                 # Unified ATree normalization
│  │  │  ├─ mappers/               # NVDA/JAWS/VoiceOver/TalkBack mappers
│  │  │  └─ generators/            # Text/audio/gesture generators
│  │  └─ utils/                      # Utilities (logging, telemetry, errors, config)
│  │     ├─ src/
│  │     │  ├─ config/                # Configuration utilities
│  │     │  │  └─ env.ts             # Environment variables parsing
│  │     │  ├─ logger/                # Structured logging
│  │     │  │  └─ index.ts           # Logger implementation
│  │     │  ├─ telemetry/             # OpenTelemetry SDK (placeholder)
│  │     │  └─ errors/                # Error handling
│  │     │     ├─ error-details-builder.ts  # Error details builder
│  │     │     ├─ error-helpers.ts          # Error helper functions
│  │     │     ├─ not-found-error.ts        # Not found error
│  │     │     ├─ standard-errors.ts        # Standard error classes
│  │     │     ├─ unauthorized-error.ts     # Unauthorized error
│  │     │     ├─ validation-error.ts       # Validation error
│  │     │     └─ index.ts                  # Error exports
│
├─ infra/                         # Infrastructure and deployment
│  ├─ k8s/                        # Kubernetes manifests and Helm charts
│  │  ├─ accellens/               # Helm chart for Accellens
│  │  │  ├─ Chart.yaml            # Chart metadata
│  │  │  ├─ values.yaml           # Default values
│  │  │  └─ templates/            # Kubernetes templates
│  │  │     ├─ gateway-deployment.yaml
│  │  │     ├─ services-deployment.yaml
│  │  │     ├─ celery-worker-deployment.yaml
│  │  │     ├─ scannerweb-deployment.yaml
│  │  │     └─ ingress.yaml
│  │  └─ environments/           # Environment-specific configurations
│  │     ├─ dev/                  # Development environment values
│  │     ├─ test/                 # Test environment values
│  │     ├─ pre-prod/             # Pre-production environment values
│  │     └─ prod/                 # Production environment values
│  ├─ terraform/                  # Terraform configurations for infrastructure
│  │  ├─ modules/                 # Reusable Terraform modules
│  │  │  ├─ rds/                  # RDS PostgreSQL module
│  │  │  ├─ elasticache/          # ElastiCache Redis module
│  │  │  ├─ s3/                   # S3 bucket module
│  │  │  └─ iam/                  # IAM roles and policies module
│  │  └─ environments/            # Configurations for each environment
│  │     ├─ test/                 # Test environment
│  │     ├─ pre-prod/             # Pre-production environment
│  │     └─ prod/                 # Production environment
│  └─ observability/              # Observability stack configurations
│     ├─ prometheus/              # Prometheus configuration
│     │  ├─ alerts/               # Alert rules
│     │  │  ├─ test-alerts.yaml
│     │  │  ├─ pre-prod-alerts.yaml
│     │  │  └─ prod-alerts.yaml
│     │  └─ prometheus.yml
│     ├─ grafana/                 # Grafana dashboards
│     │  └─ dashboards/
│     │     ├─ accellens-overview.json
│     │     ├─ ai-usage.json
│     │     ├─ scan-metrics.json
│     │     └─ queue-metrics.json
│     ├─ otel-collector-values.yaml  # OpenTelemetry Collector Helm values
│     └─ README.md
│
│  Note: Dockerfiles are located in the respective apps/ directories:
│  - apps/gateway/Dockerfile
│  - apps/services/Dockerfile
│  - apps/scanner-web/Dockerfile
│  - apps/frontend/Dockerfile
│
├─ ci-cd/                         # CI/CD integrations and templates
│  ├─ azure-pipelines/            # Azure DevOps integration
│  │  ├─ accellens-scan.yml
│  │  └─ azure-pipelines.example.yml
│  ├─ bamboo/                     # Bamboo integration
│  │  ├─ accellens-scan-script.sh
│  │  └─ README.md
│  ├─ bitbucket-pipelines/        # Bitbucket Pipelines integration
│  │  ├─ accellens-scan.yml
│  │  └─ bitbucket-pipelines.example.yml
│  ├─ jenkins/                    # Jenkins integration
│  │  ├─ accellens-pipeline.groovy
│  │  ├─ Jenkinsfile.example
│  │  └─ README.md
│  └─ teamcity/                   # TeamCity integration
│     ├─ accellens-scan-script.sh
│     └─ README.md
│
├─ docs/                          # Project documentation
│  ├─ INDEX.md                    # Documentation index
│  ├─ product/                    # Product Requirements
│  │  ├─ PRD.md                   # Product Requirements Document
│  │  └─ roadmap.md               # Roadmap
│  ├─ architecture/                # System architecture
│  │  ├─ architecture.md          # High-level architecture
│  │  ├─ data-model.md            # Data model
│  │  ├─ scan-api-extensibility.md  # Scan API extensibility
│  │  └─ guided-setup-ui.md       # Guided Setup UI architecture
│  ├─ api/                        # API documentation
│  │  ├─ api-reference.md         # REST and GraphQL API
│  │  ├─ cli-reference.md         # CLI reference
│  │  ├─ allure-format.md         # Allure JSON format
│  │  └─ error-handling.md        # API error handling
│  ├─ development/                # Developer guides
│  │  ├─ developer-guide.md       # Developer's Guide
│  │  ├─ coding-standards.md      # Coding standards
│  │  ├─ design-system.md         # Design System (UI/UX, components, styles)
│  │  ├─ ai-providers.md          # AI Providers Guide
│  │  ├─ agent-instructions.md    # Agent instructions
│  │  ├─ i18n-guide.md            # Internationalization guide
│  │  ├─ docs-smoke-tests.md      # Documentation smoke tests plan
│  │  ├─ sso-auto-login.md        # SSO auto-login
│  │  └─ viewport-testing-guide.md  # Viewport testing guide
│  ├─ testing/                    # Testing
│  │  ├─ testing.md               # Testing strategy
│  │  └─ test-plan.md             # Test plan
│  ├─ deployment/                 # Deployment and operations
│  │  ├─ deployment.md            # Deployment strategy
│  │  ├─ setup.md                 # Setup and installation
│  │  ├─ infrastructure.md        # Infrastructure deployment (Terraform)
│  │  ├─ observability.md         # Observability setup
│  │  ├─ security.md              # Security baseline
│  │  ├─ environment-variables.md # Environment variables
│  │  ├─ SSO-QUICKSTART.md        # SSO quickstart
│  │  ├─ sso-setup.md             # SSO setup documentation
│  │  └─ runbooks.md              # Runbooks and procedures
│  ├─ integrations/               # CI/CD integrations
│  │  ├─ github-actions.md
│  │  ├─ gitlab-ci.md
│  │  ├─ jenkins.md
│  │  ├─ bamboo.md
│  │  ├─ circleci.md
│  │  ├─ teamcity.md
│  │  ├─ azure-devops.md
│  │  └─ bitbucket-pipelines.md
│  ├─ contributing/               # Contributing
│  │  └─ contributing.md          # Contributing rules and RFC process
│  └─ analysis/                   # Analysis and reports
│     └─ compliance-report.md     # Compliance report
│
├─ tests/                         # Tests (unit, integration, e2e, smoke)
│  ├─ unit/                       # Unit tests
│  ├─ integration/                # Integration tests (docker-compose)
│  ├─ e2e/                        # End-to-end tests (Playwright, Appium)
│  ├─ smoke/                      # Smoke tests for deployment verification
│  │  └─ deployment-verification.test.ts
│  ├─ conftest.py                 # Pytest configuration
│  └─ setup.ts                    # Test setup utilities
│
├─ scripts/                       # Utilities and scripts
│  ├─ validate-env.py             # Environment variables validation
│  ├─ validate-sso-config.py      # SSO configuration validation
│  ├─ validate-nx-tags.ts        # Nx tags validation
│  ├─ update-github-about.py      # Update GitHub About section
│  ├─ check-github-settings.py    # Check GitHub settings
│  ├─ setup-github-repository.py  # Setup GitHub repository files
│  ├─ migrate.sh                  # DB migrations script
│  ├─ install-helm.sh             # Helm installation script
│  ├─ setup-keycloak-dev.sh       # Keycloak setup for dev
│  ├─ configure-keycloak-dev.sh   # Keycloak configuration
│  ├─ create-keycloak-test-user.sh  # Create Keycloak test user
│  ├─ create-test-user.py         # Create test user
│  ├─ check-setup.py              # Check environment setup
│  ├─ update-keycloak-redirect-uri.sh  # Update Keycloak redirect URI
│  ├─ update-keycloak-redirect-uri-cli.sh  # Update Keycloak CLI redirect URI
│  └─ update-sso-secret.sh        # Update SSO secret
│
├─ .github/                       # GitHub workflows and templates
│  ├─ workflows/                  # CI/CD workflows
│  │  ├─ build.yml                # Build workflow
│  │  ├─ ci-cd.yml                # CI/CD pipeline workflow
│  │  ├─ codeql.yml               # CodeQL security scanning
│  │  ├─ docker-build.yml        # Docker build workflow
│  │  ├─ e2e-tests.yml           # End-to-end tests
│  │  ├─ format-check.yml        # Format checking
│  │  ├─ integration-tests.yml   # Integration tests
│  │  ├─ lint.yml                # Linting workflow
│  │  ├─ nightly-builds.yml      # Nightly builds workflow
│  │  ├─ pr-auto-check.yml       # PR auto-check
│  │  ├─ security.yml            # Security scanning
│  │  ├─ test.yml                # Test workflow
│  │  ├─ type-check.yml          # Type checking
│  │  ├─ verify-hooks.yml        # Git hooks verification
│  │  └─ accellens-scan-example.yml  # Accellens scan example workflow
│  ├─ actions/                    # GitHub Actions
│  │  └─ accellens-scan/          # Accellens scan action
│  │     └─ action.yml
│  ├─ ISSUE_TEMPLATE/             # Issue templates
│  │  ├─ bug_report.md            # Bug report template
│  │  ├─ documentation.md         # Documentation issue template
│  │  ├─ feature_request.md       # Feature request template
│  │  ├─ performance.md           # Performance issue template
│  │  └─ question.md              # Question template
│  ├─ ABOUT.md                    # About section description
│  ├─ ABOUT_INSTRUCTIONS.md       # About section instructions
│  ├─ BRANCH_PROTECTION.md        # Branch protection settings
│  ├─ CODEOWNERS                  # Code owners configuration
│  ├─ COMMIT_MESSAGE.md           # Commit message guidelines
│  ├─ CONTRIBUTING.md             # Contributing guidelines
│  ├─ PULL_REQUEST_TEMPLATE.md    # Pull request template
│  ├─ REPOSITORY_SETTINGS.md      # Repository settings documentation
│  ├─ SECURITY.md                 # Security policy
│  └─ dependabot.yml              # Dependabot configuration
├─ .circleci/                      # CircleCI integration
│  ├─ accellens-scan.yml          # CircleCI template
│  └─ config.example.yml          # Example CircleCI config
├─ .gitlab-ci/                     # GitLab CI integration
│  ├─ accellens-scan.yml          # GitLab CI template
│  └─ example.gitlab-ci.yml        # Example GitLab CI config
├─ .nx/                           # Nx cache and configuration
├─ nx.json                         # Nx workspace configuration
├─ package.json                   # Root package.json (workspace)
├─ package-lock.json              # npm lock file
├─ pyproject.toml                 # Python workspace configuration
├─ uv.lock                        # Python lock file (uv)
├─ requirements.txt               # Legacy/Compatibility dependencies (auto-generated)
├─ docker-compose.yml             # Local development setup (Postgres, Redis, RabbitMQ)
├─ docker-compose.dev.yml         # Development docker-compose override
├─ docker-compose.test.yml        # Test docker-compose override
├─ .env.example                   # Environment variables example
├─ .gitignore                     # Git ignore rules
├─ .prettierrc                    # Prettier configuration
├─ eslint.config.mjs              # ESLint configuration
├─ tsconfig.json                  # TypeScript root configuration
├─ vitest.config.ts               # Vitest configuration
├─ playwright.config.ts           # Playwright configuration
├─ README.md                       # Root README
├─ CHANGELOG.md                   # Changelog
├─ CONTRIBUTING.md                # Contributing guidelines
├─ SECURITY.md                    # Security policy
├─ LICENSE                        # License file
└─ urls.txt                       # URLs for testing
└─ urls.txt                       # URLs for testing

4. Tech Stack

The tech stack is described in the root README.md.

5. Key Domain Modules

5.1 Web Analyzer

apps/scanner-web container (Playwright, axe-core, Lighthouse).
Collects DOM, accessibility tree, events, screenshots/video, perf metrics.
axe-core: primary source of WCAG rules — the library contains built-in WCAG 2.1/2.2 Level A and AA rules.
Artifacts are saved to s3://accellens-artifacts/projects/{project}/runs/{run}/..., ingest-trigger is published via RabbitMQ.

5.2 Mobile Analyzer

Appium 3 + XCUITest/Espresso, integration with BrowserStack/Saucelabs.
Android: AccessibilityNodeInfo, Accessibility Test Framework.
iOS: UIAccessibility, gesture snapshots.
Support for React Native/Flutter via bridge manifests and component profiles.

5.3 Screen Reader Announcement Analyzer

Unified ATree (web + mobile), rule mapper (NVDA/JAWS/VoiceOver/TalkBack).
AI-based announcement clarity analysis: Analyzes Accessibility Tree in conjunction with axe-core (rules), DOM snapshot (context), and AI to determine screen reader announcement clarity.
- Implementation: apps/services/audit/src/services/announcement_analyzer.py
- AI service: apps/services/ai/src/services/announcement_analyzer_service.py
- Prompt: libs/ai/src/prompts/announcement_analysis.yaml
- Evaluation criteria:
  - Sufficient information in the announcement (has_sufficient_info)
  - Not too verbose (is_too_verbose)
  - Logical sequence of announcements (is_logical)
  - Clarity of element purpose (purpose_clear)
Generates findings for unclear or problematic announcements.
- Rule ID: screen-reader-announcement-{screen_reader}-{role}
- Category: UNDERSTANDABLE
- Severity is determined by AI analysis
- suggested_fix stores: utterance, screen_reader, issues, recommendations, confidence
Integration: Automatically called in AuditEngine.analyze_run() after artifact processing.
Audio generator (TTS) — mp3/ogg: Used only for developer demonstration of what a screen reader user would hear. Not used for accessibility analysis.
Gesture/keyboard simulator reproduces navigation.
Cognitive load analyzer evaluates structure/readability.

5.4 AI Semantics & Learning Engine

Calculates Accessibility Accuracy Score (AAS), prioritizes findings (severity/impact/effort).
Generates explanations, technical problem descriptions with code fix examples (HTML/ARIA, RN/Flutter), evaluates confidence.
Learning Engine collects feedback, performs reinforcement learning, updates prompts/weights.

5.5 Experience Layer

Next.js dashboard: Runs, Findings, Audio/Video replay, AAS dashboards, Team collaboration.
Mobile companion (roadmap) for notifications and offline viewing.
CLI/SDK/IDE plugins provide developers with access to reports and technical problem descriptions with code fix examples.

6. Data Flow

Scan Trigger — API/CLI/CI calls Gateway (POST /projects/{id}/scans).
Capture — Scanners execute scenarios, upload artifacts to S3.
- axe-core: performs accessibility analysis and generates results with WCAG 2.1/2.2 rules.
- axe-core results contain rule IDs, standard references (standard_refs), violation descriptions.
Ingest — Audit Engine reads artifacts, applies rules, writes findings, AAS, embeddings.
- WCAG Rules Sources:
  - Primary: axe-core (Deque) — the library contains built-in WCAG 2.1/2.2 Level A and AA rules.
  - Storage: compliance_rules table in PostgreSQL (rule_id, standard, level, description, enabled, version).
  - Process: rules are imported from axe-core results, mapped to WCAG 2.2 criteria, saved in DB.
  - Update:
    - Automatic update on every scan via RuleUpdater.
    - Periodic check via Celery beat task check_rules_updates (configurable interval).
    - Rule hashing to detect changes.
    - Rules are automatically imported and versioned when the axe-core library is updated.
- AI Role: AI does not generate WCAG rules (they are fixed by the standard), but is used for:
  - Generating violation explanations (AI explanations).
  - Impacted users analysis.
  - Generating technical problem descriptions with code fix examples.
  - Calibrating AAS based on user feedback.
- More details: ../architecture/data-model.md
AI Processing — LLM services form explanations, effort estimations, and impacted users analysis.
- generate_ai_explanations Celery task automatically starts after Audit Engine analysis.
- ExplanationService: generates AI explanations for findings (saved in ai_explanation).
- EffortEstimationService: evaluates fix complexity (quick_fix/medium/complex, saved in suggested_fix.effort_estimation).
- ImpactedUsersService: analyzes affected user categories (blind, low_vision, motor, cognitive, deaf, saved in impacted_users).
- FixSuggestionsService: generates code fix suggestions using platform-specific generators.
  - Generators Architecture: Strategy pattern with platform-specific generators.
  - Platform Detection: automatic during scanning (from DOM) or manual via platform parameter in the request.
  - Supported Platforms: HTML/ARIA, React Native, Flutter, Angular, Vue.js, Svelte.
  - Platform Persistence: stored in Run.summary["platform"] and used for all findings from this run.
- AIProviderRouter: manages providers (OpenAI → Anthropic → Ollama fallback) with Redis caching.
- More details: ai-providers.md
Persistence — PostgreSQL, Vector DB, S3, Redis.
Delivery — GraphQL/REST, SSE/WebSockets, webhooks, CLI/SDK, reports (PDF/JSON/SARIF).

7. API and SDK

REST /api/v1/... (Fastify routes): projects, scans, findings, reports, integrations.
GraphQL /graphql: typed schema, dataloaders, persisted queries, subscriptions (scanProgress, aasUpdates).
WebSockets/SSE: scan status, new findings notifications, AAS feed.
SDK: JS/TS (libs/sdk-ts), Python (libs/sdk-python), Java (roadmap).
CLI: apps/cli (see ../api/cli-reference.md).

7.0 API Structure and Data Organization

Important: All API endpoints working with organization data (projects, runs, scans, findings, AI endpoints) require passing organization_id in the URI path, not in the request body. This ensures:

Security: Explicit data isolation by organizations at the URI level.
Consistency: Unified approach to API endpoints organization.
Transparency: Easy to understand which organization the data belongs to.

Endpoints Format:

POST /api/v1/organizations/{organization_id}/projects - create project
GET /api/v1/organizations/{organization_id}/projects - list projects
POST /api/v1/organizations/{organization_id}/projects/{project_id}/scans - start scanning
POST /api/v1/organizations/{organization_id}/runs - create run
POST /api/v1/organizations/{organization_id}/ai/explain - AI finding explanation
POST /api/v1/organizations/{organization_id}/ai/impact - AI impacted users analysis
POST /api/v1/organizations/{organization_id}/ai/effort - AI effort estimation
POST /api/v1/organizations/{organization_id}/ai/fix - AI fix suggestions

Examples:

# Create project
curl -X POST "https://api.accellens.dev/api/v1/organizations/{organization_id}/projects" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "slug": "my-project"}'

# Start scan
curl -X POST "https://api.accellens.dev/api/v1/organizations/{organization_id}/projects/{project_id}/scans" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"type": "web", "triggerSource": "api", "targetUrl": "https://example.com"}'

More details see ../api/api-reference.md.

7.1 Reports API

The platform supports report generation in three formats:

JSON Report (GET /api/v1/reports/{run_id}/json):

Full structured report with all metadata, statistics, and findings.
Convenient for programmatic processing and integration with other tools.
Implementation: apps/services/routers/reports.py::get_json_report

Report Archive:

Data model: apps/services/models/report_archive.py::ReportArchive
CRUD operations: apps/services/crud/report_archive.py::ReportArchiveCRUD
Service: apps/services/services/report_archive.py::ReportArchiveService
API endpoints: apps/services/routers/report_archive.py
Automatic cleanup: apps/services/tasks/maintenance_tasks.py::cleanup_report_archives (Celery task)

ReportArchive Data Model:

id (UUID) — unique identifier of the archived report
organization_id (UUID, FK) — owner organization (for data isolation)
project_id (UUID, FK) — project
run_id (UUID, FK) — scan
report_type (enum: pdf, sarif, json) — report type
storage_key (string, unique) — S3 path (e.g., organizations/{org_id}/projects/{project_id}/runs/{run_id}/reports/{report_id}.{ext})
file_size (integer) — file size in bytes
content_type (string) — MIME type (application/pdf, application/json, application/sarif+json)
expires_at (timestamp) — storage expiration date (calculated: created_at + retention_days)
meta_data (JSONB) — additional metadata (custom_sections for PDF, format version, etc.)
created_at, updated_at (timestamps) — standard time stamps

Archiving Logic:

When generating a report (JSON, SARIF, PDF) via corresponding endpoints:
- The report is saved to S3 via StorageService.
- Metadata is recorded in the report_archives table via ReportArchiveService.save_report_to_archive().
- Report existence is checked by storage_key to prevent duplicates.
- Archiving errors do not block report generation (non-blocking).
Archive settings are stored in Organization.settings (JSONB):
- report_archive_max_count (default: 100) — maximum number of reports.
- report_archive_retention_days (default: 90) — retention period in days.
Automatic cleanup (Celery task cleanup_report_archives, runs daily at 02:00 UTC):
- Lifecycle policy: deletes reports with expires_at < current_timestamp.
  - Checks file existence in S3 (S3 lifecycle might have already deleted it).
  - If file exists — deletes from S3, then from DB.
  - If file doesn't exist — only deletes from DB.
- FIFO policy: checks current_count > max_count for each organization.
  - If exceeded — deletes oldest reports (by created_at) until limit is reached.
- Prometheus metrics: report_archive_cleanup_total, report_archive_cleanup_size_bytes.
- Audit log: entry on mass cleanup (> 100 files).
S3 Lifecycle Policies (optional, backup mechanism):
- Automatically configured upon changing report_archive_retention_days.
- Prefix: organizations/{org_id}/projects/ (broad policy, less precise).
- Primary cleanup method — Celery task (more precise, based on expires_at from DB).
- MinIO: lifecycle policies might not be supported via boto3 (manual configuration required).

PDF Report (GET /api/v1/reports/{run_id}/pdf, POST /api/v1/reports/{run_id}/pdf):

Professionally designed PDF report for stakeholder presentation.
Includes Executive Summary, detailed findings with color-coded severity.
Supports custom sections via POST endpoint.
Generation: apps/services/services/report_pdf.py::PDFReportService
Storage: S3 with pre-signed URLs (24-hour TTL).
Caching: Redis (24-hour TTL).

SARIF Report (GET /api/v1/reports/{run_id}/sarif):

SARIF 2.1.0 format for integration with CI/CD platforms (GitHub Security, Azure DevOps).
Implementation: apps/services/routers/reports.py::get_sarif_report

Detailed API documentation: ../api/api-reference.md

7.2 Caching Patterns

Accellens uses multi-level caching for performance optimization:

In-Memory TTL Cache (Application Level)

Uses cachetools.TTLCache for frequently accessed, relatively static data:

Cache	Location	TTL	Purpose
Rule Cache	`audit/src/services/rule_cache.py`	1 hour	Compliance rules
Permission Cache	`services/permission_cache.py`	5 min	User permissions

Usage:

from services.permission_cache import permission_cache

# Get cached permissions
perms = permission_cache.get(user_id, organization_id)
if perms is None:
    perms = await load_permissions_from_db(user_id, organization_id)
    permission_cache.set(user_id, organization_id, perms)

# Invalidation on permission change
permission_cache.invalidate_user(user_id)
permission_cache.invalidate_organization(organization_id)

Cache Invalidation Strategy

TTL-based: Automatic expiration prevents stale data.
Event-based: Explicit invalidation on data changes.
Scoped: Invalidate by user, organization, or specific key.

7.3 Rate Limiting Strategy

Accellens implements distributed rate limiting via Redis (SlowAPI):

Rate Limit Keys

Key Pattern	Description
`gateway-internal`	Gateway requests (unlimited)
`org:{org_id}`	Organization-scoped limits
IP address	External request fallback

Tier-Based Limits

Tier	Requests/Hour	Requests/Minute
Free	1,000	20
Starter	5,000	100
Pro	25,000	500
Enterprise	100,000	2,000

Response Headers

All responses include rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Policy: 10000;w=3600
X-RateLimit-Scope: organization

Decorating Endpoints

from middleware.rate_limit import limiter

@router.get("/resource")
@limiter.limit("100/minute")
async def get_resource(request: Request):
    ...

8. Standards and Quality

Detailed coding standards are described in coding-standards.md.

Design System: UI/UX components, styles, and visual standards are described in design-system.md. It is critically important for frontend developers to follow the design system when creating components.

Responsive Design: Frontend must be responsive with a desktop-first approach — the interface is designed for desktop (≥1024px) first, then adapted for tablets and mobile devices while maintaining full functionality. All features must be available on all devices. Detailed requirements for breakpoints, touch targets, responsive components, and testing are described in design-system.md.

Main requirements:

Node.js gateway: ESLint (typescript-eslint), Prettier, Jest/Supertest.
Python services: Ruff (linting & formatting), mypy strict, pytest/pytest-asyncio.
Frontend: ESLint strict, Prettier, tsconfig strict, Playwright component tests (desktop + mobile viewport), Design System compliance, desktop-first responsive design.
ESLint plugins for code quality:
- eslint-plugin-unused-imports: automatically detects unused imports.
- eslint-plugin-sonarjs: detects string duplication (sonarjs/no-duplicate-string) and high cognitive complexity (sonarjs/cognitive-complexity).
- These plugins help prevent code duplication and maintain codebase cleanliness.
SonarQube/SonarCloud: centralized code quality analysis with quality gates, metrics, and change history. Analysis runs automatically on every PR and push to main/develop. More details: sonarqube-setup.md, sonarqube-quality-gates.md, sonarqube-metrics-dashboards.md.
Conventional Commits; PR template requires tests, changelog, docs.
Documentation is updated in the same PR, including smoke configs (docs-smoke-tests.md).

Git Hooks Enforcement

Git Hooks Enforcement is STRICTLY REQUIRED

NEVER use --no-verify flag when committing or pushing.
NEVER skip git hooks - all checks MUST pass before committing.
If checks fail, fix the issues instead of skipping validation.
CI/CD will automatically detect and block PRs with hook skip attempts.
See Git Hooks Protection for details.

9. Testing

Unit: pytest (backend/AI), vitest/jest (gateway/frontend), prompt snapshot tests.
Integration: docker-compose (Postgres, Redis, RabbitMQ, scanners), gateway↔services contract tests.
E2E Web: Playwright (desktop/mobile viewport), accessibility regression.
E2E Mobile: Appium (BrowserStack), nightly smoke.
Accessibility regression: accessibility tree comparison, audio, AAS.
Performance/Load: k6 (parallel scans), device farm load.
Security: trivy, bandit, npm audit, snyk (roadmap).
Smoke tests: API JSON schema validation against domain models from @accellens/common (see tests/smoke/api-schema-validation.test.ts). Run: npm run test:smoke.
More details: ../testing/testing.md, ../testing/test-plan.md.

10. CI/CD Pipeline

Lint → Type check → Unit tests (Node/Python/TS).
Container Build → security scan (Trivy/Snyk).
Integration tests (docker-compose, device farm smoke).
Documentation smoke tests (API/CLI examples).
SonarQube analysis → quality gates check (coverage, code smells, bugs, security vulnerabilities).
Publish images (GHCR/ECR) + Terraform plan (optional gate).
Deploy via Helm/ArgoCD: dev → qa → staging (auto), prod (manual approval, canary roadmap).
SemVer tagging, release notes, Statuspage updates.

Workflows: ../integrations/github-actions.md, ../deployment/deployment.md.

SonarQube: Code quality analysis is performed automatically in the sonarqube.yml workflow and integrated into quality-gates.yml. Analysis results are available in the SonarCloud dashboard and automatically commented on PRs. More details: sonarqube-setup.md.

11. Local Development

git clone.
Create .env from root template: cp .env.example .env and fill in required variables.
docker compose up — Postgres, Redis, RabbitMQ, MinIO, gateway, services, frontend.
Gateway: pnpm nx serve gateway (dev server on port 3000).
- To run test server on port 3002: cd apps/gateway && npm run dev:test
- Test server is only needed when real environment isolation is required.
Python services: make services-dev or uvicorn apps.services.audit.main:app --reload.
Frontend: pnpm nx serve frontend; CLI: pnpm nx run cli:dev.
Scanners: pnpm nx run scanner-web:dev, pnpm nx run scanner-mobile:dev (requires browsers/emulators).
Storybook: pnpm nx storybook frontend.
Docs smoke: pnpm nx run docs:smoke --dry-run.

11.0 Frontend (Next.js + Tailwind v4) — mandatory dependencies

Tailwind v4 and Next 16 require native bindings lightningcss and @tailwindcss/oxide. These packages are published as optional dependencies, so npm on Linux/macOS might skip them.
After any npm install you must run:
```
npm install --workspace apps/frontend --include=optional
npm run --workspace @accellens/frontend ensure:lightningcss
```
The first step forces npm to download platform packages (lightningcss-*-musl/gnu, @tailwindcss/oxide-*). The second step (scripts/ensure-lightningcss.js) checks that the binary appeared in node_modules and downloads the correct variant if necessary.
In Docker dev environment, the frontend command in docker-compose.dev.yml already performs npm install --include=optional on every container start. If the container is recreated, no additional actions are required.
If you receive errors like Cannot find module 'critters' or Cannot find native binding ... tailwindcss-oxide.linux-arm64-musl.node, repeat the commands above and restart the frontend: docker compose -f docker-compose.yml -f docker-compose.dev.yml restart frontend.

Python services — security baseline dev/test setup

Requirements: Python ≥ 3.13, uv, installed Docker (for Postgres/Redis/RabbitMQ).

Initialize environment with uv:

cd apps/services
# Create virtual environment and install dependencies (including dev)
uv sync --all-extras
# Activate virtual environment
source .venv/bin/activate

To add a dependency: uv add <package> To run a command: uv run <command>

Spin up infrastructure for tests (Postgres/Redis/RabbitMQ/MinIO):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d postgres redis rabbitmq minio

Export required environment variables before running security/observability tests:

export DATABASE_URL="postgresql+asyncpg://<DB_USER>:<DB_PASSWORD>@localhost:5432/accellens"
export OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_SERVICE_NAME="accellens-services"
export PROMETHEUS_MULTIPROC_DIR="/tmp/prometheus"

All variables are listed in apps/services/config.py and docs/deployment/environment-variables.md. At a minimum, DATABASE_URL, OTEL_*, and PROMETHEUS_* must be declared to enable metrics and tracing export.

Security baseline dependencies are already fixed in apps/services/pyproject.toml:
- runtime: prometheus-client, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-grpc, opentelemetry-instrumentation-fastapi, opentelemetry-instrumentation-celery.
- dev/test: pytest, pytest-asyncio, pytest-cov, httpx.
Before pushing, run:
```
source .venv/bin/activate   # or poetry shell
./scripts/run-security-tests.sh
python -m pytest -m security
```
The script runs Bandit + pytest (marker security), while a separate pytest call is useful for local debugging.

11.1 Utilities and Scripts

Utilities and scripts are available in the project to automate development and deployment tasks.

⚠️ Important: Whenever possible, all interaction with GitHub should be performed via API or GitHub CLI (gh), rather than the web interface. This ensures automation, reproducibility, and versioning of operations.

Scripts in `scripts/`

`validate-env.py` — Environment Variable Validation

Validates environment configuration files for different environments (dev, test, pre-prod, prod).

Usage:

# Check dev environment
python scripts/validate-env.py --env dev --file .env.dev

# Check prod environment
python scripts/validate-env.py --env prod --file .env.prod

Features:

Checks for required variables for each environment.
Validates formats for URL, numeric values, JSON.
Checks if variable values match expected ones (LOG_LEVEL, APP_ENV, AI providers).
Warns about hardcoded secrets in non-dev environments.

Supported Environments:

dev — local development (Docker Compose)
test — test environment (QA)
pre-prod — pre-production environment (staging)
prod — production environment

`update-github-about.py` — Update GitHub About Section

Updates repository description, website, and topics via GitHub API.

Usage:

# Using environment variable
export GITHUB_TOKEN=your_token_here
python scripts/update-github-about.py

# Passing token as argument
python scripts/update-github-about.py YOUR_TOKEN [OWNER] [REPO]

Features:

Repository description update.
Website (homepage) update.
Topics update.

GitHub CLI Alternative:

# Update description and website
gh api repos/tridention/Accessibility-Intelligence-Platform -X PATCH \
  -f description="..." \
  -f homepage="https://tridention.com"

# Update topics
gh api repos/tridention/Accessibility-Intelligence-Platform/topics -X PUT \
  -H "Accept: application/vnd.github.mercy-preview+json" \
  --input - << 'EOF'
{
  "names": ["accessibility", "wcag", ...]
}
EOF

`check-github-settings.py` — Check GitHub Repository Settings

Checks current repository settings and provides improvement recommendations.

Usage:

# Using environment variable
export GITHUB_TOKEN=your_token_here
python scripts/check-github-settings.py

# Passing token as argument
python scripts/check-github-settings.py YOUR_TOKEN [OWNER] [REPO]

Features:

Checks current repository settings.
Checks merge settings (auto-merge, squash, rebase).
Checks branch protection.
Checks labels, webhooks, deploy keys.
Recommendations for settings improvement.

`migrate.sh` — DB Migration Script

Simplifies running Alembic commands for PostgreSQL database migrations in a Docker container.

Usage:

# Show current migration version
./scripts/migrate.sh current

# Show migration history
./scripts/migrate.sh history

# Apply all migrations
./scripts/migrate.sh upgrade head

# Roll back one migration
./scripts/migrate.sh downgrade -1

# Create new migration (autogenerate)
./scripts/migrate.sh revision "Add new table" --autogenerate

# Show help
./scripts/migrate.sh help

Features:

Automatic environment setup (PYTHONPATH, DATABASE_URL).
Checks and automatically starts the Docker container if it's not running.
Runs Alembic commands in the services container.
Colored output for convenience.
Supports all main Alembic commands (upgrade, downgrade, current, history, revision, merge, show, stamp).

When to use:

On first application start (table creation).
After changes to SQLAlchemy models (new fields/tables).
When updating code from the repository (new migrations).
To roll back migrations in case of problems.

More details see Using the migration script in the deployment documentation.

`setup-github-repository.py` — Setup Repository Files via API

Creates all necessary repository files via GitHub API:

CODEOWNERS
SECURITY.md
CONTRIBUTING.md
Issue templates (question, documentation, performance)

Usage:

# Using environment variable
export GITHUB_TOKEN=your_token_here
python scripts/setup-github-repository.py

# Passing token as argument
python scripts/setup-github-repository.py YOUR_TOKEN [OWNER] [REPO]

Features:

File creation/update via GitHub Contents API.
Automatic detection of existing files (update instead of creation).
File creation in correct directories.
Support for all recommended repository files.

Note: All repository files can be created via GitHub API, which follows the "GitHub API First" principle (see docs/development/agent-instructions.md).

Additional Information

Detailed instructions on using scripts and setting up the GitHub repository see:

.github/ABOUT_INSTRUCTIONS.md — About section filling instructions.
.github/ABOUT.md — About section description.
.github/REPOSITORY_SETTINGS.md — Full list of repository settings and recommendations.

11.5 Fix Suggestions Engine Architecture

11.5.1 Overview

The Fix Suggestions Engine uses the Strategy pattern to generate code fixes for different platforms/frameworks. The platform is detected automatically during scanning or can be manually specified by the user.

11.5.2 Platform Detection

The platform is determined at the run level (one platform for all findings):

Manual Selection: The user can specify platform in ScanRequestDto when creating a scan.
Automatic Detection: If the platform is not specified or set to auto, it is automatically determined from the DOM snapshot during artifact analysis.
Persistence: The detected platform is saved in Run.summary["platform"] and used for all findings from that run.

11.5.3 Generators Architecture

Base Class: BaseFixGenerator (apps/services/ai/src/generators/base.py)

Abstract class with generate_fix() method.
Common functionality: loading YAML prompts, router interaction, generation parameters.

Generator Implementations:

HTMLARIAFixGenerator — HTML/ARIA (base, default).
ReactFixGenerator — React.js with semantic HTML and ARIA support.
ReactNativeFixGenerator — React Native with accessibility props support.
FlutterFixGenerator — Flutter with Semantics widget support.
AngularFixGenerator — Angular with CDK accessibility directives support.
VueFixGenerator — Vue.js with Vue accessibility best practices support.
SvelteFixGenerator — Svelte.
GenericFrameworkFixGenerator — Fallback for unknown platforms (uses HTMLARIAFixGenerator).

Service: FixSuggestionsService (apps/services/ai/src/services/fix_suggestions_service.py)

Uses the Strategy pattern to select a generator based on the platform.
Retrieves the platform from Run.summary["platform"] via finding.run_id.
Delegates generation to the selected generator.

11.5.4 Adding a New Platform

To add support for a new platform:

Create a new generator in apps/services/ai/src/generators/ (inherit from BaseFixGenerator).
Create a YAML prompt in libs/ai/src/prompts/fix_suggestions_<platform>.yaml.
Add support in PlatformDetector (apps/services/audit/src/services/platform_detector.py).
Add the generator to FixSuggestionsService._get_generator().
Update the Platform enum in apps/services/schemas/scan.py and libs/common/src/models/platform.ts.

11.5.5 Files

Generators: apps/services/ai/src/generators/
Prompts: libs/ai/src/prompts/fix_suggestions_*.yaml
Platform Detection: apps/services/audit/src/services/platform_detector.py
Utilities: apps/services/ai/src/utils/platform_utils.py

12. Security and Privacy

PII redaction on ingest and logging; configurable data residency.
Encryption at rest: PostgreSQL TDE, S3 SSE-KMS; secrets via Vault/KMS.
RBAC + SSO (OIDC/SAML), API scopes (scan:write, report:read, admin:manage).
GDPR/ISO27001: retention policies, DSAR workflow.
SOC2 readiness: access logging, DR runbooks, pen-test cadence.

12.1 Multitenancy & RBAC in Python Services

AccessContext: apps/services/security/context.py forms the context from X-Actor-Id, X-Organization-Id, X-Project-Id headers. Endpoint access is established via Depends(require_organization_access) / Depends(require_project_access) and automatically validates membership and roles.
Scoped CRUD: apps/services/crud/base.py provides OrganizationScopedCRUD and ProjectScopedCRUD, which add organization_id / project_id to every SQLAlchemy query. All CRUD operations working with tenant data must inherit from these classes.
Negative Tests: apps/services/tests/unit/test_reports_router.py and accompanying fixtures verify that another organization's data is inaccessible (HTTP 403). When adding a new router, create a similar test and pass organization_id/project_id in the request.
Documentation: any new endpoints must describe required headers and roles in Swagger/OpenAPI and corresponding developer-guide sections.
PII + Audit: PIIRedactionMiddleware and AuditLoggingMiddleware are included in apps/services/main.py. All write operations are logged after redaction; explicit logging of raw personal data inside routers is not allowed.

13. Observability

OpenTelemetry SDK for gateway, microservices, scanners; trace propagation via RabbitMQ.
Prometheus + Grafana: queue backlog, scan duration, AAS drift, LLM latency, cost.
Loki/ELK: structured JSON logs; Jaeger/Tempo for traces.
Alerts: backlog threshold, scan failure rate, SLA breach, AI drift, TTS errors, device farm outage.
FastAPI /metrics (Prometheus) + auto-collection via ServiceMonitor; smoke coverage by tests/unit/test_metrics_endpoint.py.

14. Roadmap

A detailed development plan is described in ../product/roadmap.md.

Key stages:

MVP (0–6 months) — Stage 1 completed (Nov 23, 2025): ✅ Web audit (WCAG 2.2 AA), ✅ text-only ASE, ✅ AI explanations + ✅ AAS v0, ✅ GitHub Action, ✅ basic dashboard, ✅ PDF/JSON/SARIF reports. ⬜ Increase test coverage (Stage 2: 2.8.10).
v1 (6–12 months): Mobile audit, TTS audio, vision/contrast analysis, cognitive load, Jira/Slack integrations, SARIF export, AAS v1.
v2 (12–18 months): Full VoiceOver/TalkBack simulation (gestures, live replay), rules marketplace, on-premise deployment (Helm charts, air-gapped mode, local AI models), continuous monitoring, anomaly detection, learning engine GA.

On-premise deployment (v2+): The platform supports installation on client servers for enterprise clients with security, compliance (GDPR, HIPAA, FedRAMP), or data residency requirements. More details: ../deployment/deployment.md.

15. Team and Interaction

Engineering Lead — architecture, gateway, CI/CD.
Python Lead — audit/AI services, Celery, data layer.
AI/ML Engineer — prompts, LLM orchestration, learning engine.
Frontend/Mobile Engineers — Next.js, React Native/Flutter, design system.
Automation Engineer — Playwright/Appium, device farm, CI smoke.
DevOps/SRE — infrastructure, observability, security, cost control.
Accessibility Specialist — WCAG/EN/ADA methodologies, simulation validation, AAS control.

Communication: two-week sprints (Scrum/Kanban), Slack/Teams, Jira/Linear, RFCs in docs/rfc/, changelog is mandatory.

16. Next Steps

Confirm MVP scope (../product/PRD.md) and requirements freeze.
Set up monorepo, service templates, and CI workflows.
Implement PoC Assistive Simulation Engine (text-only) and AAS v0 on representative pages.
Prepare beta-client list and public landing page.
Organize feedback loop: user rating collection, Learning Engine training.

FilesExpand file tree

developer-guide.md

Latest commit

History

developer-guide.md

File metadata and controls

Developer's Guide — Accellens AI Accessibility Compliance Platform

1. System Overview

2. Platform Architecture

3. Repository and Structure

3.1 Project Structure

4. Tech Stack

5. Key Domain Modules

5.1 Web Analyzer

5.2 Mobile Analyzer

5.3 Screen Reader Announcement Analyzer

5.4 AI Semantics & Learning Engine

5.5 Experience Layer

6. Data Flow

7. API and SDK

7.0 API Structure and Data Organization

7.1 Reports API

7.2 Caching Patterns

In-Memory TTL Cache (Application Level)

Cache Invalidation Strategy

7.3 Rate Limiting Strategy

Rate Limit Keys

Tier-Based Limits

Response Headers

Decorating Endpoints

8. Standards and Quality

Git Hooks Enforcement

9. Testing

10. CI/CD Pipeline

11. Local Development

11.0 Frontend (Next.js + Tailwind v4) — mandatory dependencies

Python services — security baseline dev/test setup

11.1 Utilities and Scripts

Scripts in scripts/

validate-env.py — Environment Variable Validation

update-github-about.py — Update GitHub About Section

check-github-settings.py — Check GitHub Repository Settings

migrate.sh — DB Migration Script

setup-github-repository.py — Setup Repository Files via API

Additional Information

11.5 Fix Suggestions Engine Architecture

11.5.1 Overview

11.5.2 Platform Detection

11.5.3 Generators Architecture

11.5.4 Adding a New Platform

11.5.5 Files

12. Security and Privacy

12.1 Multitenancy & RBAC in Python Services

13. Observability

14. Roadmap

15. Team and Interaction

16. Next Steps

Scripts in `scripts/`

`validate-env.py` — Environment Variable Validation

`update-github-about.py` — Update GitHub About Section

`check-github-settings.py` — Check GitHub Repository Settings

`migrate.sh` — DB Migration Script

`setup-github-repository.py` — Setup Repository Files via API