# sakshamagarwalm2/synthia architecture

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

- Interactive diagram: https://gitdiagram.com/sakshamagarwalm2/synthia
- Repository: https://github.com/sakshamagarwalm2/synthia

## Overview

##### Project Type and Purpose
- Synthia is a full-stack AI-driven web application built with Next.js (App Router). It offers intelligent search and research capabilities by integrating multiple external services (Google Custom Search, Gemini AI) and a managed backend (Supabase, Clerk, Inngest).

##### File Structure Analysis
- Top-level folders:
- app/ – Next.js routes and React server/client components.
- components/ – Reusable UI primitives (Shadcn UI + Radix UI wrappers).
- context/, hooks/ – React context providers and custom hooks.
- api routes under app/api/ – Next.js serverless functions.
- inngest/ – Inngest client and functions for background jobs.
- Services/ – External service configuration (Supabase client).
- lib/ – Helper utilities.
- Configuration: next.config.mjs, tsconfig.json, middleware.js for Clerk auth.

##### Key Insights from README
- Frontend: Next.js + Tailwind + Shadcn UI + Lucide React + Radix UI components.
- Authentication: Clerk.
- Database: Supabase (Users, Librery, Chats tables).
- Asynchronous tasks: Inngest triggered by /api/llm-model to generate AI summaries.
- External APIs: Google Custom Search for search results; Gemini AI for summarization.

##### Main Components
a. Client (Browser)
- UI pages (Home, Search Results, Library, Discover)
- Shared components (AppSidebar, ChatInputBox, CreditPopup, Tabs)
b. Next.js Application
- App Router (app/ pages + layout)
- API Routes:
- /api/search-api → Google Custom Search
- /api/llm-model → Gemini AI + Inngest trigger
- /api/inngest → Inngest webhook handler
- /api/get-inngest-status → Poll job status
- Middleware: Clerk authentication guard
c. Backend Services
- Supabase (PostgreSQL):
- Users table (authentication, credits)
- Librery table (search sessions)
- Chats table (search results, AI responses)
- Inngest Serverless Functions: background processing of AI responses
d. External APIs
- Google Custom Search API
- Gemini AI API (summarization)
- Clerk (Auth as a Service)

##### Relationships and Data Flows
1. User interacts with UI in Browser → sends requests to Next.js front end.
2. On search submission:
- Next.js API /api/search-api calls Google Custom Search → returns raw search results.
- Results are saved to Supabase.Chats and Librery (if authenticated).
- Next.js API /api/llm-model triggers an Inngest job with search data → Inngest calls Gemini AI → writes AI summary back to Supabase.Chats.
- Frontend polls /api/get-inngest-status to receive updated AI summary in real time.
3. UI reads data from Supabase via direct fetches in server components or via client SDK (supabase.jsx).
4. Auth flow: Clerk middleware ensures protected routes are only accessible to logged-in users; guest users have limited functionality.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- UI layer (React components)
- API layer (Next.js serverless functions)
- Data layer (Supabase)
- Background processing (Inngest)
- Event-Driven Asynchrony: Inngest functions decouple AI summarization from synchronous request flow.
- Contextual State Management: React Context for user details, custom hooks for responsive behavior.
- Modular Component Architecture: Shadcn UI + Radix UI primitives, local _components vs shared components.

