# siddharthjiyani/knots-social-media-app architecture

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

- Interactive diagram: https://gitdiagram.com/siddharthjiyani/knots-social-media-app
- Repository: https://github.com/siddharthjiyani/knots-social-media-app

## Overview

##### Project Type & Purpose
- Full-stack community discussion platform (“Knots App”)
- Built on Next.js 14+ (App Router), MongoDB/Mongoose, Clerk Auth, Tailwind CSS/Shadcn‐UI
- Features: user authentication, communities, threads & nested comments, file uploads, webhooks for real‐time events

##### File Structure & Architectural Insights
- app/… : Next.js App Router with grouped layouts for auth flows vs. main routes (home, communities, threads, profile)
- app/api/… : serverless Route Handlers for file uploads (UploadThing) and Clerk webhooks
- components/… : UI atoms/molecules/organisms (cards, forms, shared layouts)
- lib/actions/… : server actions (business logic controllers) for community, thread, user operations
- lib/models/… : Mongoose schemas (User, Thread, Community)
- middleware.ts : Clerk authentication middleware
- config & styles: next.config.js, tailwind.config.js, globals.css

##### Main System Components
a. Frontend (Next.js App)
- React Server Components & Client Components under app/
- Shadcn-UI + Tailwind for styling
b. Backend/API Layer
- Server Actions (imported in RSCs) for CRUD operations
- API Routes (/api/uploadthing, /api/webhook/clerk)
- Middleware for auth/authorization
c. Database
- MongoDB (external) via Mongoose models
d. External Services
- Clerk (user auth, social login, organizations & webhooks)
- UploadThing (file storage & React helpers)
- Svix (webhook signature verification)

##### Relationships & Data Flows
1. Browser → Next.js Pages (SSR/SSR via RSCs)
2. Pages → Server Actions (createThread, updateUser, etc.)
3. Pages → API Routes (upload, webhook)
4. Server Actions/API → Mongoose → MongoDB
5. Clerk handles login; middleware injects session → Next.js
6. UploadThing receives files; responds to client
7. Clerk emits org events → Svix‐verified webhook → Community actions

##### Architectural Patterns
- App Router & Route Groups for logical separation
- Server Actions as BFF/controller layer
- MVC-like layering: Models (Mongoose), Actions (Controllers), Views (React)
- Serverless functions for APIs
- Shared code monorepo (frontend + backend)

##### Elements
- Labels: “Browser”, “Next.js App”, “Server Actions”, “API Routes”, “MongoDB”, “Clerk”, “UploadThing”
- Frontend (Blue),
- Next.js Server/API (Green),
- Database (Orange),
- External Services (Purple)
- Rectangles for modules/services,
- Clouds for third-party services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Browser["Browser"]:::frontend
    NextUI["Next.js UI\n(app/)"]:::frontend
    Browser -->|"renders via SSR"| NextUI

    %% Server
    subgraph "Next.js Application" 
        direction TB
        AuthRoutes["Auth Flow Routes\n(app/(auth)/)"]:::backend
        RootRoutes["Main App Routes\n(app/(root)/)"]:::backend
        Middleware["Authentication Middleware\n(middleware.ts)"]:::backend
        ServerActions["Server Actions\n(lib/actions/)"]:::backend
        APIRoutes["API Routes"]:::backend
        UploadAPI["/api/uploadthing\n(route.ts & core.ts)"]:::backend
        WebhookAPI["/api/webhook/clerk\n(route.ts)"]:::backend
        Models["Mongoose Models\n(lib/models/)"]:::backend
    end

    NextUI -->|"navigates to"| AuthRoutes
    NextUI -->|"navigates to"| RootRoutes
    AuthRoutes -->|uses| Middleware
    RootRoutes -->|uses| Middleware
    NextUI -->|"calls server actions"| ServerActions
    NextUI -->|"calls API"| UploadAPI
    NextUI -->|"receives webhook"| WebhookAPI

    ServerActions -->|"\nreads/writes"| Models
    UploadAPI -->|"\nstores file"| UploadThing
    WebhookAPI -.->|async webhook| Svix
    WebhookAPI -->|calls| ServerActions

    %% Persistence
    MongoDB["MongoDB Atlas\n(cylinder)"]:::database
    Models -->|"\nvia Mongoose"| MongoDB

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth"]:::external
        UploadThing["UploadThing"]:::external
        Svix["Svix"]:::external
    end

    NextUI -->|"login/auth"| Clerk
    Clerk -->|injects session via\nMiddleware| Middleware
    UploadAPI -->|verifies & stores| UploadThing

    Clerk -.->|webhook events| WebhookAPI
    Svix -.->|verifies signature| WebhookAPI

    %% Click Events
    click NextUI "https://github.com/siddharthjiyani/knots-social-media-app/tree/main/app/"
    click AuthRoutes "https://github.com/siddharthjiyani/knots-social-media-app/tree/main/app/(auth)/"
    click RootRoutes "https://github.com/siddharthjiyani/knots-social-media-app/tree/main/app/(root)/"
    click Middleware "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/middleware.ts"
    click ServerActions "https://github.com/siddharthjiyani/knots-social-media-app/tree/main/lib/actions/"
    click Models "https://github.com/siddharthjiyani/knots-social-media-app/tree/main/lib/models/"
    click UploadAPI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/app/api/uploadthing/route.ts"
    click UploadAPI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/app/api/uploadthing/core.ts"
    click WebhookAPI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/app/api/webhook/clerk/route.ts"
    click Clerk "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/lib/uploadthing.ts"
    click MongoDB "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/lib/mongoose.ts"
    click UploadThing "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/lib/uploadthing.ts"
    click NextUI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/app/globals.css"
    click NextUI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/tailwind.config.js"
    click NextUI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/postcss.config.js"
    click NextUI "https://github.com/siddharthjiyani/knots-social-media-app/blob/main/next.config.js"

    %% Styling
    classDef frontend fill:#D0E8FF,stroke:#1E90FF,color:#000
    classDef backend fill:#D6F5D6,stroke:#2E8B57,color:#000
    classDef database fill:#FFE4B5,stroke:#FF8C00,color:#000
    classDef external fill:#E6D0F8,stroke:#800080,color:#000
```
