How rangonroyutsab/seo-audit-tool works
1. Overall shape
- This is a stateless two-tier web app: a React/Vite frontend for user interaction and a Python/FastAPI backend for audit execution.
- There is no database or long-term storage; each audit request is processed independently and returned as JSON.
2. User-facing flow
- The user enters a URL in the frontend form, submits it, and waits on a loading state.
- The frontend then renders a results dashboard with an overall score, category scores, and detailed findings.
3. Frontend boundary
- The frontend lives under frontend/src and is split into:
- pages/FormPage.jsx for URL submission
- pages/ResultsPage.jsx for audit display
- App.jsx and main.jsx for app bootstrap/routing/state orchestration
- api.js is the browser-to-backend integration layer.
- auditHistory.js suggests a client-side-only history or session-memory helper, but not server persistence.
4. Frontend responsibilities
- The frontend handles input, loading/error states, presentation, and responsive dashboard layout.
- styles.css and the Vite setup indicate this is a single-page app built for quick local development and static deployment.
5. Backend boundary
- The backend is a FastAPI service under backend/app.
- main.py is the HTTP entrypoint and exposes at least:
- GET /health
- POST /api/audits
- Its job is to validate requests, run the audit, and return structured JSON responses or structured errors.
6. Audit engine subsystem
- The backend/app/auditor package is the core analysis layer.
- engine.py likely coordinates the full audit lifecycle.
- models.py defines the audit response and finding/category schemas.
- errors.py centralizes failure cases such as invalid URL, timeout, blocked automation, or non-HTML responses.
- This separation keeps the API layer thin and the audit logic reusable.
7. Page rendering and local analysis
- The backend uses Playwright with Chromium to fetch the target page as a rendered browser page, not just raw HTML.
- That matters architecturally because SEO/accessibility checks depend on client-rendered content and final navigated state.
- The audit returns the final URL and audit timestamp alongside scores and findings.
8. External SEO/performance integration
- pagespeed.py and the README point to an optional integration with Google PageSpeed Insights.
- When GOOGLE_PAGESPEED_INSIGHTS_API_KEY is present, the backend enriches the audit with Lighthouse/PageSpeed metrics.
- If PSI is unavailable or fails, the system still returns local audit results and includes a warning in the pagespeed category instead of failing the whole request.
9. Data flow across the system
- Browser submits URL → frontend sends request to FastAPI → backend validates and renders the target page → audit engine computes findings and scores → optional PSI metrics are merged → JSON response returns to frontend → frontend formats the dashboard.
- This is a request/response pipeline with no background jobs, queues, or persisted state.
10. Error handling model
- The backend is designed to fail atomically for invalid or unreachable targets: if the URL is malformed, times out, blocks automation, redirects badly, or returns non-HTML, the API returns a structured error.
- It does not return partial audit results in those cases, which simplifies the frontend contract.
11. Runtime and tooling
- Backend runtime: Python with FastAPI and Uvicorn.
- Browser automation runtime: Playwright plus Chromium.
- Frontend runtime: React with Vite.
- The repo uses .env.example to document configuration, especially the optional Google PSI key.
12. Architecture summary for diagramming
- Draw the frontend as a single-page React client with a form-to-results flow.
- Draw the backend as a stateless FastAPI service with an internal audit engine boundary.
- Show two external dependencies from the backend: local Chromium via Playwright and the optional Google PageSpeed Insights API.
- Omit any storage layer, because the system intentionally has none.
Main entry points: App.jsx App · main.py API entry · engine.py Audit engine · FormPage.jsx Form page
Components 14
Frontend
React/Vite single-page client for URL entry and results display.
- App · Top-level client shell that wires routing, state, and page selection.
frontend/src/App.jsx - Boot · Vite/React entrypoint that mounts the application.
frontend/src/main.jsx - Form page · URL submission screen with loading and error handling.
frontend/src/pages/FormPage.jsx - Results page · Dashboard view for overall score, category scores, and findings.
frontend/src/pages/ResultsPage.jsx - API client · Frontend-to-backend request layer for audit submission.
frontend/src/api.js - History · Client-side history or session-memory helper without server persistence.
frontend/src/auditHistory.js - Styles · Global presentation and responsive layout styles.
frontend/src/styles.css
Backend
FastAPI service plus audit engine for stateless SEO analysis.
- API entry · HTTP entrypoint exposing health and audit endpoints.
backend/app/main.py - Audit engine · Coordinates validation, page rendering, scoring, and response assembly.
backend/app/auditor/engine.py - Models · Defines audit payloads, category scores, and finding structures.
backend/app/auditor/models.py - Errors · Centralizes structured failures for invalid URLs, timeouts, blocks, and non-HTML responses.
backend/app/auditor/errors.py - PageSpeed · Optional enrichment layer for Google PageSpeed Insights and Lighthouse metrics.
backend/app/auditor/pagespeed.py
External services
Browser automation and optional third-party metrics providers.
- Chromium · Headless browser used through Playwright to render target pages.
- PSI API · Optional Google PageSpeed Insights service used when an API key is configured.
Connections 16
- Boot → App: mounts · Bootstraps the React application.
- App → Form page: shows entry · Primary initial screen for URL submission.
- App → Results page: shows output · Switches to the results dashboard after audit completion.
- Form page → API client: submits URL · Sends audit requests and handles loading/error states.
- API client → API entry: POST /api/audits · Browser client calls the audit endpoint.
- API entry → Audit engine: delegates · API layer forwards validated requests to the audit engine.
- Audit engine → Models: produces · Builds structured audit responses and findings.
- Audit engine → Errors: raises · Uses structured failure cases for atomic request rejection.
- Audit engine → Chromium: renders page · Uses Playwright with Chromium to load and inspect the target site.
- Audit engine → PageSpeed: enriches · Optionally merges external PageSpeed data into the audit.
- PageSpeed → PSI API: calls · Fetches Google PSI metrics when configured.
- API entry → Results page: returns JSON · Audit response is consumed by the dashboard.
- App → History: tracks session · Maintains client-side history or last-results context.
- App → Styles: styles · Applies shared presentation and layout rules.
- API entry → Models: serializes · Uses response schemas when serving API output.
- API entry → Errors: maps errors · Converts engine failures into structured API errors.