# piyushk-dev/gestify architecture

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

- Interactive diagram: https://gitdiagram.com/piyushk-dev/gestify
- Repository: https://github.com/piyushk-dev/gestify

## Overview

##### Project type and purpose
- Gestify is a full-stack web application built on Next.js with TypeScript and React Server Components.
- Its core purpose is to scrape news from multiple sources, summarize articles via the Gemini AI API, compare perspectives, store results, and deliver a personalized feed or newsletter to authenticated users.

##### File structure
- Top-level Next.js “app” directory holds routing, server components, and API routes under `app/api`.
- `app/api/auth/*` implements OAuth endpoints (login, logout, refresh) for Google.
- `app/api/generate-pdf/route.ts` exposes a PDF-generation micro-endpoint.
- `app/components/…` contains page-specific React components; a parallel `components/ui` folder holds shared UI primitives.
- `lib/` encapsulates low-level logic:
- `auth.ts` for JWT/session handling
- `mongodb.ts` and `postgres.ts` (via Prisma in `prisma.ts`) for database connections
- `actions.ts` and `utils.ts` for business logic
- `providers/authprovider.tsx` wires up React context for auth state.
- Hooks folder centralizes custom React hooks (`use-toast`, `use-mobile`).
- Configuration files: `next.config.mjs`, `tailwind.config.ts`, `postcss.config.mjs`.

##### README for additional insights
- Tech stack: Next.js (with ISR every 12h + SSR), PostgreSQL, MongoDB, Gemini API for summaries, OAuth for login.
- Features mention scrapers that run on a schedule (not in repo but implied externally) to refresh stale data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client (Browser/Mobile)"]:::frontend

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        NextApp["Next.js App Router"]:::backend
        RSC["React Server Components"]:::backend
        API["API Routes"]:::backend
        Components["Page Components"]:::frontend
        UI["Shared UI Primitives"]:::frontend
        Hooks["Custom Hooks"]:::frontend
        Provider["Auth Context Provider"]:::backend
        Utils["Utils & Actions"]:::backend
        LibAuth["JWT/Session Handling"]:::backend
        Prisma["Prisma ORM & Postgres"]:::db
        Mongo["MongoDB Client"]:::db
        Layout["Global Layout & Styling"]:::frontend
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        OAuth["Google OAuth"]:::external
        Gemini["Gemini AI API"]:::external
        Email["Email/Newsletter Service"]:::external
    end

    %% Scraper Jobs
    Scraper["Scheduled Scraper Jobs"]:::backend

    %% CDN / Cache
    CDN["CDN / ISR Cache"]:::backend

    %% Data Flow
    Client -->|"HTTP Requests / RSC Fetch"| CDN
    CDN --> NextApp
    NextApp --> RSC
    NextApp --> API
    NextApp --> Components
    NextApp --> Layout
    Components --> UI
    Components --> Hooks
    Hooks -->|use-toast / use-mobile| Utils

    API --> AuthAPI["Auth Service"]:::backend
    API --> SumAPI["Summarization Service"]:::backend
    API --> PDFAPI["PDF-Generation Endpoint"]:::backend

    AuthAPI -->|OAuth Redirect| OAuth
    AuthAPI -->|JWT Issuance| LibAuth

    SumAPI -->|Summarize Articles| Gemini
    SumAPI -->|Utils calls| Utils

    PDFAPI -->|Generate PDF| RSC

    NextApp -->|DB Queries| Prisma
    Prisma -->|TCP| PostgreSQLDB["PostgreSQL"]:::db
    NextApp -->|Raw Articles| Mongo
    Mongo -->|Store & Read| MongoDB["MongoDB"]:::db

    Scraper -->|Push Raw Articles| Mongo
    Scraper -.->|Stale Tagging| Mongo

    SumAPI -->|Store Summaries| Mongo
    NextApp -->|Read Summaries| Mongo

    NextApp -->|Read User Data| PostgreSQLDB
    NextApp -->|Read Feed Metadata| PostgreSQLDB

    %% Newsletter Workflow
    EmailService["Newsletter Service"]:::external
    EmailService -->|Fetch Personalized Summaries| PostgreSQLDB
    EmailService -->|Send Emails| Email

    %% Click Events
    click NextApp "https://github.com/piyushk-dev/gestify/tree/main/app/"
    click AuthAPI "https://github.com/piyushk-dev/gestify/tree/main/app/api/auth/"
    click PDFAPI "https://github.com/piyushk-dev/gestify/blob/main/app/api/generate-pdf/route.ts"
    click SumAPI "https://github.com/piyushk-dev/gestify/blob/main/lib/actions.ts"
    click LibAuth "https://github.com/piyushk-dev/gestify/blob/main/lib/auth.ts"
    click Prisma "https://github.com/piyushk-dev/gestify/blob/main/lib/prisma.ts"
    click Mongo "https://github.com/piyushk-dev/gestify/blob/main/lib/mongodb.ts"
    click Utils "https://github.com/piyushk-dev/gestify/blob/main/lib/utils.ts"
    click Provider "https://github.com/piyushk-dev/gestify/blob/main/providers/authprovider.tsx"
    click UI "https://github.com/piyushk-dev/gestify/tree/main/components/ui/"
    click Components "https://github.com/piyushk-dev/gestify/tree/main/app/components/"
    click Hooks "https://github.com/piyushk-dev/gestify/blob/main/hooks/use-toast.tsx"
    click Hooks "https://github.com/piyushk-dev/gestify/blob/main/hooks/use-mobile.tsx"
    click Layout "https://github.com/piyushk-dev/gestify/blob/main/app/layout.tsx"
    click Client "https://github.com/piyushk-dev/gestify/blob/main/app/globals.css"
    click Client "https://github.com/piyushk-dev/gestify/blob/main/tailwind.config.ts"
    click Client "https://github.com/piyushk-dev/gestify/blob/main/postcss.config.mjs"
    click FeedPage "https://github.com/piyushk-dev/gestify/blob/main/app/feed/page.tsx"
    click NewsletterPage "https://github.com/piyushk-dev/gestify/blob/main/app/newsletter/page.tsx"
    click PrefsPage "https://github.com/piyushk-dev/gestify/blob/main/app/preferences/page.tsx"

    %% Define individual page nodes for click
    FeedPage["Main Feed Page"]:::frontend
    NewsletterPage["Newsletter Page"]:::frontend
    PrefsPage["User Preferences Page"]:::frontend

    %% Legend Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#01579B
    classDef backend fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef db fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef util fill:#F1F8E9,stroke:#AFB42B,color:#827717
```
