# Audesto - Full Technical Specification & AI Agent Guide

> Audesto is an advanced, enterprise-grade Web Audit, Technical SEO, Core Web Vitals, and AI Engine Optimization (AEO) platform built for digital agencies, SEO specialists, and web developers.

## System Architecture & Capabilities

### 1. Single Page Audit Engine
- **Targeting**: Analyzes any publicly accessible URL in real-time.
- **Header Parsing**: Evaluates HTTP status codes, response headers, canonical link tags, viewport configurations, and hreflang localization directives.
- **Semantic Structure**: Extracts H1-H6 heading hierarchy, title tag length (50-60 characters optimal), meta description length (150-160 characters optimal), Open Graph tags, and Twitter Cards.
- **Content & Keywords**: Calculates word count, readability index, target keyword frequency, title keyword placement, and image alt attribute coverage.

### 2. Entire Website Crawler
- **Crawl Depth**: Discovers and indexes up to 100 internal directory nodes.
- **Link Auditing**: Validates internal link integrity, detects 404 broken links, external outbound link count, and identifies missing `rel="noopener"` or `rel="noreferrer"` security vulnerabilities on `target="_blank"` links.
- **Site Structure**: Generates internal crawl graph visual maps and estimates page click depth from the homepage.

### 3. AEO & GEO (AI Engine Optimization & Generative Engine Optimization)
- **llms.txt Detection**: Automatically checks domain root for `/llms.txt` plain-text Markdown summary directories.
- **Knowledge Graph & Schema**: Parses Schema.org JSON-LD (WebSite, Organization, Article, LocalBusiness, Product, SoftwareApplication, FAQPage) for AI agent citation readiness.
- **Semantic Clarity**: Assesses whether content contains direct answer paragraphs, bulleted summary blocks, and clear entity definitions optimal for RAG vector indexing.

### 4. Technical Performance & Core Web Vitals
- **LCP (Largest Contentful Paint)**: Measure of main content render speed (Target: < 2.5s).
- **TBT (Total Blocking Time)**: Measure of main thread activity and responsiveness (Target: < 200ms).
- **CLS (Cumulative Layout Shift)**: Measure of visual layout stability (Target: < 0.10).
- **Asset Preloading & Compression**: Verifies gzip/brotli transfer encoding, critical font preloading (`Inter-Regular.woff2`), and image width/height explicit sizing attributes.

### 5. White-Label Report PDF Generation
- **Branding Customization**: Custom agency name, logo URL, brand hex colors, and custom footers.
- **PDF Engine**: Server-side PDF layout synthesis with executive summary metrics, category breakdown charts, and prioritized fix roadmaps.

## API Specification for AI Agents

### Health Check
- `GET /api/health`
- Response: `{ "status": "ok", "version": "2.4.0", "timestamp": "2026-07-25T00:00:00Z" }`

### Create Audit
- `POST /api/audit/`
- Request Payload:
  ```json
  {
    "url": "https://example.com",
    "audit_type": "page" | "website",
    "target_keyword": "digital marketing"
  }
  ```
- Response: Returns audit JSON object containing overall score, Core Web Vitals metrics, category breakdowns, and audit UUID.

### Fetch Audit Results
- `GET /api/audit/<uuid>/`
- Response: Full structured audit report JSON.

### Generate White-Label PDF Report
- `GET /api/audit/<uuid>/pdf?recaptchaToken=<token>`
- Response: Binary PDF file with `Content-Type: application/pdf` and `Content-Disposition: attachment; filename="audit_report_domain_date.pdf"`.

## LLM Crawler Directives
- **Allowed Bots**: All AI search crawlers including GPTBot, ChatGPT-User, PerplexityBot, Google-Extended, ClaudeBot, Anthropic-ai, Copilot, Grok, Applebot-Extended, and WebMCP agents are welcomed.
- **Rate Limits**: 100 requests per minute per IP address.
- **Contact & Support**: For platform integrations or enterprise access, visit https://audesto.toolchunks.com/