# titarek/pagelens architecture

> Architecture diagram of the GitHub repository titarek/pagelens, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/titarek/pagelens
- Repository: https://github.com/titarek/pagelens

## Overview

PageLens accepts a URL and inspection mode, validates the target, runs static analysis and—when requested—headless rendering, then presents a scored report with diagnostics, security findings, resources, and export/source-inspection options. The frontend’s report page polls for job completion. The README documents additional audit and dashboard capabilities; unsampled implementation details are represented only where documented, and uncertain links are omitted.

Main entry points: [`backend/app/services/analyzer.py`](https://github.com/titarek/pagelens/blob/main/backend/app/services/analyzer.py) (Analysis Orchestrator), [`backend/app/schemas/report.py`](https://github.com/titarek/pagelens/blob/main/backend/app/schemas/report.py) (Report Schema), [`frontend/src/pages/Report.tsx`](https://github.com/titarek/pagelens/blob/main/frontend/src/pages/Report.tsx) (Report View), [`backend/app/api/routes_analyze.py`](https://github.com/titarek/pagelens/blob/main/backend/app/api/routes_analyze.py) (Analysis Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analysis Dashboard"]
  node_home["Analysis Form<br/>[Home.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
  node_report_page["Report View<br/>[Report.tsx]"]
  node_report_widgets["Report Widgets"]
  node_source_viewer["Source Inspector"]
  node_explorer["Interactive Explorer"]
  node_app_router["App Router<br/>[App.tsx]"]
end

subgraph group_gateway["API and Jobs"]
  node_analyze_routes["Analysis Routes<br/>[routes_analyze.py]"]
  node_report_routes["Report Routes<br/>[routes_report.py]"]
  node_ssrf_guard["SSRF Guard<br/>[security.py]"]
  node_job_store[("Job Cache<br/>[cache.py]")]
end

subgraph group_inspection["Site Inspection"]
  node_analyzer["Analysis Orchestrator<br/>[analyzer.py]"]
  node_fetcher["HTTP Fetcher<br/>[fetcher.py]"]
  node_html_parser["HTML Parser<br/>[parser.py]"]
  node_css_collector["CSS Collector<br/>[css_collector.py]"]
  node_playwright["Headless Renderer"]
end

subgraph group_reporting["Metrics and Reports"]
  node_structural["Structural Metrics<br/>[structural.py]"]
  node_timing["Timing Metrics<br/>[timing.py]"]
  node_shortcomings["Rule Diagnostics<br/>[shortcomings.py]"]
  node_security_audit["Security Audit<br/>[audit.py]"]
  node_scoring["Score Calculator<br/>[scoring.py]"]
  node_report_schema["Report Schema<br/>[report.py]"]
  node_pdf_export["PDF Exporter<br/>[pdf_exporter.py]"]
end

node_user(("Developer"))
node_target_site(("Target Website"))

node_user -->|"submits URL"| node_home
node_app_router -->|"routes to"| node_home
node_app_router -->|"routes to"| node_report_page
node_home -->|"submits analysis"| node_api_client
node_report_page -->|"polls report"| node_api_client
node_report_page -->|"renders findings"| node_report_widgets
node_report_page -->|"renders source"| node_source_viewer
node_report_page -->|"renders explorer"| node_explorer
node_api_client -->|"HTTP JSON"| node_analyze_routes
node_api_client -->|"fetches reports"| node_report_routes
node_analyze_routes -->|"validates URL"| node_ssrf_guard
node_analyze_routes -->|"stores job"| node_job_store
node_analyze_routes -->|"schedules analysis"| node_analyzer
node_analyze_routes -->|"simulates interaction"| node_playwright
node_report_routes -->|"reads job"| node_job_store
node_report_routes -->|"validates report"| node_report_schema
node_report_routes -->|"generates PDF"| node_pdf_export
node_analyzer -->|"fetches page"| node_fetcher
node_analyzer -->|"parses HTML"| node_html_parser
node_analyzer -->|"collects CSS"| node_css_collector
node_analyzer -->|"renders deep mode"| node_playwright
node_fetcher -.->|"requests page"| node_target_site
node_playwright -.->|"renders page"| node_target_site
node_analyzer -->|"calculates structure"| node_structural
node_analyzer -->|"checks rules"| node_shortcomings
node_analyzer -->|"calculates score"| node_scoring
node_analyzer -->|"audits security"| node_security_audit
node_playwright -->|"collects timings"| node_timing
node_analyzer -->|"builds report"| node_report_schema
node_scoring -->|"sets score fields"| node_report_schema
node_structural -->|"produces metrics"| node_report_schema
node_shortcomings -->|"produces findings"| node_report_schema
node_security_audit -->|"produces audit"| node_report_schema
node_timing -->|"produces timings"| node_report_schema

click node_home "https://github.com/titarek/pagelens/blob/main/frontend/src/pages/Home.tsx"
click node_api_client "https://github.com/titarek/pagelens/blob/main/frontend/src/lib/api.ts"
click node_report_page "https://github.com/titarek/pagelens/blob/main/frontend/src/pages/Report.tsx"
click node_report_widgets "https://github.com/titarek/pagelens/tree/main/frontend/src/components"
click node_source_viewer "https://github.com/titarek/pagelens/blob/main/frontend/src/components/ScrapedSourceViewer.tsx"
click node_explorer "https://github.com/titarek/pagelens/blob/main/frontend/src/components/InteractiveExplorer.tsx"
click node_app_router "https://github.com/titarek/pagelens/blob/main/frontend/src/App.tsx"
click node_analyze_routes "https://github.com/titarek/pagelens/blob/main/backend/app/api/routes_analyze.py"
click node_report_routes "https://github.com/titarek/pagelens/blob/main/backend/app/api/routes_report.py"
click node_ssrf_guard "https://github.com/titarek/pagelens/blob/main/backend/app/core/security.py"
click node_job_store "https://github.com/titarek/pagelens/blob/main/backend/app/core/cache.py"
click node_analyzer "https://github.com/titarek/pagelens/blob/main/backend/app/services/analyzer.py"
click node_fetcher "https://github.com/titarek/pagelens/blob/main/backend/app/scraper/fetcher.py"
click node_html_parser "https://github.com/titarek/pagelens/blob/main/backend/app/scraper/parser.py"
click node_css_collector "https://github.com/titarek/pagelens/blob/main/backend/app/scraper/css_collector.py"
click node_playwright "https://github.com/titarek/pagelens/blob/main/backend/app/renderer/playwright_runner.py"
click node_structural "https://github.com/titarek/pagelens/blob/main/backend/app/metrics/structural.py"
click node_timing "https://github.com/titarek/pagelens/blob/main/backend/app/metrics/timing.py"
click node_shortcomings "https://github.com/titarek/pagelens/blob/main/backend/app/metrics/shortcomings.py"
click node_security_audit "https://github.com/titarek/pagelens/blob/main/backend/app/security/audit.py"
click node_scoring "https://github.com/titarek/pagelens/blob/main/backend/app/metrics/scoring.py"
click node_report_schema "https://github.com/titarek/pagelens/blob/main/backend/app/schemas/report.py"
click node_pdf_export "https://github.com/titarek/pagelens/blob/main/backend/app/services/pdf_exporter.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_home,node_api_client,node_report_page,node_report_widgets,node_source_viewer,node_explorer,node_app_router toneBlue
class node_analyze_routes,node_report_routes,node_ssrf_guard,node_job_store toneAmber
class node_analyzer,node_fetcher,node_html_parser,node_css_collector,node_playwright toneMint
class node_structural,node_timing,node_shortcomings,node_security_audit,node_scoring,node_report_schema,node_pdf_export toneRose
class node_user,node_target_site toneIndigo
```

## Components

### Analysis Dashboard

- [Analysis Form](https://github.com/titarek/pagelens/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [API Client](https://github.com/titarek/pagelens/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Report View](https://github.com/titarek/pagelens/blob/main/frontend/src/pages/Report.tsx): `frontend/src/pages/Report.tsx`
- [Report Widgets](https://github.com/titarek/pagelens/tree/main/frontend/src/components): `frontend/src/components`
- [Source Inspector](https://github.com/titarek/pagelens/blob/main/frontend/src/components/ScrapedSourceViewer.tsx): `frontend/src/components/ScrapedSourceViewer.tsx`
- [Interactive Explorer](https://github.com/titarek/pagelens/blob/main/frontend/src/components/InteractiveExplorer.tsx): `frontend/src/components/InteractiveExplorer.tsx`
- [App Router](https://github.com/titarek/pagelens/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and Jobs

- [Analysis Routes](https://github.com/titarek/pagelens/blob/main/backend/app/api/routes_analyze.py): `backend/app/api/routes_analyze.py`
- [Report Routes](https://github.com/titarek/pagelens/blob/main/backend/app/api/routes_report.py): `backend/app/api/routes_report.py`
- [SSRF Guard](https://github.com/titarek/pagelens/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Job Cache](https://github.com/titarek/pagelens/blob/main/backend/app/core/cache.py): `backend/app/core/cache.py`

### Site Inspection

- [Analysis Orchestrator](https://github.com/titarek/pagelens/blob/main/backend/app/services/analyzer.py): `backend/app/services/analyzer.py`
- [HTTP Fetcher](https://github.com/titarek/pagelens/blob/main/backend/app/scraper/fetcher.py): `backend/app/scraper/fetcher.py`
- [HTML Parser](https://github.com/titarek/pagelens/blob/main/backend/app/scraper/parser.py): `backend/app/scraper/parser.py`
- [CSS Collector](https://github.com/titarek/pagelens/blob/main/backend/app/scraper/css_collector.py): `backend/app/scraper/css_collector.py`
- [Headless Renderer](https://github.com/titarek/pagelens/blob/main/backend/app/renderer/playwright_runner.py): `backend/app/renderer/playwright_runner.py`

### Metrics and Reports

- [Structural Metrics](https://github.com/titarek/pagelens/blob/main/backend/app/metrics/structural.py): `backend/app/metrics/structural.py`
- [Timing Metrics](https://github.com/titarek/pagelens/blob/main/backend/app/metrics/timing.py): `backend/app/metrics/timing.py`
- [Rule Diagnostics](https://github.com/titarek/pagelens/blob/main/backend/app/metrics/shortcomings.py): `backend/app/metrics/shortcomings.py`
- [Security Audit](https://github.com/titarek/pagelens/blob/main/backend/app/security/audit.py): `backend/app/security/audit.py`
- [Score Calculator](https://github.com/titarek/pagelens/blob/main/backend/app/metrics/scoring.py): `backend/app/metrics/scoring.py`
- [Report Schema](https://github.com/titarek/pagelens/blob/main/backend/app/schemas/report.py): `backend/app/schemas/report.py`
- [PDF Exporter](https://github.com/titarek/pagelens/blob/main/backend/app/services/pdf_exporter.py): `backend/app/services/pdf_exporter.py`

### Other components

- **Developer**
- **Target Website**

## Connections

- Developer → Analysis Form: submits URL (evidence: `frontend/src/pages/Home.tsx`)
- App Router → Analysis Form: routes to (evidence: `frontend/src/App.tsx`)
- App Router → Report View: routes to (evidence: `frontend/src/App.tsx`)
- Analysis Form → API Client: submits analysis (evidence: `frontend/src/pages/Home.tsx`)
- Report View → API Client: polls report (evidence: `frontend/src/pages/Report.tsx`)
- Report View → Report Widgets: renders findings (evidence: `frontend/src/pages/Report.tsx`)
- Report View → Source Inspector: renders source (evidence: `frontend/src/pages/Report.tsx`)
- Report View → Interactive Explorer: renders explorer (evidence: `frontend/src/pages/Report.tsx`)
- API Client → Analysis Routes: HTTP JSON (evidence: `README.md`)
- API Client → Report Routes: fetches reports (evidence: `README.md`)
- Analysis Routes → SSRF Guard: validates URL (evidence: `backend/app/api/routes_analyze.py`)
- Analysis Routes → Job Cache: stores job (evidence: `backend/app/api/routes_analyze.py`)
- Analysis Routes → Analysis Orchestrator: schedules analysis (evidence: `backend/app/api/routes_analyze.py`)
- Analysis Routes → Headless Renderer: simulates interaction (evidence: `backend/app/api/routes_analyze.py`)
- Report Routes → Job Cache: reads job (evidence: `backend/app/api/routes_report.py`)
- Report Routes → Report Schema: validates report (evidence: `backend/app/api/routes_report.py`)
- Report Routes → PDF Exporter: generates PDF (evidence: `backend/app/api/routes_report.py`)
- Analysis Orchestrator → HTTP Fetcher: fetches page (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → HTML Parser: parses HTML (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → CSS Collector: collects CSS (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → Headless Renderer: renders deep mode (evidence: `backend/app/services/analyzer.py`)
- HTTP Fetcher → Target Website: requests page (evidence: `README.md`)
- Headless Renderer → Target Website: renders page (evidence: `README.md`)
- Analysis Orchestrator → Structural Metrics: calculates structure (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → Rule Diagnostics: checks rules (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → Score Calculator: calculates score (evidence: `backend/app/services/analyzer.py`)
- Analysis Orchestrator → Security Audit: audits security (evidence: `backend/app/services/analyzer.py`)
- Headless Renderer → Timing Metrics: collects timings (evidence: `backend/app/renderer/playwright_runner.py`)
- Analysis Orchestrator → Report Schema: builds report (evidence: `backend/app/services/analyzer.py`)
- Score Calculator → Report Schema: sets score fields (evidence: `backend/app/metrics/scoring.py`)
- Structural Metrics → Report Schema: produces metrics (evidence: `backend/app/metrics/structural.py`)
- Rule Diagnostics → Report Schema: produces findings (evidence: `backend/app/metrics/shortcomings.py`)
- Security Audit → Report Schema: produces audit (evidence: `backend/app/security/audit.py`)
- Timing Metrics → Report Schema: produces timings (evidence: `backend/app/metrics/timing.py`)
