# Roadmap & Production Readiness

This document outlines the architectural roadmap, feature milestones, and production readiness checklist for the Aviary auditing engine.

# Known issues / fixes required

• CLI Testing: Integration tests time out even with 120s limit (fixed by replacing slow locator auto-waits with page.evaluate).

# Core features enhancement

# SEO checkers

• Structured Data Validation

  • JSON-LD schema detection and validation
  • Microdata detection
  • RDFa support — not implemented
  • Schema.org vocabulary validation — Organization, Person, Product, Article, BreadcrumbList, FAQPage, HowTo, Review, Event, LocalBusiness, WebPage, WebSite, ImageObject
  • Rich snippets preview — not implemented

• Content Analysis — partial

  • Keyword density analyzer — not implemented
  • Content readability score (Flesch-Kincaid)
  • Duplicate content detection — not implemented
  • Word count and content length analysis
  • Internal and external link analysis
  • Broken link detection — link structure is checked, but nothing crawls links to verify they resolve

• Technical SEO

  • Robots.txt validation
  • XML sitemap detection and validation
  • SSL/HTTPS verification
  • Mobile-friendliness test
  • Page speed insights integration
  • Core Web Vitals (LCP, CLS) — real values via web-vitals'/PerformanceObserver, injected before navigation; plus FCP and TTFB. INP itself isn't reported (it requires a real user interaction this unattended audit never performs) — Total Blocking Time (long-task entries) is the disclosed proxy instead, same as Lighthouse. See Accuracy limitations §3.4
  • Server response time check
  • Redirect chain detection
  • 404 error detection

• Heatmap & User Experience

  • Click heatmap generation — predictive, from static DOM position/element-type heuristics, not recorded user interactions
  • Scroll depth tracking
  • Mouse movement tracking — not implemented
  • Attention heatmap — static heuristic scoring (heading level, above-the-fold, element size), not time-based
  • Visual hierarchy analysis
  • Above-the-fold content detection

• Social Media Optimization

  • Twitter Card validation
  • Facebook Open Graph validation
  • LinkedIn meta tags — not implemented
  • Pinterest rich pins — not implemented
  • Social share preview generation — not implemented

• Accessibility (A11y) — partial

  • ARIA attributes validation
  • Color contrast checking — not implemented
  • Keyboard navigation testing (tab order, skip links)
  • Screen reader compatibility — not implemented
  • WCAG compliance levels — not implemented

• Internationalization

  • hreflang and language declaration validation
  • Character encoding / UTF-8 checks
  • RTL language support detection
  • Geo-targeting signals

• E-commerce

  • Product schema, pricing, and review markup validation
  • Checkout and shipping information checks

• Legal Compliance

  • Privacy policy, GDPR, and CCPA detection
  • Cookie consent, copyright, and disclaimer checks

# Architecture & code quality

• Testing

  • Unit tests for all checkers (Jest/Vitest)
  • Integration tests
  • E2E tests for the tool itself
  • Test coverage > 80%
  • Mock server setup for consistent testing
  • Performance benchmarks

• Configuration

  • Configuration file support (JSON, YAML)
  • Custom rule definitions
  • Rule severity levels (error, warning, info)
  • Rule enabling/disabling
  • Preset configurations (basic, advanced, strict)

• Error Handling

  • Comprehensive error handling
  • Retry mechanisms for network failures
  • Graceful degradation
  • Detailed error messages
  • Error logging and reporting

• Performance

  • Parallel checking for multiple URLs
  • Caching mechanisms
  • Resource pooling (browser instances)
  • Memory leak prevention
  • Optimization for large-scale scanning

# Reporting & output

• Report Formats

  • JSON output
  • HTML report with charts
  • PDF report generation
  • CSV export for data analysis
  • JUnit XML for CI/CD integration
  • Markdown summary

• Visualization

  • Interactive dashboard
  • Charts and graphs (score trends, issue breakdown)
  • Heatmap visualization overlay
  • Before/after comparisons
  • Historical data tracking

• Actionable Insights

  • Prioritized recommendations
  • Fix suggestions with code examples
  • Impact scoring for each issue
  • Quick wins identification
  • Competitor comparison

# Developer experience

• CLI Tool

  • Command-line interface
  • Interactive mode — full-screen TUI dashboard
  • Progress indicators
  • Watch mode for development
  • Glob pattern support for multiple URLs
  • CI/CD integration examples

• API

  • MCP server (stdio) — seo_audit, seo_score, seo_check_category tools for AI agents
  • REST API server
  • WebSocket for real-time updates
  • API authentication
  • Rate limiting
  • API documentation (OpenAPI/Swagger)

