# mhbhuiyan99/seo_audit_tool architecture

> Architecture diagram of the GitHub repository mhbhuiyan99/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/mhbhuiyan99/seo_audit_tool
- Repository: https://github.com/mhbhuiyan99/seo_audit_tool

## Overview

1. **What this repo is**
   - Sitewell is a **single-service SEO audit application** built on **Django 5** plus **Playwright**.
   - Its core job is to take one target URL, crawl/render it in a real Chromium browser, grade SEO and performance signals, store the result, and return a JSON report that the browser dashboard renders.

2. **Top-level runtime shape**
   - The app runs as a **containerized Django server** with a Playwright-ready base image.
   - There is no separate frontend build, worker queue, or microservice split; the main boundary is between the **HTTP request layer**, the **browser automation worker thread**, and the **persistence layer**.

3. **Request entry and routing**
   - `config/urls.py` is the top-level router.
   - It sends the dashboard page to Django templates and mounts the analyzer API under `/api/`.
   - `analyzer/urls.py` exposes the audit and history endpoints used by the dashboard.

4. **User-facing UI boundary**
   - `templates/dashboard.html` is a self-contained single-page interface.
   - It uses **vanilla JavaScript** and **Tailwind CDN**, with no React/Vue or client-side build pipeline.
   - The UI submits audit requests via `fetch`, renders the returned JSON, animates inline SVG score gauges, and can refresh historical scans from the API.

5. **Audit execution pipeline**
   - The main audit endpoint is in `analyzer/views.py`.
   - A request does not run the scan inline on the Django thread; it submits work to a **module-level `ThreadPoolExecutor`** and waits with a timeout.
   - This is the key concurrency boundary: Django handles the request, a worker thread runs the browser scan, then the result comes back as JSON.

6. **Browser automation and crawling**
   - `analyzer/scanner.py` is the scanning engine.
   - It uses **Playwright’s sync API** to launch Chromium, open the target page, and collect page signals.
   - The scanner includes practical guardrails such as navigation retries, content-type checks, and a robots-related fetch before scanning.

7. **What the scanner extracts**
   - The scan is not a general crawler; it focuses on **on-page SEO and performance signals** for a single URL.
   - Extracted data includes metadata, headings, structured data / JSON-LD, social metadata, images, links, and timing/performance information.
   - The result is a structured “raw scan” dictionary that becomes the input to the rule engine.

8. **Grading and diagnostics**
   - `analyzer/seo_rules.py` turns scan output into a scored report.
   - It applies a fixed set of SEO rules and classifies each one as PASS, WARNING, or FAIL.
   - Each check carries a score, severity, evidence snippet, and recommendation, which is what the dashboard displays.

9. **Persistence and scan history**
   - `analyzer/models.py` defines the scan history model stored in **SQLite**.
   - The full report is persisted in a **JSONField**, so the app can show previous audits without re-running the scan.
   - The migrations directory shows this is a normal Django ORM-backed history store rather than an external analytics database.

10. **API/data flow back to the browser**
   - The scan result is converted to a JSON response from the view layer.
   - The dashboard then renders the overall score, category scores, rule cards, and filterable status tabs from that payload.
   - A separate history endpoint lets the UI reload prior audits and selected scan details.

11. **Important operational boundary**
   - The architecture is intentionally built around **blocking Playwright work isolated from request threads**.
   - That prevents a slow or hung browser session from freezing the Django process.
   - The timeout in the view layer acts as the service-level protection against dead pages, long redirects, or stalled browser activity.

12. **Deployment and infrastructure**
   - `Dockerfile` and `docker-compose.yml` package the app into one containerized service on port 8000.
   - The Playwright base image matters architecturally because it bundles the browser and Linux dependencies required for headless Chromium.
   - The repo is therefore optimized for reproducible local/CI execution rather than distributed scaling.

Main entry points: [`analyzer/views.py`](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/views.py) (API views), [`analyzer/models.py`](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/models.py) (Scan record), [`analyzer/scanner.py`](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/scanner.py) (Scanner), [`templates/dashboard.html`](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/templates/dashboard.html) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Django app"]
  node_config_urls["URL router<br/>django routes<br/>[urls.py]"]
  node_analyzer_urls["API routes<br/>django routes<br/>[urls.py]"]
  node_analyzer_views["API views<br/>request handler<br/>[views.py]"]
  node_config_settings["Settings<br/>django config<br/>[settings.py]"]
end

subgraph group_g2["Scan pipeline"]
  node_scanner["Scanner<br/>Playwright engine<br/>[scanner.py]"]
  node_seo_rules["SEO rules<br/>scoring engine<br/>[seo_rules.py]"]
  node_thread_pool(("Worker pool<br/>concurrency boundary<br/>[views.py]"))
end

subgraph group_g3["UI and storage"]
  node_dashboard["Dashboard<br/>vanilla SPA<br/>[dashboard.html]"]
  node_scan_model[("Scan record<br/>Django model<br/>[models.py]")]
  node_json_field["Report JSON<br/>stored payload<br/>[models.py]"]
  node_migrations["Migrations<br/>schema history<br/>[0001_initial.py]"]
end

subgraph group_g4["Deployment"]
  node_dockerfile["App image<br/>container build"]
  node_compose["Compose stack<br/>service orchestration<br/>[docker-compose.yml]"]
  node_manage["Admin CLI<br/>Django entrypoint<br/>[manage.py]"]
