# rangonroyutsab/seo-audit-tool architecture

> Architecture diagram of the GitHub repository rangonroyutsab/seo-audit-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rangonroyutsab/seo-audit-tool
- Repository: https://github.com/rangonroyutsab/seo-audit-tool

## Overview

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: [`frontend/src/App.jsx`](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/App.jsx) (App), [`backend/app/main.py`](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/main.py) (API entry), [`backend/app/auditor/engine.py`](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/engine.py) (Audit engine), [`frontend/src/pages/FormPage.jsx`](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/pages/FormPage.jsx) (Form page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App<br/>react shell<br/>[App.jsx]"]
  node_frontend_main["Boot<br/>react entry<br/>[main.jsx]"]
  node_frontend_form["Form page<br/>ui page<br/>[FormPage.jsx]"]
  node_frontend_results["Results page<br/>ui page<br/>[ResultsPage.jsx]"]
  node_frontend_api["API client<br/>browser client<br/>[api.js]"]
  node_frontend_history["History<br/>client state<br/>[auditHistory.js]"]
  node_frontend_styles["Styles<br/>ui styling<br/>[styles.css]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_engine["Audit engine<br/>analysis orchestrator<br/>[engine.py]"]
  node_backend_models["Models<br/>response schema<br/>[models.py]"]
  node_backend_errors["Errors<br/>failure taxonomy<br/>[errors.py]"]
  node_backend_pagespeed["PageSpeed<br/>PSI adapter<br/>[pagespeed.py]"]
end

subgraph group_external["External services"]
  node_chromium["Chromium<br/>browser runtime"]
  node_pagespeed_api["PSI API<br/>external API"]
end

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"shows entry"| node_frontend_form
node_frontend_app -->|"shows output"| node_frontend_results
node_frontend_form -->|"submits URL"| node_frontend_api
node_frontend_api -->|"POST /api/audits"| node_backend_main
node_backend_main -->|"delegates"| node_backend_engine
node_backend_engine -->|"produces"| node_backend_models
node_backend_engine -->|"raises"| node_backend_errors
node_backend_engine -->|"renders page"| node_chromium
node_backend_engine -->|"enriches"| node_backend_pagespeed
node_backend_pagespeed -->|"calls"| node_pagespeed_api
node_backend_main -->|"returns JSON"| node_frontend_results
node_frontend_app -->|"tracks session"| node_frontend_history
node_frontend_app -->|"styles"| node_frontend_styles
node_backend_main -->|"serializes"| node_backend_models
node_backend_main -->|"maps errors"| node_backend_errors

click node_frontend_app "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/App.jsx"
click node_frontend_main "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/main.jsx"
click node_frontend_form "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/pages/FormPage.jsx"
click node_frontend_results "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/pages/ResultsPage.jsx"
click node_frontend_api "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/api.js"
click node_frontend_history "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/auditHistory.js"
click node_frontend_styles "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/styles.css"
click node_backend_main "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/main.py"
click node_backend_engine "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/engine.py"
click node_backend_models "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/models.py"
click node_backend_errors "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/errors.py"
click node_backend_pagespeed "https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/pagespeed.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_main,node_frontend_form,node_frontend_results,node_frontend_api,node_frontend_history,node_frontend_styles toneBlue
class node_backend_main,node_backend_engine,node_backend_models,node_backend_errors,node_backend_pagespeed toneAmber
class node_chromium,node_pagespeed_api toneMint
```

## Components

### Frontend

React/Vite single-page client for URL entry and results display.

- [App](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/App.jsx): react shell · Top-level client shell that wires routing, state, and page selection. · `frontend/src/App.jsx`
- [Boot](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/main.jsx): react entry · Vite/React entrypoint that mounts the application. · `frontend/src/main.jsx`
- [Form page](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/pages/FormPage.jsx): ui page · URL submission screen with loading and error handling. · `frontend/src/pages/FormPage.jsx`
- [Results page](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/pages/ResultsPage.jsx): ui page · Dashboard view for overall score, category scores, and findings. · `frontend/src/pages/ResultsPage.jsx`
- [API client](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/api.js): browser client · Frontend-to-backend request layer for audit submission. · `frontend/src/api.js`
- [History](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/auditHistory.js): client state · Client-side history or session-memory helper without server persistence. · `frontend/src/auditHistory.js`
- [Styles](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/frontend/src/styles.css): ui styling · Global presentation and responsive layout styles. · `frontend/src/styles.css`

### Backend

FastAPI service plus audit engine for stateless SEO analysis.

- [API entry](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/main.py): FastAPI app · HTTP entrypoint exposing health and audit endpoints. · `backend/app/main.py`
- [Audit engine](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/engine.py): analysis orchestrator · Coordinates validation, page rendering, scoring, and response assembly. · `backend/app/auditor/engine.py`
- [Models](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/models.py): response schema · Defines audit payloads, category scores, and finding structures. · `backend/app/auditor/models.py`
- [Errors](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/errors.py): failure taxonomy · Centralizes structured failures for invalid URLs, timeouts, blocks, and non-HTML responses. · `backend/app/auditor/errors.py`
- [PageSpeed](https://github.com/rangonroyutsab/seo-audit-tool/blob/main/backend/app/auditor/pagespeed.py): PSI adapter · 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**: browser runtime · Headless browser used through Playwright to render target pages.
- **PSI API**: external API · Optional Google PageSpeed Insights service used when an API key is configured.

## Connections

- 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.
