# utkarshthedev/tweeterlens architecture

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

- Interactive diagram: https://gitdiagram.com/utkarshthedev/tweeterlens
- Repository: https://github.com/utkarshthedev/tweeterlens

## Overview

##### Main components
- User / Browser
– Interacts with the React-based UI in the browser
– Fetches pages (SSR) and calls client-side data hooks (TanStack Query)
- Next.js Server (App Router)
– Renders pages server-side via `src/app`
– Hosts serverless API routes under `src/app/api/twitter` and `.../stats`
- Upstash Redis (Caching Layer)
– Caches Twitter profiles, tweets, and stats for 8-hour TTL
- Social Data API (External Service)
– Provides Twitter data (user profiles, tweet lists, engagement metrics)
- Vercel (Hosting / Deployment)
– Hosts Next.js app and static assets (in `/public`)
- Client-side State & UI Libraries
– TanStack Query (data fetching/cache on client)
– Shadcn UI + Tailwind CSS + Framer Motion (UI & animation)

##### Relationships and data flows
- Page request (initial SSR)
1. Browser → Next.js Server → SSR `page.tsx`
2. Next.js Server calls internal API route (`route.ts`) if data needed
3. API route checks Upstash Redis → cache hit or miss
4. If miss, API route calls Social Data API → stores response in Redis → returns data
5. Server renders page HTML + initial JSON payload → Browser
- Client-side data fetching (interactions / pagination)
1. React components (e.g., `Tweets.tsx`) invoke TanStack Query hooks
2. Query hooks call Next.js serverless API endpoints
3. Same Redis + external API flow as above
4. Data returns to UI, updates components
- Static assets & fonts
– Served directly from `/public` via Vercel’s CDN

##### Architectural patterns
- Full-stack SSR with Next.js App Router
- Serverless Function API Layer for data aggregation
- Smart caching using Upstash Redis to minimize external API calls
- Client-side caching & state management with TanStack Query
- Separation of concerns:
– `src/app` for pages & API routes
– `src/components` for UI
– `src/lib` for utilities and providers
– `src/context` for React context

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        Browser["Browser / React UI"]:::client
        ReactQueryProvider["TanStack Query Provider"]:::compute
        SearchContext["Search Context"]:::compute
        Browser -->|"uses Provider & Context"| ReactQueryProvider
        Browser -->|"uses Provider & Context"| SearchContext
    end

    %% Vercel CDN
    subgraph "Vercel CDN"
        direction TB
        StaticAssets["Static Assets (/public)"]:::cdn
        Fonts["Font Assets"]:::cdn
    end

    Browser -->|"GET assets"| StaticAssets
    Browser -->|"GET fonts"| Fonts

    %% Server Side / Vercel
    subgraph "Server Side / Vercel"
        direction TB
        NextServer["Next.js Server (SSR)"]:::compute
        PageHome["Home/Search Page"]:::compute
        PageTweets["Tweets Analytics Page"]:::compute
        Layout["Global Layout"]:::compute
        Providers["App Providers"]:::compute
        API_Twitter["API: /api/twitter"]:::compute
        API_Stats["API: /api/twitter/stats"]:::compute
        Redis["Upstash Redis"]:::storage
        TwitterUtils["Twitter Utils"]:::compute
        GlobalsCSS["Globals.css"]:::compute
        TailwindConfig["tailwind.config.js"]:::compute
        FontsLoader["Font Loader"]:::compute

        NextServer -->|"SSR page request"| PageHome
        NextServer -->|"SSR page request"| PageTweets
        NextServer -->|"renders with Layout & Providers"| Layout
        NextServer -->|"includes styles/scripts"| GlobalsCSS
        NextServer -->|"includes styles/scripts"| TailwindConfig
        NextServer -->|"loads fonts via"| FontsLoader

        Browser -->|"initial SSR request"| NextServer
        Browser -->|"client API calls"| API_Twitter
        Browser -->|"client API calls"| API_Stats

        NextServer -->|"internal API call"| API_Twitter
        NextServer -->|"internal API call"| API_Stats

        API_Twitter -->|"cache GET/SET"| Redis
        API_Stats -->|"cache GET/SET"| Redis

        API_Twitter -->|"calls on miss"| SocialAPI
        API_Stats -->|"calls on miss"| SocialAPI

        API_Twitter -->|"uses utils"| TwitterUtils
        API_Stats -->|"uses utils"| TwitterUtils
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SocialAPI["Social Data API"]:::external
    end

    %% Click Events
    click Browser "https://github.com/utkarshthedev/tweeterlens/tree/main/src/components/"
    click ReactQueryProvider "https://github.com/utkarshthedev/tweeterlens/blob/main/src/lib/ReactQueryProvider.tsx"
    click SearchContext "https://github.com/utkarshthedev/tweeterlens/blob/main/src/context/SearchContext.tsx"
    click StaticAssets "https://github.com/utkarshthedev/tweeterlens/tree/main/public/"
    click Fonts "https://github.com/utkarshthedev/tweeterlens/tree/main/public/fonts/cabinet-web/"
    click NextServer "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/page.tsx"
    click PageHome "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/page.tsx"
    click PageTweets "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/tweets/page.tsx"
    click Layout "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/layout.tsx"
    click Providers "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/providers.tsx"
    click API_Twitter "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/api/twitter/route.ts"
    click API_Stats "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/api/twitter/stats/route.ts"
    click Redis "https://github.com/utkarshthedev/tweeterlens/blob/main/src/lib/upstash.ts"
    click TwitterUtils "https://github.com/utkarshthedev/tweeterlens/blob/main/src/lib/twitter-utils.ts"
    click GlobalsCSS "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/globals.css"
    click TailwindConfig "https://github.com/utkarshthedev/tweeterlens/blob/main/tailwind.config.js"
    click FontsLoader "https://github.com/utkarshthedev/tweeterlens/blob/main/src/app/fonts.ts"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef compute fill:#bbf,stroke:#333,stroke-width:2px
    classDef storage fill:#fbf,stroke:#333,stroke-width:2px
    classDef external fill:#fbb,stroke:#333,stroke-width:2px
    classDef cdn fill:#bfb,stroke:#333,stroke-width:2px
```
