# ammaarreshi/gemini-search architecture

> Architecture diagram of the GitHub repository ammaarreshi/gemini-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ammaarreshi/gemini-search
- Repository: https://github.com/ammaarreshi/gemini-search

## Overview

##### Project Type & Purpose
- Gemini Search is a full-stack application that acts as a Perplexity-style search engine. It leverages Google’s Gemini 2.0 Flash API and Google Search API to provide AI-powered answers with real-time web search citations.
- The project has clearly separated client and server sides and includes database integration (likely to store queries, logs, user data, etc.), along with external API calls to Google services.

##### Analyzing the File Structure
- The top-level directories are divided into:
- client: Contains the frontend code using React, Vite, and TypeScript. It includes pages, components (both application-specific and a large number of reusable UI components), hooks, and utility functions.
- server: Contains backend code, which uses Express.js and TypeScript. Key files include index.ts (entry point), routes.ts (defining API routes), and environment setup (env.ts).
- db: Contains files for database initialization and schema definitions. A configuration file (drizzle.config.ts) is also present, suggesting the use of Drizzle ORM.
- Additional configuration files like vite.config.ts, postcss.config.js, tailwind.config.ts, and tsconfig.json reveal build and type-checking setups.

a. Frontend Layer:
- Client (React + Vite + TypeScript):
- Pages: Home, Search, etc.
- Reusable UI Components (buttons, forms, modals, etc. as seen in the UI subdirectory)
- Hooks and Libraries: Custom hooks, Gemini integration utilities (e.g., client/src/lib/gemini.ts)
- Interaction: Presents the UI, communicates with the backend via API calls.

b. Backend Layer:
- Server (Express.js + TypeScript):
- API Routes: Defined in routes.ts, handling search queries, interacting with the Gemini API, and processing follow-up questions.
- Server Initialization: In server/index.ts and configuration files.
- Environment Management: Uses server/env.ts for environment variables.

c. Database Layer:
- db folder:
- Schema Definitions and Connection: Managed in db/index.ts and db/schema.ts, likely used to persist query logs or user session data.
- ORM/Configuration: The drizzle.config.ts indicates usage of Drizzle ORM.

d. External Services & APIs:
- Google Gemini 2.0 Flash API: Critical for handling AI-powered answer generation.
- Google Search API: Pulls in real-time web search data and citations.

##### Relationships & Data Flow
- The client (frontend) sends search requests to the backend via defined API endpoints.
- The backend (Express server) processes these requests by:
- Communicating with the Google Gemini API to get AI responses.
- Possibly making calls to the Google Search API for fetching additional data and citations.
- Optionally reading from or storing data in the database.
- The results from the external APIs are then relayed back to the client for display.

##### Architectural Patterns & Principles
- Separation of Concerns: Clear division between the client (UI), server (business logic, API management), and database (data persistence).
- Modular Reusability: Extensive use of modular, reusable components in the client (e.g., UI component library) and clear separation in the backend routing.
- API-First Communication: The client-server interaction is based on well-defined API routes.
- External API Integration: Emphasizes integration with external services (Google Gemini and Search APIs) for AI response generation and web search.

##### Instructing the Principal Software Engineer
- Component with clear labels:
- Frontend: UI Components (pages, hooks, libraries), state management.
- Backend: API Routes, Processing Logic, Express Server.
- Database: DB connection, ORM usage.
- External APIs: Google Gemini API, Google Search API.
- Client sends search requests to the backend.
- Backend orchestrates responses between external APIs and database operations.
- Server relays processed responses back to the client.
- Optionally, incorporate deployment-specific details such as environment configuration and build scripts (Vite, Tailwind, etc.) if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_main["Client (React+Vite+TS)"]:::frontend
        FE_home["Home Page"]:::frontend
        FE_search["Search Page"]:::frontend
        FE_ui["UI Components"]:::frontend
        FE_hooks["Custom Hooks"]:::frontend
        FE_gemini["Gemini Integration"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE_main["Express Server (index.ts)"]:::backend
        BE_routes["API Routes (routes.ts)"]:::backend
        BE_env["Environment Config (env.ts)"]:::backend
        BE_config["Other Server Config (vite.ts)"]:::backend
    end

    %% Database Layer
    subgraph "Database Layer"
        DB_conn["DB Connection (index.ts)"]:::database
        DB_schema["Schema Definitions (schema.ts)"]:::database
        DB_orm["ORM Config (drizzle.config.ts)"]:::database
    end

    %% External Services
    subgraph "External Services"
        EX1["Google Gemini API"]:::external
        EX2["Google Search API"]:::external
    end

    %% Data Flows between Layers
    FE_main -->|"sends_search_request"| BE_main
    BE_main -->|"handles_routing"| BE_routes
    BE_main -->|"reads_env"| BE_env
    BE_main -->|"applies_config"| BE_config
    BE_main -->|"queries_DB"| DB_conn
    BE_main -->|"updates_schema"| DB_schema
    BE_main -->|"calls"| EX1
    BE_main -->|"calls"| EX2

    %% Additional internal Frontend connections
    FE_main --- FE_home
    FE_main --- FE_search
    FE_main --- FE_ui
    FE_main --- FE_hooks
    FE_hooks --- FE_gemini

    %% Click Events for Frontend Layer
    click FE_main "https://github.com/ammaarreshi/gemini-search/tree/main/client/"
    click FE_home "https://github.com/ammaarreshi/gemini-search/blob/main/client/src/pages/Home.tsx"
    click FE_search "https://github.com/ammaarreshi/gemini-search/blob/main/client/src/pages/Search.tsx"
    click FE_ui "https://github.com/ammaarreshi/gemini-search/tree/main/client/src/components/"
    click FE_hooks "https://github.com/ammaarreshi/gemini-search/tree/main/client/src/hooks/"
    click FE_gemini "https://github.com/ammaarreshi/gemini-search/blob/main/client/src/lib/gemini.ts"

    %% Click Events for Backend Layer
    click BE_main "https://github.com/ammaarreshi/gemini-search/blob/main/server/index.ts"
    click BE_routes "https://github.com/ammaarreshi/gemini-search/blob/main/server/routes.ts"
    click BE_env "https://github.com/ammaarreshi/gemini-search/blob/main/server/env.ts"
    click BE_config "https://github.com/ammaarreshi/gemini-search/blob/main/server/vite.ts"

    %% Click Events for Database Layer
    click DB_conn "https://github.com/ammaarreshi/gemini-search/blob/main/db/index.ts"
    click DB_schema "https://github.com/ammaarreshi/gemini-search/blob/main/db/schema.ts"
    click DB_orm "https://github.com/ammaarreshi/gemini-search/blob/main/drizzle.config.ts"

    %% Styles
    classDef frontend fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef database fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
