# PlatPhorm Insights - Complete Technical Reference

> Enterprise-grade web performance, accessibility, SEO, and sustainability analysis platform.
> Version: 2.0.0
> Last Updated: 2026-04-08T12:35:32.968Z

## Table of Contents

1. Overview
2. Architecture
3. API Reference
4. MCP Integration
5. Analysis Modules
6. Data Schemas
7. Webhooks
8. Error Handling
9. Rate Limiting
10. Security

---

## Overview

PlatPhorm Insights provides comprehensive web analysis through:

- **Custom Analysis Engine**: No dependency on Google PageSpeed API
- **AI-Powered Recommendations**: Grok AI integration for intelligent suggestions
- **Real-time Validation**: W3C HTML, CSS, ARIA, and link validation
- **Sustainability Metrics**: Carbon footprint and green hosting analysis
- **Multi-language Support**: 10 locales with RTL support

### Key Differentiators

1. **Independence**: Own analysis infrastructure, no third-party API dependencies
2. **AI-Native**: Built for LLM consumption with structured outputs
3. **Comprehensive**: Single platform for performance, accessibility, SEO, security, sustainability
4. **Network Effect**: Part of PlatPhorm News Network ecosystem
5. **Real-time**: Instant analysis with streaming results

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     PlatPhorm Insights                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │   Web UI    │  │   REST API  │  │ MCP Server  │            │
│  │  (Next.js)  │  │   (v1/v2)   │  │ (JSON-RPC)  │            │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
│         │                │                │                    │
│         └────────────────┼────────────────┘                    │
│                          │                                      │
│  ┌───────────────────────┴───────────────────────┐             │
│  │              Analysis Engine                   │             │
│  ├───────────────────────────────────────────────┤             │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐        │             │
│  │  │   DOM   │ │Resource │ │  Perf   │        │             │
│  │  │ Parser  │ │ Loader  │ │ Timer   │        │             │
│  │  └────┬────┘ └────┬────┘ └────┬────┘        │             │
│  │       └───────────┼───────────┘              │             │
│  │                   ▼                          │             │
│  │  ┌────────────────────────────────────────┐ │             │
│  │  │           Analysis Modules             │ │             │
│  │  │  Performance | A11y | SEO | Security  │ │             │
│  │  │  Sustainability | W3C | Links | LLM   │ │             │
│  │  └────────────────────────────────────────┘ │             │
│  └───────────────────────────────────────────────┘             │
│                          │                                      │
│                          ▼                                      │
│  ┌───────────────────────────────────────────────┐             │
│  │              AI Analysis Layer                │             │
│  │         (Grok AI / Vercel AI Gateway)        │             │
│  └───────────────────────────────────────────────┘             │
│                          │                                      │
│                          ▼                                      │
│  ┌───────────────────────────────────────────────┐             │
│  │                Neon Database                  │             │
│  │    (Analysis Results | History | Analytics)   │             │
│  └───────────────────────────────────────────────┘             │
└─────────────────────────────────────────────────────────────────┘
```

---

## MCP Server Details

### Endpoint
```
https://insights.platphormnews.com/api/mcp
```

### Protocol
JSON-RPC 2.0 over HTTP POST

### Authentication
Optional Bearer token for higher rate limits

### Available Tools


#### analyze_url
Analyze a URL for performance, accessibility, SEO, and best practices. Returns Lighthouse scores, Core Web Vitals, and AI-powered recommendations.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to analyze (must be publicly accessible)"
    },
    "strategy": {
      "type": "string",
      "enum": [
        "mobile",
        "desktop"
      ],
      "description": "Device strategy for analysis (default: mobile)"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "performance",
          "accessibility",
          "best-practices",
          "seo"
        ]
      },
      "description": "Categories to analyze (default: all)"
    }
  },
  "required": [
    "url"
  ]
}
```


#### get_core_web_vitals
Get Core Web Vitals (LCP, INP, CLS, TTFB, FCP) for a URL with field data from CrUX when available.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to get Core Web Vitals for"
    },
    "origin": {
      "type": "boolean",
      "description": "Get origin-level data instead of URL-level (default: false)"
    }
  },
  "required": [
    "url"
  ]
}
```


#### compare_urls
Compare performance metrics between multiple URLs. Useful for competitive analysis or A/B testing.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 2,
      "maxItems": 5,
      "description": "URLs to compare (2-5 URLs)"
    },
    "strategy": {
      "type": "string",
      "enum": [
        "mobile",
        "desktop"
      ],
      "description": "Device strategy for comparison (default: mobile)"
    }
  },
  "required": [
    "urls"
  ]
}
```


#### get_recommendations
Get AI-powered optimization recommendations for a previously analyzed URL.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "analysis_id": {
      "type": "string",
      "description": "The analysis ID from a previous analyze_url call"
    },
    "focus": {
      "type": "string",
      "enum": [
        "performance",
        "accessibility",
        "seo",
        "security",
        "all"
      ],
      "description": "Focus area for recommendations (default: all)"
    }
  },
  "required": [
    "analysis_id"
  ]
}
```


#### check_security_headers
Analyze security headers of a URL including CSP, HSTS, X-Frame-Options, etc.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to check security headers for"
    }
  },
  "required": [
    "url"
  ]
}
```