end

node_config_urls -->|"serves"| node_dashboard
node_config_urls -->|"mounts /api"| node_analyzer_urls
node_analyzer_urls -->|"dispatches"| node_analyzer_views
node_dashboard -->|"fetches"| node_analyzer_views
node_analyzer_views -->|"submits work"| node_thread_pool
node_thread_pool -->|"runs"| node_scanner
node_scanner -->|"raw scan"| node_seo_rules
node_seo_rules -->|"report"| node_analyzer_views
node_analyzer_views -->|"persists"| node_scan_model
node_scan_model -->|"contains"| node_json_field
node_scan_model -->|"evolves via"| node_migrations
node_config_settings -->|"configures db"| node_scan_model
node_dockerfile -->|"packages"| node_scanner
node_compose -->|"builds"| node_dockerfile
node_manage -->|"bootstraps"| node_config_settings
node_analyzer_views -->|"returns JSON"| node_dashboard

click node_config_urls "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/config/urls.py"
click node_analyzer_urls "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/urls.py"
click node_analyzer_views "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/views.py"
click node_config_settings "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/config/settings.py"
click node_scanner "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/scanner.py"
click node_seo_rules "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/seo_rules.py"
click node_thread_pool "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/views.py"
click node_dashboard "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/templates/dashboard.html"
click node_scan_model "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/models.py"
click node_json_field "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/models.py"
click node_migrations "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/migrations/0001_initial.py"
click node_dockerfile "https://github.com/mhbhuiyan99/seo_audit_tool/tree/main/Dockerfile"
click node_compose "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/docker-compose.yml"
click node_manage "https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/manage.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_config_urls,node_analyzer_urls,node_analyzer_views,node_config_settings toneBlue
class node_scanner,node_seo_rules,node_thread_pool toneAmber
class node_dashboard,node_scan_model,node_json_field,node_migrations toneMint
class node_dockerfile,node_compose,node_manage toneRose
```

## Components

### Django app

HTTP routing, request handling, and app settings

- [URL router](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/config/urls.py): django routes · Top-level Django router that splits dashboard and API traffic · `config/urls.py`
- [API routes](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/urls.py): django routes · Analyzer endpoint routing for audit and history · `analyzer/urls.py`
- [API views](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/views.py): request handler · Runs audit requests and serves history responses · `analyzer/views.py`
- [Settings](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/config/settings.py): django config · Project configuration including database and app wiring · `config/settings.py`

### Scan pipeline

Browser automation and SEO grading

- [Scanner](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/scanner.py): Playwright engine · Launches Chromium and collects page-level audit signals · `analyzer/scanner.py`
- [SEO rules](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/seo_rules.py): scoring engine · Transforms raw scan data into scored checks and recommendations · `analyzer/seo_rules.py`
- [Worker pool](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/views.py): concurrency boundary · Module-level executor that isolates blocking browser work from request threads · `analyzer/views.py`

### UI and storage

Browser dashboard, Django models, and local persistence

- [Dashboard](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/templates/dashboard.html): vanilla SPA · Single-page HTML interface that submits audits and renders results · `templates/dashboard.html`
- [Scan record](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/models.py): Django model · Stores audit history and full JSON reports in SQLite · `analyzer/models.py`
- [Report JSON](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/models.py): stored payload · Persisted scan report used to reload prior audits · `analyzer/models.py`
- [Migrations](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/analyzer/migrations/0001_initial.py): schema history · Database schema evolution for the scan history store · `analyzer/migrations/0001_initial.py`

### Deployment

Containerized runtime and service wiring

- [App image](https://github.com/mhbhuiyan99/seo_audit_tool/tree/main/Dockerfile): container build · Playwright-ready container image for Django and Chromium · `Dockerfile`
- [Compose stack](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/docker-compose.yml): service orchestration · Local container orchestration for the single service · `docker-compose.yml`
- [Admin CLI](https://github.com/mhbhuiyan99/seo_audit_tool/blob/main/manage.py): Django entrypoint · Command-line entry for running the Django project · `manage.py`

## Connections

- URL router → Dashboard: serves · Routes browser requests to the dashboard page
- URL router → API routes: mounts /api · Delegates API traffic to the analyzer app
- API routes → API views: dispatches · Maps audit and history endpoints to view handlers
- Dashboard → API views: fetches · Submits audits and loads history over HTTP
- API views → Worker pool: submits work · Offloads scan execution to a worker thread
- Worker pool → Scanner: runs · Executes the Playwright scan in a blocking worker
- Scanner → SEO rules: raw scan · Produces structured scan data consumed by the rule engine
- SEO rules → API views: report · Returns scored checks and recommendations to the response layer
- API views → Scan record: persists · Stores completed audits and history records
- Scan record → Report JSON: contains · Keeps the full report payload in a JSON field
- Scan record → Migrations: evolves via · Schema changes are managed through Django migrations
- Settings → Scan record: configures db · Defines the ORM-backed SQLite storage setup
- App image → Scanner: packages · Provides Playwright and browser dependencies
- Compose stack → App image: builds · Runs the application as one containerized service
- Admin CLI → Settings: bootstraps · Starts the Django project using the configured settings
- API views → Dashboard: returns JSON · Sends the audit payload consumed by the UI
