# rangonroyutsab/getsetseo architecture

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

- Interactive diagram: https://gitdiagram.com/rangonroyutsab/getsetseo
- Repository: https://github.com/rangonroyutsab/getsetseo

## Overview

1. **Overall shape**
   - This is a single-app Next.js project with one primary backend entrypoint and a client-facing audit dashboard.
   - The architecture is centered on a **URL audit pipeline**: user submits a site URL, the server renders and inspects the page, modular SEO rules run, scores are calculated, and the result is returned to the UI.

2. **User-facing surfaces**
   - `src/app/page.tsx` is the landing page where users enter a target URL.
   - `src/app/audit/page.tsx` is the results dashboard, showing the overall score, category breakdowns, and filtered issue lists.
   - `src/components/audit/ScoreRing.tsx` and `IssueCard.tsx` are the main presentation primitives for the audit results.

3. **Backend boundary**
   - The only backend API is `src/app/api/audit/route.ts`, a POST endpoint that receives the URL to audit.
   - This route is the orchestration layer: it validates input, invokes scraping, runs rule checks, aggregates scores, and returns a typed JSON payload to the client.
   - That separation is the key architectural boundary: **UI concerns stay in the App Router pages/components; audit computation stays in the API route and `lib/seo`**.

4. **Scraping and page extraction**
   - `src/lib/seo/scraper.ts` is responsible for loading the target website in a headless Chromium browser via Playwright.
   - Its job is to capture the **fully rendered DOM**, which matters for JavaScript-heavy sites and SPAs.
   - The scraped HTML is then passed into the analysis layer, where parsing is handled with Cheerio rather than directly through the browser context.

5. **Analysis engine and modular rules**
   - SEO checks are split into four rule groups under `src/lib/seo/rules/`:
     - `onPage.ts` for title, meta description, H1, and heading hierarchy checks
     - `technical.ts` for canonical, lang, and robots-related checks
     - `content.ts` for image alt text, link text, and link validity checks
     - `social.ts` for Open Graph, Twitter Card, and JSON-LD/schema checks
   - This makes the audit logic composable and category-oriented, which is useful for both scoring and UI grouping.

6. **Scoring layer**
   - `src/lib/seo/scoring.ts` turns raw rule results into weighted category and overall scores.
   - The dashboard’s score ring and summary stats are driven by this scoring output, not by ad hoc UI calculations.
   - This gives the app a clear separation between **finding issues** and **deciding how much they matter**.

7. **Optional external enrichment**
   - `src/lib/seo/psi.ts` integrates with Google PageSpeed Insights when an API key is present.
   - This is an optional external dependency rather than a core requirement, so the architecture treats it as additive data that can enrich the audit with performance metrics without blocking the main SEO analysis path.

8. **Shared types and validation**
   - `src/lib/types.ts` defines the typed contract for request and response data, with Zod used for validation and structure.
   - This is important because the API response feeds a complex dashboard with filters, sections, and issue cards; strongly typed payloads reduce drift between backend analysis and frontend rendering.

9. **Result presentation and interaction**
   - The dashboard is designed around **issue severity and discoverability**:
     - global filters for Passed / Warnings / Failed
     - per-category drilldown
     - expandable issue cards with snippets of offending HTML
   - The screenshot-driven UX implies the client consumes the audit response as a structured tree of categories, rules, counts, and evidence snippets.

10. **Error-handling path**
   - The audit pipeline is built to fail gracefully on invalid domains, timeouts, and blocked sites.
   - Instead of crashing the server or partially rendering broken data, the API returns a failure state that the UI can present as an “Audit Failed” view.
   - This is an important architectural trait because the scraper is the highest-risk component in the system.

11. **Runtime and framework choices that matter**
   - Next.js App Router drives both routing and server-side API handling.
   - Playwright Chromium is the critical runtime dependency for rendering modern sites before analysis.
   - Cheerio is used for lightweight DOM traversal once HTML has been captured.
   - Tailwind CSS shapes the dashboard presentation, but it does not affect the core data flow.

