# hackice20/perplexity-clone architecture

> Architecture diagram of the GitHub repository hackice20/perplexity-clone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hackice20/perplexity-clone
- Repository: https://github.com/hackice20/perplexity-clone

## Overview

##### Main components

- Backend (Node.js/Express):
- Server (backend/src/server.js): Handles incoming API requests.
- AI Module (backend/src/ai.js): Interfaces with the Llama-3.3 AI model, likely hosted externally on Groq.
- Search Module (backend/src/search.js): Manages interactions with the Google Custom Search JSON API.
- Environment Configuration (backend/src/env.js) and .env.example: Manages application’s environment settings.

- Frontend (React/TypeScript):
- Main Application (frontend/src/App.tsx and frontend/src/main.tsx): Serves as the entry point and high-level component of the user interface.
- UI Components (e.g., SearchInput, SearchResults, Tooltip under frontend/src/components and its subdirectories): Handle user interactions and display results.
- Project Configuration and Styling: Files such as tailwind.config.js, vite.config.ts, and postcss.config.js indicating the use of Tailwind CSS and Vite for build and bundling.

##### Relationships and interactions

- Data Flow:
- The user interacts with the frontend UI. Actions (such as typing a query into the SearchInput component) trigger API calls.
- These API calls are directed to the backend server (Express) endpoints.
- The backend server uses the AI module to process the query with the Llama-3.3 model and the Search module to obtain results from the Google Custom Search API.
- Once processed, the backend sends the consolidated results back to the frontend, where components such as SearchResults display the output.

- External Services:
- External communication links from the backend to:
- The Llama-3.3 AI service (hosted on Groq).
- The Google Custom Search JSON API.

##### Important architectural patterns and design principles

- Separation of Concerns:
- Distinct division between frontend and backend responsibilities.
- Within the backend, separation into modules (AI, search, environment configuration) that encapsulate specific functionalities.

- API-driven Communication:
- RESTful API endpoints that bridge the frontend and backend.

- Modular, Component-based Frontend:
- React component hierarchy, depicting the relationship between the main application and its subcomponents.

##### Relevant technologies and frameworks

- Backend:
- Node.js, Express.js
- Use of configuration via environment variables (.env)

- Frontend:
- React and TypeScript for UI and type safety
- Tailwind CSS for styling
- Vite for development/build tooling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Section
    subgraph "Frontend (React/TypeScript)"
        U["User"]:::frontend
        F1["Main Application (App & main.tsx)"]:::frontend
        SI["SearchInput Component"]:::frontend
        SR["SearchResults Component"]:::frontend
        TT["Tooltip Component"]:::frontend
        FCONFIG["Build & Styling Config"]:::config
    end

    %% Backend Section
    subgraph "Backend (Node.js/Express)"
        BE["Express Server"]:::backend
        AIM["AI Module"]:::backend
        SM["Search Module"]:::backend
        CONF["Environment Configuration"]:::backend
        AIEXT["Llama-3.3 AI Service (Groq)"]:::external
        GS["Google Custom Search API"]:::external
    end

    %% Data Flow: Frontend to Backend and Back
    U -->|"initiatesSearch"| SI
    SI -->|"sendsAPIRequest"| BE
    BE -->|"delegatesToAI"| AIM
    BE -->|"delegatesToSearch"| SM
    BE --> CONF
    AIM -->|"callsAI"| AIEXT
    SM -->|"callsSearch"| GS
    BE -->|"returnsAggregatedResponse"| F1
    F1 -->|"rendersResults"| SR
    F1 -->|"displaysTooltip"| TT
    F1 -->|"configuredBy"| FCONFIG

    %% Styles
    classDef backend fill:#ffe6cc,stroke:#ff9900,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#999999,stroke-width:2px;
    classDef config fill:#e6ccff,stroke:#a64ca6,stroke-width:2px;

    %% Click Events for Backend Components
    click BE "https://github.com/hackice20/perplexity-clone/blob/main/backend/src/server.js"
    click AIM "https://github.com/hackice20/perplexity-clone/blob/main/backend/src/ai.js"
    click SM "https://github.com/hackice20/perplexity-clone/blob/main/backend/src/search.js"
    click CONF "https://github.com/hackice20/perplexity-clone/blob/main/backend/src/env.js"
    click CONF "https://github.com/hackice20/perplexity-clone/blob/main/backend/.env.example"

    %% Click Events for Frontend Components
    click F1 "https://github.com/hackice20/perplexity-clone/blob/main/frontend/src/main.tsx"
    click F1 "https://github.com/hackice20/perplexity-clone/blob/main/frontend/src/App.tsx"
    click SI "https://github.com/hackice20/perplexity-clone/blob/main/frontend/src/components/SearchInput.tsx"
    click SR "https://github.com/hackice20/perplexity-clone/blob/main/frontend/src/components/SearchResults.tsx"
    click TT "https://github.com/hackice20/perplexity-clone/blob/main/frontend/src/components/ui/Tooltip.tsx"
    click FCONFIG "https://github.com/hackice20/perplexity-clone/blob/main/frontend/tailwind.config.js"
    click FCONFIG "https://github.com/hackice20/perplexity-clone/blob/main/frontend/vite.config.ts"
    click FCONFIG "https://github.com/hackice20/perplexity-clone/blob/main/frontend/postcss.config.js"
```
