# mckaywrigley/clarity-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mckaywrigley/clarity-ai
- Repository: https://github.com/mckaywrigley/clarity-ai

## Overview

##### Project type and purpose
- This is a full‐stack Next.js application (React + serverless API routes) that mimics Perplexity.ai by scraping the web, building a prompt, and calling OpenAI to generate answers.
- The README makes clear it’s a “Perplexity.ai clone” that:
1. Accepts a user query
2. Scrapes Google results
3. Parses webpage text
4. Builds an LLM prompt
5. Calls OpenAI’s API
6. Streams the answer back to the user

##### File structure
- Top-level directories and files:
- pages/ – Next.js page components and API routes
– pages/index.tsx (UI)
– pages/api/answer.ts & pages/api/sources.ts (serverless endpoints)
- components/ – React UI pieces (Search, Answer)
- utils/ – business logic modules (scraping, prompt building)
- types/ – TypeScript interfaces
- public/, styles/, tailwind.config.js – static assets & styling
- next.config.js, tsconfig.json, PostCSS, ESLint – framework & build configs
- There is no persistent database; all data flows through in-memory scraping and OpenAI calls.

##### README for additional insights
- Describes the end-to-end flow (scrape → parse → prompt → OpenAI).

a. Main components:
- Client (Browser UI)
- Next.js Frontend (React + Tailwind in pages/index.tsx & components/)
- Next.js API Server (Serverless functions in pages/api/)
- Scraper Module (utils/sources.ts)
- Parser Module (utils/answer.ts)
- Prompt Builder & LLM Gateway (utils/answer.ts calling OpenAI)
- External Services: Google Search (scraping), OpenAI API
- Hosting/Infra: Vercel (Next.js runtime)
b. Relationships & interactions:
1. User enters query in the Search component →
2. Frontend calls /api/sources to retrieve links (Scraper Module calls Google via HTTP, parses HTML) →
3. Frontend displays sources (optional) →
4. User requests an answer → Frontend calls /api/answer →
5. API handler orchestrates: calls Scraper → Parser → Prompt Builder → OpenAI API → streams tokens back →
6. Frontend renders incremental Answer component updates
c. Architectural patterns and design principles:
- Serverless functions for backend logic (no monolithic server)
- Separation of concerns: UI (components) vs. data-fetching (pages/api) vs. business logic (utils/)
- Streaming response pattern for LLM output
- Utility modules abstracting scraping/parsing to stay framework-agnostic
d. Relevant technologies/frameworks:
- Next.js (SSR/SSG + API routes)
- React + Tailwind CSS (UI styling)
- Node.js + Cheerio or similar for web scraping
- OpenAI API (text-davinci-003 or streaming models)
- TypeScript for type safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Vercel Hosting"
        direction TB

        subgraph "Frontend"
            direction TB
            Browser["Browser"]:::external
            UI["pages/index.tsx"]:::frontend
            SearchComp["components/Search.tsx"]:::frontend
            AnswerComp["components/Answer.tsx"]:::frontend
            AppWrapper["pages/_app.tsx"]:::frontend
            Document["pages/_document.tsx"]:::frontend
        end

        subgraph "Backend (Serverless Functions)"
            direction TB
            SourcesAPI["pages/api/sources.ts"]:::backend
            AnswerAPI["pages/api/answer.ts"]:::backend
        end

        subgraph "Business Logic (utils)"
            direction TB
            Scraper["utils/sources.ts"]:::utils
            ParserPrompt["utils/answer.ts"]:::utils
        end

        subgraph "Config & Types"
            direction TB
            Types["types/index.ts"]:::config
            Styles["styles/globals.css"]:::config
            Tailwind["tailwind.config.js"]:::config
            NextConfig["next.config.js"]:::config
        end

        subgraph "External Services"
            direction TB
            Google["Google Search"]:::external
            OpenAI["OpenAI API"]:::external
        end
    end

    %% User flow: search sources
    Browser --> UI
    UI --> SearchComp
    SearchComp -->|"1. query sources"| SourcesAPI
    SourcesAPI --> Scraper
    Scraper --> Google
    Google --> Scraper
    Scraper --> SourcesAPI
    SourcesAPI -->|2. return links| UI

    %% User flow: generate answer
    UI --> AnswerComp
    AnswerComp -->|"3. request answer"| AnswerAPI
    AnswerAPI --> Scraper
    AnswerAPI --> ParserPrompt
    ParserPrompt --> OpenAI
    OpenAI -->|stream tokens| AnswerAPI
    AnswerAPI -->|streaming response| AnswerComp

    %% Config & Types usage
    UI --> Types
    UI --> Styles
    UI --> Tailwind
    UI --> NextConfig
    UI --> AppWrapper
    UI --> Document

    %% Click Events
    click UI "https://github.com/mckaywrigley/clarity-ai/blob/main/pages/index.tsx"
    click SearchComp "https://github.com/mckaywrigley/clarity-ai/blob/main/components/Search.tsx"
    click AnswerComp "https://github.com/mckaywrigley/clarity-ai/blob/main/components/Answer.tsx"
    click SourcesAPI "https://github.com/mckaywrigley/clarity-ai/blob/main/pages/api/sources.ts"
    click AnswerAPI "https://github.com/mckaywrigley/clarity-ai/blob/main/pages/api/answer.ts"
    click Scraper "https://github.com/mckaywrigley/clarity-ai/blob/main/utils/sources.ts"
    click ParserPrompt "https://github.com/mckaywrigley/clarity-ai/blob/main/utils/answer.ts"
    click Types "https://github.com/mckaywrigley/clarity-ai/blob/main/types/index.ts"
    click Styles "https://github.com/mckaywrigley/clarity-ai/blob/main/styles/globals.css"
    click Tailwind "https://github.com/mckaywrigley/clarity-ai/blob/main/tailwind.config.js"
    click NextConfig "https://github.com/mckaywrigley/clarity-ai/blob/main/next.config.js"
    click AppWrapper "https://github.com/mckaywrigley/clarity-ai/blob/main/pages/_app.tsx"
    click Document "https://github.com/mckaywrigley/clarity-ai/blob/main/pages/_document.tsx"

    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#28a745,stroke-width:1px
    classDef utils fill:#F0D9FF,stroke:#6f42c1,stroke-width:1px
    classDef external fill:#FFF4D6,stroke:#d08b02,stroke-width:1px
    classDef config fill:#E8E8E8,stroke:#6a737d,stroke-width:1px
```