#### estimate_carbon_footprint
Estimate the carbon footprint of a webpage based on data transfer and green hosting status.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to estimate carbon footprint for"
    }
  },
  "required": [
    "url"
  ]
}
```


#### bulk_analyze
Analyze multiple URLs in batch. Returns job ID for tracking progress.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "description": "URLs to analyze (max 10)"
    },
    "strategy": {
      "type": "string",
      "enum": [
        "mobile",
        "desktop"
      ],
      "description": "Device strategy for analysis (default: mobile)"
    },
    "webhook_url": {
      "type": "string",
      "description": "Optional webhook URL to receive results when complete"
    }
  },
  "required": [
    "urls"
  ]
}
```


#### get_analysis_history
Get historical analysis results for a URL to track performance over time.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The URL to get history for"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of results to return (default: 10)"
    },
    "days": {
      "type": "number",
      "description": "Number of days to look back (default: 30)"
    }
  },
  "required": [
    "url"
  ]
}
```


---

## API Reference

### Base URL
```
Production: https://insights.platphormnews.com/api/v1
```

### Authentication
```http
Authorization: Bearer YOUR_API_KEY
X-Request-ID: unique-request-id
```

### POST /api/v1/analyze

Analyzes a URL for performance, accessibility, SEO, security, and sustainability.

**Request:**
```json
{
  "url": "https://example.com",
  "strategy": "mobile",
  "categories": ["performance", "accessibility", "seo", "security", "sustainability"],
  "options": {
    "waitForSelector": ".main-content",
    "timeout": 30000,
    "emulateDevice": "Pixel 7"
  }
}
```

**Response:**
```json
{
  "id": "uuid",
  "status": "complete",
  "url": "https://example.com",
  "finalUrl": "https://example.com/",
  "timestamp": "2026-03-16T12:00:00Z",
  "duration": 4523,
  "scores": {
    "performance": 85,
    "accessibility": 92,
    "seo": 88,
    "security": 95,
    "sustainability": 78,
    "overall": 87.6
  },
  "coreWebVitals": {
    "lcp": { "value": 2100, "unit": "ms", "rating": "good", "percentile": 75 },
    "inp": { "value": 150, "unit": "ms", "rating": "good", "percentile": 95 },
    "cls": { "value": 0.05, "unit": "score", "rating": "good", "percentile": 75 },
    "fcp": { "value": 1200, "unit": "ms", "rating": "good", "percentile": 75 },
    "ttfb": { "value": 450, "unit": "ms", "rating": "good", "percentile": 75 }
  },
  "issues": [...],
  "recommendations": [...],
  "metadata": {...}
}
```

### POST /api/v1/compare

Compares multiple URLs side-by-side.

**Request:**
```json
{
  "urls": ["https://site1.com", "https://site2.com"],
  "strategy": "mobile",
  "categories": ["performance", "accessibility"]
}
```

### POST /api/v1/validate

W3C validation for HTML, CSS, ARIA.

**Request:**
```json
{
  "url": "https://example.com",
  "validators": ["html", "css", "aria", "links"],
  "options": {
    "showSource": true,
    "outline": true
  }
}
```

### GET /api/v1/results/{id}

Retrieves a previously run analysis by ID.

### GET /api/v1/history/{domain}

Get analysis history for a domain.

**Query Parameters:**
- `limit`: Number of results (default: 10, max: 100)
- `offset`: Pagination offset
- `from`: Start date (ISO 8601)
- `to`: End date (ISO 8601)

### GET /api/health

Health check endpoint returning service status.

---

## Analysis Modules

### Performance Analysis

Metrics collected:
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- Interaction to Next Paint (INP)
- Cumulative Layout Shift (CLS)
- Time to First Byte (TTFB)
- Total Blocking Time (TBT)
- Speed Index
- Time to Interactive (TTI)

Checks performed:
- Render-blocking resources
- Image optimization (format, size, lazy loading)
- JavaScript bundle analysis
- CSS critical path
- Font loading strategy
- Cache policy evaluation
- Compression (Brotli/gzip)
- HTTP/2 and HTTP/3 usage

### Accessibility Analysis (WCAG 2.2)

Level A checks:
- Non-text content alternatives
- Time-based media alternatives
- Adaptable content structure
- Distinguishable elements
- Keyboard accessibility
- Seizure prevention
- Navigable content
- Readable text
- Predictable interface
- Input assistance

Level AA checks:
- Color contrast (4.5:1 for normal text, 3:1 for large text)
- Text resize support
- Images of text avoidance
- Multiple navigation methods
- Clear headings and labels
- Focus visibility
- Consistent navigation
- Error identification and suggestion

### SEO/AEO/GEO Analysis

SEO Factors:
- Title tag optimization (length, keywords, uniqueness)
- Meta description quality
- Heading hierarchy (H1-H6)
- Image alt attributes
- Internal link structure
- Canonical URL configuration
- Mobile-friendliness
- HTTPS security
- URL structure

AEO (Answer Engine Optimization):
- Featured snippet optimization
- FAQ schema implementation
- How-to structured data
- Direct answer formatting
- Question-answer patterns

GEO (Generative Engine Optimization):
- llms.txt presence and quality
- Structured data comprehensiveness
- Content clarity for AI parsing
- API documentation quality
- Semantic HTML usage
- Entity relationship clarity

### Security Analysis

Headers checked:
- Content-Security-Policy (CSP)
- Strict-Transport-Security (HSTS)
- X-Content-Type-Options
- X-Frame-Options
- X-XSS-Protection
- Referrer-Policy
- Permissions-Policy
- Cross-Origin-Opener-Policy (COOP)
- Cross-Origin-Embedder-Policy (COEP)
- Cross-Origin-Resource-Policy (CORP)

### Sustainability Analysis

Metrics:
- Page weight (KB)
- Number of requests
- Data transfer per visit
- Estimated CO2 per page view
- Green hosting status
- CDN usage
- Caching efficiency
- Image optimization level

Carbon calculation methodology:
```
CO2 per visit = Data Transfer (GB) × Energy Intensity × Carbon Intensity
Energy Intensity = 0.81 kWh/GB (global average)
Carbon Intensity = 442 g CO2/kWh (global grid average)
Green hosting modifier = 0.09× for renewable-powered hosts
```

---

## Data Models

### Analysis Result Schema
```typescript
interface AnalysisResult {
  id: string
  url: string
  finalUrl: string
  timestamp: string
  duration: number
  strategy: 'mobile' | 'desktop'
  
