# codinginflow/nextjs-15-social-media-app architecture

> Architecture diagram of the GitHub repository codinginflow/nextjs-15-social-media-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codinginflow/nextjs-15-social-media-app
- Repository: https://github.com/codinginflow/nextjs-15-social-media-app

## Overview

##### Project Type and Purpose
- This is a full-stack social media web application built with Next.js 15’s App Router.
- Key features: authentication (email/password + Google OAuth), infinite scrolling feeds, optimistic UI updates, direct messaging (real-time chat), notifications, file/image uploads.

##### File Structure
- Top-level “src/app” directory: Next.js App Router routes, React Server Components, and client components.
- (auth) pages handle login/signup and OAuth callbacks.
- (main) pages cover feeds, posts, profiles, DMs, notifications, search.
- “src/app/api” folder: Next.js API route handlers (REST endpoints for auth, posts, comments, likes, bookmarks, notifications, search, uploads, user data).
- “prisma/schema.prisma”: data model for relational DB (PostgreSQL or MySQL) via Prisma ORM.
- “src/lib”: client-side utilities (ky for HTTP, prisma client, validation, uploadthing, real-time stream helper).
- “src/components”: reusable UI bits (buttons, dialogs, posts, comments, chat UI).
- Configuration: next.config.mjs, vercel.json (deployment), tailwind.config.ts.

##### README for Additional Insights
- Confirms it’s a tutorial app demonstrating real-world features: infinite loading, optimistic updates, file uploads, DMs, notifications.

##### Main Components & Their Relationships
a. Client (Browser):
- Renders React components (UI), interacts via Server Components and Client Components.
- Uses React-Query for data fetching/caching, calls Next.js API endpoints.
b. Next.js Application Server:
- Serves pages (SSR+RSC), hosts API routes, orchestrates authentication (NextAuth or custom).
- Invokes Prisma Client to query/update the database.
c. Database (PostgreSQL/MySQL):
- Holds users, posts, comments, likes, bookmarks, messages, notifications.
d. External Services:
- OAuth Provider (Google for social login).
- File Upload Service (UploadThing, backing store could be S3).
- Real-time Messaging Service (stream or pusher, used for live chat/notifications).
e. Deployment:
- Hosted on Vercel (serverless functions for API routes, static asset CDN).

##### Data Flows & Interactions
- Authentication Flow:
User enters credentials → Next.js Auth API → OAuth provider (if Google) → Session cookie.
- Data Fetching:
Client uses React-Query → calls Next.js REST endpoints → Prisma → Database → JSON back to client.
- Infinite Scroll & Optimistic Updates:
Client paginates via “for-you” / “following” endpoints, updates UI immediately, syncs with server.
- File Upload:
Client requests upload token → calls UploadThing API route → gets upload URL → posts file directly to storage.
- Real-time Chat / Notifications:
Client subscribes to messaging service via SDK initialized in useInitializeChatClient.ts → server—via webhooks or triggers—pushes updates.

##### Architectural Patterns & Design Principles
- Monolithic Full-stack: Single codebase, clear separation between frontend routes and API routes.
- React Server Components for data fetching and rendering on the server.
- Client Components for interactivity (e.g., message input, like buttons).
- API Layer: Thin REST layer using Next.js “/api” routes.
- ORM Layer: Prisma for DB abstraction.
- CQRS-style split: Queries (feeds, search) vs. Mutations (like, comment, bookmark) organized under separate routes and “actions.ts” files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser (Client)"
        BROWSER["Browser\n(React UI)"]:::frontend
        ReactQuery["React-Query Provider\n(src/app/ReactQueryProvider.tsx)"]:::frontend
        KY["ky HTTP Utility\n(src/lib/ky.ts)"]:::frontend
        BROWSER -->|"initializes"| ReactQuery
        ReactQuery -->|"uses"| KY
        BROWSER -->|"HTTPS API"| API_CALLS
    end

    subgraph "Next.js App Server\n(Node.js, RSC)" 
        NextJs["Next.js App Router & Pages\n(src/app)"]:::backend
        subgraph "Next.js /api Routes\n(src/app/api)"
            AuthAPI["Auth Routes"]:::backend
            PostsAPI["Posts & Feeds"]:::backend
            MsgAPI["Messaging API"]:::backend
            NotifAPI["Notifications API"]:::backend
            UploadAPI["UploadThing API"]:::backend
        end
        NextJs --> AuthAPI
        NextJs --> PostsAPI
        NextJs --> MsgAPI
        NextJs --> NotifAPI
        NextJs --> UploadAPI
    end

    API_CALLS -->|"HTTPS"| AuthAPI
    API_CALLS -->|"HTTPS"| PostsAPI
    API_CALLS -->|"HTTPS"| MsgAPI
    API_CALLS -->|"HTTPS"| NotifAPI
    API_CALLS -->|"HTTPS"| UploadAPI

    AuthAPI -->|"invokes"| PrismaClient
    PostsAPI -->|"invokes"| PrismaClient
    MsgAPI -->|"invokes"| PrismaClient
    NotifAPI -->|"invokes"| PrismaClient
    UploadAPI -->|"invokes"| PrismaClient

    PrismaClient["Prisma Client\n(src/lib/prisma.ts)"]:::backend
    PrismaClient -->|"SQL Queries"| DB

    BROWSER -->|"WebSocket (WS)"| RT["Real-time Service\n(Stream/Pusher)"]:::external
    MsgAPI -->|"Webhooks"| RT

    AuthAPI -->|"OAuth HTTPS"| OAuth["OAuth Provider\n(Google)"]:::external
    UploadAPI -->|"HTTPS"| UploadService["Upload Service\n(UploadThing/S3)"]:::external

    DB["Database\n(PostgreSQL/MySQL)\n(prisma/schema.prisma)"]:::external

    %% Click Events
    click ReactQuery "https://github.com/codinginflow/nextjs-15-social-media-app/blob/Final-Project/src/app/ReactQueryProvider.tsx"
    click KY "https://github.com/codinginflow/nextjs-15-social-media-app/blob/Final-Project/src/lib/ky.ts"
    click NextJs "https://github.com/codinginflow/nextjs-15-social-media-app/tree/Final-Project/src/app"
    click AuthAPI "https://github.com/codinginflow/nextjs-15-social-media-app/tree/Final-Project/src/app/api"
    click PrismaClient "https://github.com/codinginflow/nextjs-15-social-media-app/blob/Final-Project/src/lib/prisma.ts"
    click DB "https://github.com/codinginflow/nextjs-15-social-media-app/blob/Final-Project/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#1e7e34,stroke-width:1px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:1px;
    classDef realtime stroke:#8a2be2,stroke-width:2px,stroke-dasharray: 5 5;
    class RT realtime
```