##### Final Advice
- Every path: user authentication → search → storage → AI summarization → real-time update.
- Don’t overcomplicate – show each major component and its interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Zone
    subgraph "Client (Browser)" 
        direction TB
        Home["Home Page"]:::frontend
        Discover["Discover Page"]:::frontend
        Library["Library Page"]:::frontend
        SearchResults["Search Results Page"]:::frontend
        AppSidebar["App Sidebar"]:::frontend
        ChatInputBox["Chat Input Box"]:::frontend
        CreditPopup["Credit Popup"]:::frontend
        Tabs["Tabs"]:::frontend

        Home -->|uses| AppSidebar
        Discover -->|uses| AppSidebar
        Library -->|uses| AppSidebar
        SearchResults -->|uses| AppSidebar
        SearchResults -->|uses| ChatInputBox
        SearchResults -->|uses| CreditPopup
        SearchResults -->|uses| Tabs
    end

    %% Next.js Application Zone
    subgraph "Next.js Application" 
        direction TB
        Layout["Layout & Providers"]:::backend
        Middleware["Clerk Middleware"]:::external
        subgraph "API Routes" 
            direction TB
            SearchAPI["/api/search-api"]:::backend
            LLMModel["/api/llm-model"]:::backend
            InngestWebhook["/api/inngest"]:::backend
            InngestStatus["/api/get-inngest-status"]:::backend
        end
    end

    %% Database Zone
    subgraph "Database (Supabase)" 
        direction TB
        Supabase["Supabase PostgreSQL"]:::db
    end

    %% Inngest Zone
    subgraph "Inngest (Serverless)" 
        direction TB
        InngestClient["Inngest Client"]:::backend
        InngestFunctions["Inngest Functions"]:::backend
    end

    %% External Services Zone
    subgraph "External Services" 
        direction TB
        GoogleSearch["Google Custom Search API"]:::external
        Gemini["Gemini AI API"]:::external
        ClerkAuth["Clerk Auth Service"]:::external
    end

    %% Connections
    Home -->|SSR/CSR| Layout
    Discover -->|SSR/CSR| Layout
    Library -->|SSR/CSR| Layout
    SearchResults -->|SSR/CSR| Layout

    Layout -->|protects requests| Middleware
    Middleware -->|guards| SearchAPI
    Middleware -->|guards| LLMModel
    Middleware -->|guards| InngestWebhook
    Middleware -->|guards| InngestStatus

    SearchResults -->|submit search| SearchAPI
    SearchAPI -->|"calls"| GoogleSearch
    SearchAPI -->|"stores results"| Supabase

    SearchResults -->|trigger AI job| LLMModel
    LLMModel -->|invokes| InngestClient
    InngestClient -->|schedules| InngestFunctions
    InngestFunctions -->|"calls"| Gemini
    InngestFunctions -->|"writes summary"| Supabase

    SearchResults -->|poll status| InngestStatus
    InngestStatus -->|reads summary| Supabase
    InngestStatus -->|responds to| SearchResults

    %% Authentication flow
    SearchResults -->|checks auth| ClerkAuth
    Library -->|checks auth| ClerkAuth
    Discover -->|optional auth| ClerkAuth

    %% Click events
    click Home "https://github.com/sakshamagarwalm2/synthia/blob/main/app/page.js"
    click Discover "https://github.com/sakshamagarwalm2/synthia/blob/main/app/(routes)/discover/page.jsx"
    click Library "https://github.com/sakshamagarwalm2/synthia/blob/main/app/(routes)/library/page.jsx"
    click SearchResults "https://github.com/sakshamagarwalm2/synthia/blob/main/app/(routes)/search/[libid]/page.jsx"
    click AppSidebar "https://github.com/sakshamagarwalm2/synthia/blob/main/app/_components/AppSidebar.jsx"
    click ChatInputBox "https://github.com/sakshamagarwalm2/synthia/blob/main/app/_components/ChatInputBox.jsx"
    click CreditPopup "https://github.com/sakshamagarwalm2/synthia/blob/main/components/ui/CreditPopup.jsx"
    click Tabs "https://github.com/sakshamagarwalm2/synthia/blob/main/components/ui/tabs.jsx"
    click Layout "https://github.com/sakshamagarwalm2/synthia/blob/main/app/layout.js"
    click Middleware "https://github.com/sakshamagarwalm2/synthia/blob/main/middleware.js"
    click SearchAPI "https://github.com/sakshamagarwalm2/synthia/blob/main/app/api/search-api/route.jsx"
    click LLMModel "https://github.com/sakshamagarwalm2/synthia/blob/main/app/api/llm-model/route.js"
    click InngestWebhook "https://github.com/sakshamagarwalm2/synthia/blob/main/app/api/inngest/route.js"
    click InngestStatus "https://github.com/sakshamagarwalm2/synthia/blob/main/app/api/get-inngest-status/route.jsx"
    click Supabase "https://github.com/sakshamagarwalm2/synthia/blob/main/Services/supabase.jsx"
    click InngestClient "https://github.com/sakshamagarwalm2/synthia/blob/main/inngest/client.js"
    click InngestFunctions "https://github.com/sakshamagarwalm2/synthia/blob/main/inngest/functions.js"

    %% Styles
    classDef frontend fill:#e0f7ff,stroke:#333,stroke-width:1px
    classDef backend fill:#ffe7c6,stroke:#333,stroke-width:1px
    classDef db fill:#e0ffe0,stroke:#333,stroke-width:1px
    classDef external fill:#ffdede,stroke:#333,stroke-width:1px
```
