# banujanr29/website-audit-ai architecture

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

- Interactive diagram: https://gitdiagram.com/banujanr29/website-audit-ai
- Repository: https://github.com/banujanr29/website-audit-ai

## Overview

PagePulse AI is a single-page website auditing application. A user submits a URL through the Next.js interface; the backend fetches and parses the page, extracts factual metrics, calculates a score, and requests grounded insights and prioritized recommendations from Gemini. The frontend presents the combined report and exposes prompt logs. The README documents the full analysis stages; sampled source confirms the API entry point, frontend request hook, and Gemini request/parsing behavior. Some frontend rendering and backend orchestration links are documented rather than shown in excerpts.

Main entry points: [`frontend/app/page.tsx`](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/app/page.tsx) (Audit page), [`backend/src/main/java/com/eight25/audit/service/impl/AuditServiceImpl.java`](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/AuditServiceImpl.java) (Audit orchestration), [`frontend/services/api.ts`](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/services/api.ts) (API client), [`backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java`](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java) (Gemini integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Audit interface"]
  node_page["Audit page<br/>[page.tsx]"]
  node_form["Audit form<br/>[AuditForm.tsx]"]
  node_hook["Audit state hook<br/>[useAudit.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Audit API"]
  node_controller["Audit endpoint"]
  node_orchestrator["Audit orchestration"]
end

subgraph group_analysis["Page analysis"]
  node_scraper["Page fetcher"]
  node_extractor["Metrics extractor"]
  node_scorer["Score calculator"]
end

subgraph group_ai["AI analysis"]
  node_prompt["Prompt builder<br/>[PromptBuilder.java]"]
  node_gemini["Gemini integration"]
end

subgraph group_report["Audit report"]
  node_response["Audit response<br/>[AuditResponse.java]"]
  node_score_view["Score overview<br/>[ScoreOverview.tsx]"]
  node_metrics_view["Metrics grid<br/>[MetricsGrid.tsx]"]
  node_insights_view["AI insights<br/>[AIInsights.tsx]"]
  node_recommendations_view["Recommendations"]
  node_prompt_logs["Prompt transparency"]
end

node_user(("Website owner"))
node_api_actor(("Browser client"))
node_target(("Target website"))
node_gemini_api(("Google Gemini"))

node_user -->|"enters URL"| node_form
node_form -.->|"submits URL"| node_hook
node_hook -->|"posts audit"| node_api_client
node_api_client -.->|"sends REST request"| node_api_actor
node_api_actor -->|"POST /api/audit"| node_controller
node_controller -->|"calls audit"| node_orchestrator
node_orchestrator -->|"fetches page"| node_scraper
node_scraper -->|"fetches HTML"| node_target
node_orchestrator -->|"extracts metrics"| node_extractor
node_orchestrator -->|"calculates score"| node_scorer
node_orchestrator -->|"requests insights"| node_gemini
node_gemini -->|"builds prompts"| node_prompt
node_gemini -->|"sends analysis"| node_gemini_api
node_orchestrator -->|"assembles report"| node_response
node_response -.->|"returns report"| node_api_client
node_api_client -.->|"provides result"| node_page
node_page -.->|"renders score"| node_score_view
node_page -.->|"renders metrics"| node_metrics_view
node_page -.->|"renders insights"| node_insights_view
node_page -.->|"renders recommendations"| node_recommendations_view
node_page -.->|"shows prompt logs"| node_prompt_logs

click node_page "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/app/page.tsx"
click node_form "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/AuditForm.tsx"
click node_hook "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/hooks/useAudit.ts"
click node_api_client "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/services/api.ts"
click node_controller "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/controller/AuditController.java"
click node_orchestrator "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/AuditServiceImpl.java"
click node_scraper "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/WebsiteScraperServiceImpl.java"
click node_extractor "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/MetricsExtractorServiceImpl.java"
click node_scorer "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/WebsiteScoreCalculatorImpl.java"
click node_prompt "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/PromptBuilder.java"
click node_gemini "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java"
click node_response "https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/dto/response/AuditResponse.java"
click node_score_view "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/ScoreOverview.tsx"
click node_metrics_view "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/MetricsGrid.tsx"
click node_insights_view "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/AIInsights.tsx"
click node_recommendations_view "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/Recommendations.tsx"
click node_prompt_logs "https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/DeveloperDrawer.tsx"

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_page,node_form,node_hook,node_api_client,node_api_actor toneBlue
class node_controller,node_orchestrator toneAmber
class node_scraper,node_extractor,node_scorer toneMint
class node_prompt,node_gemini toneRose
class node_response,node_score_view,node_metrics_view,node_insights_view,node_recommendations_view,node_prompt_logs,node_user,node_target,node_gemini_api toneIndigo
```

## Components

### Audit interface

- [Audit page](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Audit form](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/AuditForm.tsx): `frontend/components/audit/AuditForm.tsx`
- [Audit state hook](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/hooks/useAudit.ts): `frontend/hooks/useAudit.ts`
- [API client](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/services/api.ts): `frontend/services/api.ts`

### Audit API

- [Audit endpoint](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/controller/AuditController.java): `backend/src/main/java/com/eight25/audit/controller/AuditController.java`
- [Audit orchestration](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/AuditServiceImpl.java): `backend/src/main/java/com/eight25/audit/service/impl/AuditServiceImpl.java`

### Page analysis

- [Page fetcher](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/WebsiteScraperServiceImpl.java): `backend/src/main/java/com/eight25/audit/service/impl/WebsiteScraperServiceImpl.java`
- [Metrics extractor](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/MetricsExtractorServiceImpl.java): `backend/src/main/java/com/eight25/audit/service/impl/MetricsExtractorServiceImpl.java`
- [Score calculator](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/WebsiteScoreCalculatorImpl.java): `backend/src/main/java/com/eight25/audit/service/impl/WebsiteScoreCalculatorImpl.java`

### AI analysis

- [Prompt builder](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/PromptBuilder.java): `backend/src/main/java/com/eight25/audit/service/impl/PromptBuilder.java`
- [Gemini integration](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java): `backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java`

### Audit report

- [Audit response](https://github.com/banujanr29/website-audit-ai/blob/develop/backend/src/main/java/com/eight25/audit/dto/response/AuditResponse.java): `backend/src/main/java/com/eight25/audit/dto/response/AuditResponse.java`
- [Score overview](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/ScoreOverview.tsx): `frontend/components/audit/ScoreOverview.tsx`
- [Metrics grid](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/MetricsGrid.tsx): `frontend/components/audit/MetricsGrid.tsx`
- [AI insights](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/AIInsights.tsx): `frontend/components/audit/AIInsights.tsx`
- [Recommendations](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/Recommendations.tsx): `frontend/components/audit/Recommendations.tsx`
- [Prompt transparency](https://github.com/banujanr29/website-audit-ai/blob/develop/frontend/components/audit/DeveloperDrawer.tsx): `frontend/components/audit/DeveloperDrawer.tsx`

### Other components

- **Website owner**
- **Browser client**
- **Target website**
- **Google Gemini**

## Connections

- Website owner → Audit form: enters URL (evidence: `README.md`)
- Audit form → Audit state hook: submits URL
- Audit state hook → API client: posts audit (evidence: `frontend/hooks/useAudit.ts`)
- API client → Browser client: sends REST request
- Browser client → Audit endpoint: POST /api/audit (evidence: `README.md`)
- Audit endpoint → Audit orchestration: calls audit (evidence: `backend/src/main/java/com/eight25/audit/controller/AuditController.java`)
- Audit orchestration → Page fetcher: fetches page (evidence: `README.md`)
- Page fetcher → Target website: fetches HTML (evidence: `README.md`)
- Audit orchestration → Metrics extractor: extracts metrics (evidence: `README.md`)
- Audit orchestration → Score calculator: calculates score (evidence: `README.md`)
- Audit orchestration → Gemini integration: requests insights (evidence: `README.md`)
- Gemini integration → Prompt builder: builds prompts (evidence: `backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java`)
- Gemini integration → Google Gemini: sends analysis (evidence: `backend/src/main/java/com/eight25/audit/service/impl/GeminiServiceImpl.java`)
- Audit orchestration → Audit response: assembles report (evidence: `README.md`)
- Audit response → API client: returns report
- API client → Audit page: provides result
- Audit page → Score overview: renders score
- Audit page → Metrics grid: renders metrics
- Audit page → AI insights: renders insights
- Audit page → Recommendations: renders recommendations
- Audit page → Prompt transparency: shows prompt logs
