Documentation

Overview

WP Audit Platform crawls your site (breadth-first, same origin), analyzes each page with passive HTML and header checks, then builds a report with scores, issues, and recommendations. No browser is opened for every URL during crawl, so scans stay fast and stable.

• No authentication — start audits from the UI or API without registering or sending tokens
• SEO — titles, meta, headings, canonicals, schema, images, duplicates, robots/sitemap
• Security — HTTPS, SSL, security headers, mixed content, WordPress exposures
• Performance — scripts, CSS, DOM size, lazy loading, cache headers
• WordPress — detection confidence, plugins, themes, version leaks
• Technology stack — CMS, CDN, analytics, frameworks

Deployment note: In public mode, anyone who can reach this server can run audits and view audit history. Use on localhost or a trusted network unless you add your own access controls.

How it works

1. Submit — You enter a URL in the UI or POST /audits; no auth step.
2. Queue — The audit is queued (status: queued).
3. Crawl — BFS discovers pages (up to CRAWL_MAX_PAGES, default 50). Progress 5–40%.
4. Analyze — SEO, security headers, WP fingerprinting, tech stack per page; site-wide robots and WP probes.
5. Performance — Lightweight metrics always; optional Lighthouse if enabled.
6. Report — Issues deduplicated, report saved; status: completed.

URL → API → Crawl (BFS) → Analyzers → Performance step → Report → Done

Queue mode: QUEUE_MODE=inline runs jobs inside the API process (local dev). QUEUE_MODE=bullmq uses Redis and a worker process for production.

Using the web UI

1. Open New audit and enter a URL (e.g. example.com — https is added automatically).
2. Watch progress on the audit page; open the report when complete.
3. Use History to see past audits on this server.
4. Expand issues and page rows for full descriptions and recommendations.

There is no sign-up, login, or API token stored in the browser.

API access

All /audits endpoints are open. Send JSON requests with Content-Type: application/json only — do not send Authorization: Bearer ….

POST http://localhost:8997/api/v1/audits
Content-Type: application/json

{ "url": "https://example.com" }

The app uses an internal guest user in MongoDB so data models stay consistent. The dashboard lists all recent audits on this instance.

API endpoints

Base path: http://localhost:8997/api/v1. Rate limit: 100 requests / 15 min per IP by default.

API workflow

1. Start an audit

POST http://localhost:8997/api/v1/audits
Content-Type: application/json

{ "url": "https://example.com" }

Returns 202 with data.id — save that audit ID.

2. Poll status

GET http://localhost:8997/api/v1/audits/AUDIT_ID/status

Statuses: queued → crawling → analyzing → generating → completed or failed. Poll every 3–10 seconds.

3. Fetch report

GET http://localhost:8997/api/v1/audits/AUDIT_ID/report

Returns 404 or an error if the audit is still running.

Example (curl)

AUDIT_ID=$(curl -s -X POST http://localhost:8997/api/v1/audits \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq -r '.data.id')

curl -s http://localhost:8997/api/v1/audits/$AUDIT_ID/status
curl -s http://localhost:8997/api/v1/audits/$AUDIT_ID/report

Report structure

The report JSON includes:

• overview — URL, pages scanned, issue counts, scores
• allIssues — full list with severity, category, recommendation, pageUrl
• pages — each crawled URL with status, depth, per-page issues
• seo, performance, security, wordpress — category scores and top issues
• intelligence — technologies, plugins, crawl metrics, security risk summary
• recommendations — prioritized action items

Real-time progress (Socket.IO)

Optional for web or Node clients on the same origin as the app. No login required — only pass auditId:

const socket = io('http://localhost:8997', { transports: ['polling', 'websocket'] });
socket.emit('join-audit', { auditId: '...' });
socket.on('audit:progress', (data) => { /* percent, message */ });
socket.on('audit:completed', (data) => { /* reportId */ });
socket.on('audit:failed', (data) => { /* message */ });

Server-side integrations can rely on polling /status only.

Configuration

Key environment variables (see .env.example):

Full markdown: docs/BACKEND_FLOW.md (data & analyzers), docs/CODEBASE_GUIDE.md, docs/API.md, docs/HOW_IT_WORKS.md.