12. **End-to-end data flow**
   - Input URL enters the landing page.
   - The POST `/api/audit` route normalizes and validates it.
   - Playwright loads the page and extracts rendered HTML.
   - Cheerio parses the HTML.
   - Modular rule files evaluate SEO checks.
   - Scoring aggregates findings and optional PSI data.
   - The typed response is rendered by the audit dashboard and interactive components.

13. **Primary architectural takeaway**
   - This repo is best understood as a **server-mediated SEO inspection pipeline with a rich client dashboard**, not as a generic content site.
   - The main boundaries are:
     - UI vs audit backend
     - scraping vs parsing vs rule evaluation
     - issue detection vs scoring vs presentation

Main entry points: [`src/lib/seo/scoring.ts`](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scoring.ts) (Scoring), [`src/app/api/audit/route.ts`](https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/api/audit/route.ts) (Audit API), [`src/lib/seo/scraper.ts`](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scraper.ts) (Scraper), [`src/lib/types.ts`](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/types.ts) (Types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_landing["Landing<br/>Next page<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>Next page<br/>[page.tsx]"]
  node_score_ring(("Score Ring<br/>UI component<br/>[ScoreRing.tsx]"))
  node_issue_card["Issue Card<br/>UI component<br/>[IssueCard.tsx]"]
end

subgraph group_backend["Backend"]
  node_audit_route["Audit API<br/>Route handler<br/>[route.ts]"]
end

subgraph group_seo["SEO Engine"]
  node_scraper["Scraper<br/>Playwright capture<br/>[scraper.ts]"]
  node_onpage_rules["On-page Rules<br/>SEO checks<br/>[onPage.ts]"]
  node_technical_rules["Technical Rules<br/>SEO checks<br/>[technical.ts]"]
  node_content_rules["Content Rules<br/>SEO checks<br/>[content.ts]"]
  node_social_rules["Social Rules<br/>SEO checks<br/>[social.ts]"]
  node_scoring["Scoring<br/>Weighting engine<br/>[scoring.ts]"]
  node_psi["PageSpeed PSI<br/>Optional enrichment<br/>[psi.ts]"]
end

subgraph group_shared["Shared"]
  node_types["Types<br/>Contract schema<br/>[types.ts]"]
end

node_landing -->|"submit URL"| node_audit_route
node_audit_route -->|"validate"| node_types
node_audit_route -->|"render page"| node_scraper
node_scraper -->|"HTML"| node_onpage_rules
node_scraper -->|"HTML"| node_technical_rules
node_scraper -->|"HTML"| node_content_rules
node_scraper -->|"HTML"| node_social_rules
node_onpage_rules -->|"findings"| node_scoring
node_technical_rules -->|"findings"| node_scoring
node_content_rules -->|"findings"| node_scoring
node_social_rules -->|"findings"| node_scoring
node_audit_route -.->|"enrich"| node_psi
node_psi -.->|"metrics"| node_scoring
node_audit_route -->|"result"| node_dashboard
node_scoring -->|"scores"| node_dashboard
node_types -->|"shape data"| node_dashboard
node_types -->|"score model"| node_score_ring
node_types -->|"issue model"| node_issue_card

click node_landing "https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/page.tsx"
click node_dashboard "https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/audit/page.tsx"
click node_score_ring "https://github.com/rangonroyutsab/getsetseo/blob/main/src/components/audit/ScoreRing.tsx"
click node_issue_card "https://github.com/rangonroyutsab/getsetseo/blob/main/src/components/audit/IssueCard.tsx"
click node_audit_route "https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/api/audit/route.ts"
click node_scraper "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scraper.ts"
click node_onpage_rules "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/onPage.ts"
click node_technical_rules "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/technical.ts"
click node_content_rules "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/content.ts"
click node_social_rules "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/social.ts"
click node_scoring "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scoring.ts"
click node_psi "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/psi.ts"
click node_types "https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/types.ts"

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_landing,node_dashboard,node_score_ring,node_issue_card toneBlue
class node_audit_route toneAmber
class node_scraper,node_onpage_rules,node_technical_rules,node_content_rules,node_social_rules,node_scoring,node_psi toneMint
class node_types toneRose
```

## Components

### UI

Landing page and audit dashboard

- [Landing](https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/page.tsx): Next page · URL entry surface for starting an audit · `src/app/page.tsx`
- [Dashboard](https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/audit/page.tsx): Next page · Audit results view with scores, filters, and issues · `src/app/audit/page.tsx`
- [Score Ring](https://github.com/rangonroyutsab/getsetseo/blob/main/src/components/audit/ScoreRing.tsx): UI component · Visual summary of overall audit score · `src/components/audit/ScoreRing.tsx`
- [Issue Card](https://github.com/rangonroyutsab/getsetseo/blob/main/src/components/audit/IssueCard.tsx): UI component · Expandable issue display with evidence snippets · `src/components/audit/IssueCard.tsx`

### Backend

API orchestration and audit execution

- [Audit API](https://github.com/rangonroyutsab/getsetseo/blob/main/src/app/api/audit/route.ts): Route handler · Validates input and orchestrates the audit pipeline · `src/app/api/audit/route.ts`

### SEO Engine

Scraping, analysis, rules, and scoring

- [Scraper](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scraper.ts): Playwright capture · Loads pages in Chromium and extracts rendered HTML · `src/lib/seo/scraper.ts`
- [On-page Rules](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/onPage.ts): SEO checks · Title, description, H1, and heading structure checks · `src/lib/seo/rules/onPage.ts`
- [Technical Rules](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/technical.ts): SEO checks · Canonical, language, and robots-related checks · `src/lib/seo/rules/technical.ts`
- [Content Rules](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/content.ts): SEO checks · Image alt text, link text, and link validity checks · `src/lib/seo/rules/content.ts`
- [Social Rules](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/rules/social.ts): SEO checks · Open Graph, Twitter Card, and schema checks · `src/lib/seo/rules/social.ts`
- [Scoring](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/scoring.ts): Weighting engine · Turns rule results into category and overall scores · `src/lib/seo/scoring.ts`
- [PageSpeed PSI](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/seo/psi.ts): Optional enrichment · Adds performance data when an API key is available · `src/lib/seo/psi.ts`

### Shared

Types and contracts

- [Types](https://github.com/rangonroyutsab/getsetseo/blob/main/src/lib/types.ts): Contract schema · Typed request and response structures with validation · `src/lib/types.ts`

## Connections

- Landing → Audit API: submit URL · User starts an audit from the landing page
- Audit API → Types: validate · Request and response shapes are enforced through shared types
- Audit API → Scraper: render page · The route loads the target site and captures rendered HTML
- Scraper → On-page Rules: HTML · Rendered markup is analyzed by modular rules
- Scraper → Technical Rules: HTML · Rendered markup is analyzed by modular rules
- Scraper → Content Rules: HTML · Rendered markup is analyzed by modular rules
- Scraper → Social Rules: HTML · Rendered markup is analyzed by modular rules
- On-page Rules → Scoring: findings · Rule outcomes are converted into weighted scores
- Technical Rules → Scoring: findings · Rule outcomes are converted into weighted scores
- Content Rules → Scoring: findings · Rule outcomes are converted into weighted scores
- Social Rules → Scoring: findings · Rule outcomes are converted into weighted scores
- Audit API → PageSpeed PSI: enrich · Optional PageSpeed data is added when configured
- PageSpeed PSI → Scoring: metrics · External performance data can contribute to the audit result
- Audit API → Dashboard: result · Typed audit payload is returned to the client UI
- Scoring → Dashboard: scores · Overall and category scores drive the dashboard
- Types → Dashboard: shape data · Client rendering depends on shared response structure
- Types → Score Ring: score model · Score visualization consumes the typed audit model
- Types → Issue Card: issue model · Issue cards render structured findings and evidence