• Documentation

  • Comprehensive README
  • API reference
  • Configuration guide
  • Best practices guide
  • Troubleshooting guide
  • Contributing guidelines — see Contributing & Support
  • Example use cases
  • Video tutorials

• IDE Integration

  • VSCode extension
  • Inline warnings in editor
  • Quick fix actions

# DevOps & deployment

• CI/CD

  • GitHub Actions workflow — lint, type-check, and test on every push/PR
  • Automated testing
  • Automated releases
  • Semantic versioning — strict SemVer tags (v0.1.0, v0.1.1) across packages and manifests
  • Changelog generation — auto-generated from commit history between tags

• Package Distribution

  • NPM package publishing
  • Docker image — built and pushed to GHCR on release
  • Standalone binary — native cross-compiled Rust binaries (tui, aviary-fast) for Linux, macOS, and Windows via platform packages and GitHub releases
  • GitHub releases with artifacts

• Monitoring & Telemetry

  • Anonymous usage analytics (opt-in)
  • Error tracking (Sentry)
  • Performance monitoring
  • Feature usage statistics

# Security & privacy

• Security Scanning — partial

  • Dependency vulnerability scanning — npm/cargo audit, SBOM generation, and CodeQL static analysis in CI
  • Security headers check — validates HSTS, X-Frame-Options, and X-Content-Type-Options
  • XSS vulnerability detection
  • CORS configuration check
  • Content Security Policy validation — validates CSP header presence and directives

• Privacy

  • No data collection by default — runs entirely local unattended audits; zero telemetry transmitted (see Privacy Policy)
  • GDPR compliance — automated detection of GDPR indicators and user rights
  • Cookie consent detection — banner, modal, and consent button detection
  • Privacy policy detection — automated footer and link verification

# Multi-language & internationalization

• i18n Support — partial
  • Multi-language reports
  • Language-specific SEO rules
  • Character encoding detection — UTF-8 and unicode validation
  • RTL language support — automated detection and dir="rtl" validation

# Integrations

• Third-party Tools

  • Google Search Console API
  • Google Analytics integration
  • Ahrefs/SEMrush API integration
  • PageSpeed Insights API
  • Lighthouse integration

• CMS Plugins

  • WordPress plugin
  • Shopify app
  • Contentful integration
  • Netlify plugin

• Version Control

  • GitHub App
  • GitLab integration
  • Bitbucket integration
  • Pre-commit hooks

# Platform support

• Browser Support

  • Firefox support
  • Safari support
  • Edge support
  • Mobile browser testing

• Operating Systems

  • Windows compatibility testing — verified on Windows runners with .exe artifact builds
  • macOS compatibility testing — verified on macOS runners in release workflow
  • Linux compatibility testing — verified on Ubuntu in CI/CD matrix

# Community & ecosystem

• Community Building

  • GitHub Discussions setup
  • Discord/Slack community
  • Contributing guidelines — see Contributing & Support
  • Code of conduct
  • Issue templates
  • PR templates

• Marketing

  • Project website
  • Blog posts and tutorials
  • Social media presence
  • Demo videos
  • Case studies

# Advanced features

• AI/ML Integration

  • Content quality scoring using NLP
  • Automated keyword suggestions
  • Competitor analysis using ML
  • Predictive SEO insights

• Continuous Monitoring

  • Scheduled scans
  • Alerting system
  • Regression detection
  • Performance tracking over time
  • SEO ranking correlation

• Multi-page Analysis

  • Entire website crawling
  • Site-wide report
  • Link graph analysis
  • Duplicate content across pages

# Maintenance

• Dependencies

  • Regular dependency updates
  • Security patches
  • Playwright version compatibility
  • Node.js version compatibility

• Deprecation Policy

  • Version support policy
  • Migration guides
  • Backward compatibility guarantees

# Priority levels

High priority — essential for v1.0 production release
Medium priority — important features for subsequent minor releases
Low priority — nice-to-have optimizations and exploratory integrations

# Next steps

• Resolve npm authentication / bypass 2FA to complete initial package bootstrapping on npm
• Release @ru1vly/aviary@0.1.0 and 0.1.1 and verify zero-install npx @ru1vly/aviary usage
• Verify cross-platform smoke tests across Linux, macOS, and Windows runners
• Implement parallel multi-URL scanning and browser resource pooling
• Implement deep link resolution crawler for broken link detection
• Add historical trend tracking and diff reporting between audits