  scores: {
    performance: number
    accessibility: number
    seo: number
    security: number
    sustainability: number
    overall: number
  }
  
  coreWebVitals: {
    lcp: MetricResult
    inp: MetricResult
    cls: MetricResult
    fcp: MetricResult
    ttfb: MetricResult
  }
  
  issues: Issue[]
  recommendations: Recommendation[]
  
  metadata: {
    htmlSize: number
    resourceCount: number
    totalBytes: number
    domElements: number
    requests: number
  }
}

interface MetricResult {
  value: number
  unit: string
  rating: 'good' | 'needs-improvement' | 'poor'
  percentile: number
}

interface Issue {
  id: string
  category: string
  severity: 'critical' | 'serious' | 'moderate' | 'minor'
  title: string
  description: string
  impact: string
  howToFix: string
  affectedElements?: string[]
  wcagCriteria?: string[]
}
```

### Core Web Vitals Thresholds (2026)
| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| LCP | ≤2.5s | ≤4.0s | >4.0s |
| INP | ≤200ms | ≤500ms | >500ms |
| CLS | ≤0.1 | ≤0.25 | >0.25 |
| FCP | ≤1.8s | ≤3.0s | >3.0s |
| TTFB | ≤800ms | ≤1800ms | >1800ms |

---

## Webhooks

### Event Types

| Event | Description |
|-------|-------------|
| analysis.started | Analysis has begun |
| analysis.complete | Analysis finished successfully |
| analysis.failed | Analysis encountered an error |
| threshold.violated | A metric exceeded configured threshold |
| scheduled.complete | Scheduled analysis batch completed |

### Payload Format
```json
{
  "event": "analysis.complete",
  "timestamp": "2026-03-16T12:00:00Z",
  "data": {
    "analysisId": "uuid",
    "url": "https://example.com",
    "scores": {...},
    "coreWebVitals": {...}
  },
  "signature": "sha256=..."
}
```

---

## Rate Limits

| Tier | Requests/Hour | Burst | Concurrent |
|------|---------------|-------|------------|
| Free | 60 | 10 | 2 |
| Pro | 500 | 50 | 10 |
| Business | 2000 | 100 | 25 |
| Enterprise | Custom | Custom | Custom |

---

## Network Integration

PlatPhorm Insights is part of the PlatPhorm News Network:

| Platform | URL |
|----------|-----|
| PlatPhorm News | https://platphormnews.com |
| Polymaths | https://polymaths.platphormnews.com |
| Trace Analytics | https://trace.platphormnews.com |
| Documentation | https://docs.platphormnews.com |

---

## Internationalization

Supported locales: en, es, fr, de, pt, zh, ja, ko, ar, hi

All API responses respect the Accept-Language header or locale parameter.

---

## Support

- Documentation: https://insights.platphormnews.com/docs
- FAQ: https://insights.platphormnews.com/faq
- GitHub: https://github.com/platphorm/insights
- Email: insights@platphormnews.com

---

Last Updated: 2026-04-08T12:35:32.968Z
Version: 2.0.0