# filiksyos/ai-reddit-search architecture

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

- Interactive diagram: https://gitdiagram.com/filiksyos/ai-reddit-search
- Repository: https://github.com/filiksyos/ai-reddit-search

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered search application built on Next.js 14 (App Router) with TypeScript and Tailwind CSS.
- It provides a user interface for entering natural language queries, enhances them via Google’s Gemini 2.0 Flash through OpenRouter, and then performs optimized Reddit searches, displaying the results in real time.

##### File Structure
- Top-level config and metadata:
- `.env.local.example`, `next.config.js`, `package.json`, `pnpm-workspace.yaml`, `tsconfig.json`
- src/app (Next.js App Router)
- `/api/enhance-query/route.ts` – serverless API route for AI query enhancement
- `layout.tsx`, `page.tsx` – root layout and home page component
- `globals.css` – global Tailwind styles
- src/components
- providers/theme-provider.tsx – UI context provider
- ui/{search-bar.tsx, filter-bar.tsx, post-card.tsx} – core presentational components
- src/hooks
- `useRedditSearch.ts` – custom hook using SWR for calling the Reddit API
- src/lib
- `client-openrouter.ts` – client-side wrapper for AI calls
- `openrouter-api.ts` – server-side AI service implementation
- `reddit-api.ts` – wrapper around Reddit’s OAuth-authenticated search
- `types.ts` and `utils.ts` – shared TypeScript types and helpers

##### Extract Key Architectural Insights from the README
- Emphasis on server-side AI calls (keeps API key hidden), client-side query throttling (debouncing), and SWR caching for performance.

##### Detail Without Over-Complication
- Every major component and interaction: UI, data fetching hooks, API routes, AI service, external API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js + React)" 
        direction TB
        Layout["Root Layout"]:::frontend
        Page["Home Page"]:::frontend
        ThemeProvider["Theme Provider"]:::frontend
        SearchBar["Search Bar UI"]:::frontend
        FilterBar["Filter Bar UI"]:::frontend
        PostCard["Post Card UI"]:::frontend
        UseReddit["useRedditSearch Hook"]:::frontend
        Styles["Global Styles"]:::frontend
    end

    %% Backend / API Layer
    subgraph "Backend (Next.js Serverless)"
        direction TB
        EnhanceAPI["/api/enhance-query"]:::backend
        OpenRouterAPI["OpenRouter API Impl"]:::backend
        RedditAPIWrapper["Reddit API Wrapper"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenRouterService["OpenRouter ↔ Gemini 2.0"]:::ai
        RedditService["Reddit API (OAuth)"]:::external
    end

    %% Data Flow
    User -->|interacts| Layout
    Layout --> Page
    Page --> ThemeProvider
    Page --> SearchBar
    Page --> FilterBar
    SearchBar -->|debounced query| UseReddit
    SearchBar -->|HTTP/JSON POST| EnhanceAPI
    EnhanceAPI -->|calls| OpenRouterAPI
    OpenRouterAPI -->|HTTP/JSON| OpenRouterService
    OpenRouterService -->|enhanced query| OpenRouterAPI
    OpenRouterAPI -->|JSON response| EnhanceAPI
    EnhanceAPI -->|enhanced query| UseReddit
    UseReddit -->|calls| RedditAPIWrapper
    RedditAPIWrapper -->|HTTP/JSON| RedditService
    RedditService -->|posts data| RedditAPIWrapper
    RedditAPIWrapper -->|data| UseReddit
    UseReddit -->|returns posts| PostCard

    %% Static Assets
    Layout --> Styles

    %% Click Events
    click Layout "https://github.com/filiksyos/ai-reddit-search/blob/master/src/app/layout.tsx"
    click Page "https://github.com/filiksyos/ai-reddit-search/blob/master/src/app/page.tsx"
    click Styles "https://github.com/filiksyos/ai-reddit-search/blob/master/src/app/globals.css"
    click EnhanceAPI "https://github.com/filiksyos/ai-reddit-search/blob/master/src/app/api/enhance-query/route.ts"
    click SearchBar "https://github.com/filiksyos/ai-reddit-search/blob/master/src/components/ui/search-bar.tsx"
    click FilterBar "https://github.com/filiksyos/ai-reddit-search/blob/master/src/components/ui/filter-bar.tsx"
    click PostCard "https://github.com/filiksyos/ai-reddit-search/blob/master/src/components/ui/post-card.tsx"
    click ThemeProvider "https://github.com/filiksyos/ai-reddit-search/blob/master/src/components/providers/theme-provider.tsx"
    click UseReddit "https://github.com/filiksyos/ai-reddit-search/blob/master/src/hooks/useRedditSearch.ts"
    click OpenRouterAPI "https://github.com/filiksyos/ai-reddit-search/blob/master/src/lib/openrouter-api.ts"
    click RedditAPIWrapper "https://github.com/filiksyos/ai-reddit-search/blob/master/src/lib/reddit-api.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#C8F8D0,stroke:#333,stroke-width:1px
    classDef ai fill:#FFE4B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0C8FF,stroke:#333,stroke-width:1px
```
