How rangonroyutsab/getsetseo works
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: scoring.ts Scoring · route.ts Audit API · scraper.ts Scraper · types.ts Types
Components 13
UI
Landing page and audit dashboard
- Landing · URL entry surface for starting an audit
src/app/page.tsx - Dashboard · Audit results view with scores, filters, and issues
src/app/audit/page.tsx - Score Ring · Visual summary of overall audit score
src/components/audit/ScoreRing.tsx - Issue Card · Expandable issue display with evidence snippets
src/components/audit/IssueCard.tsx
Backend
API orchestration and audit execution
- Audit API · Validates input and orchestrates the audit pipeline
src/app/api/audit/route.ts
SEO Engine
Scraping, analysis, rules, and scoring
- Scraper · Loads pages in Chromium and extracts rendered HTML
src/lib/seo/scraper.ts - On-page Rules · Title, description, H1, and heading structure checks
src/lib/seo/rules/onPage.ts - Technical Rules · Canonical, language, and robots-related checks
src/lib/seo/rules/technical.ts - Content Rules · Image alt text, link text, and link validity checks
src/lib/seo/rules/content.ts - Social Rules · Open Graph, Twitter Card, and schema checks
src/lib/seo/rules/social.ts - Scoring · Turns rule results into category and overall scores
src/lib/seo/scoring.ts - PageSpeed PSI · Adds performance data when an API key is available
src/lib/seo/psi.ts
Shared
Types and contracts
- Types · Typed request and response structures with validation
src/lib/types.ts
Connections 18
- 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