# oyezaheer/imaginify architecture

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

- Interactive diagram: https://gitdiagram.com/oyezaheer/imaginify
- Repository: https://github.com/oyezaheer/imaginify

## Overview

##### Project type and purpose
- This is a full-stack SaaS web application (“An AI SaaS Platform”) built with Next.js (App Router), TypeScript, MongoDB, Clerk for authentication, Cloudinary for media hosting, Stripe for payments, Shadcn/TailwindCSS for UI components.
- It offers user authentication, credit‐based image transformations, transaction tracking, and webhook integrations.

##### File structure
- **app/** (Next.js App Router)
- (auth) subfolder: sign-in, sign-up pages (Clerk)
- (root) subfolder: public pages (credits, profile, transformations CRUD)
- **app/api/**: serverless API routes for Clerk & Stripe webhooks
- **layout.tsx**, **globals.css**: global layouts & styles
- **components/** & **components/ui/**: shared UI/UX building blocks (Shadcn/Tailwind)
- **lib/**
- actions/: business logic (image, transaction, user)
- database/: Mongoose setup & models (User, Image, Transaction)
- utils.ts: helper functions
- Configs: next.config.mjs, tsconfig.json, tailwind.config.ts, postcss.config.js
- **middleware.ts**: Next.js middleware (e.g., auth guards)

##### README
- Confirms tech stack (Next.js, TypeScript, MongoDB, Clerk, Cloudinary, Stripe, Shadcn, TailwindCSS)
- Basic setup and run instructions

a. Main Components
- Client (Browser/mobile)
- Frontend (Next.js App)
- Auth Service (Clerk)
- Backend/API Layer (Next.js API routes + lib/actions)
- Database (MongoDB via Mongoose)
- Media Storage (Cloudinary)
- Payment Service (Stripe)
- External AI engine (if any; implicit)
b. Relationships & Interactions
1. User → Browser UI → Next.js pages/components
2. UI triggers API calls (REST/HTTP) to:
- Authentication (Clerk SDK)
- CRUD operations via lib/actions (user, image, transactions)
3. API layer → MongoDB (read/write models)
4. API layer → Cloudinary (upload/retrieve images)
5. API layer → Stripe (charge user credits, via payment intents)
6. Stripe & Clerk send webhooks → /app/api/webhooks/stripe & /clerk/route.ts → update DB
c. Architectural Patterns & Principles
- **Separation of Concerns**:
- UI vs. Business Logic (components vs. lib/actions)
- Serverless functions (Next.js API) vs. Persistent DB
- **Modular Components**: Shadcn UI primitives + shared components
- **Middleware**: auth guard, routing logic
- **MVC-like**: Routes → Controllers (actions) → Models
d. Key Technologies & Frameworks
- Next.js (App Router, server-side rendering, API routes)
- TypeScript (types/tsconfig)
- MongoDB + Mongoose (lib/database/models)
- Clerk (auth)
- Cloudinary (media)
- Stripe (payments)
- TailwindCSS & Shadcn (styling/UI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        AuthLayout["Auth Layout"]:::frontend
        SignInPage["Sign-In Page"]:::frontend
        SignUpPage["Sign-Up Page"]:::frontend
        RootLayout["Root Layout"]:::frontend
        GlobalLayout["Global Layout & Styles"]:::frontend
        HomePage["Home/Dashboard"]:::frontend
        CreditsPage["Credits Page"]:::frontend
        ProfilePage["Profile Page"]:::frontend
        ListTransform["List Transformation"]:::frontend
        UpdateTransform["Update Transformation"]:::frontend
        AddTransform["Add Transformation"]:::frontend
        UIPrimitives["UI Primitives"]:::frontend
        SharedComponents["Shared UI Components"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        APIRoutes["Next.js API Routes"]:::backend
        ClerkWebhook["Clerk Webhooks Route"]:::backend
        StripeWebhook["Stripe Webhooks Route"]:::backend
        Middleware["Next.js Middleware"]:::backend
        UserActions["User Actions"]:::backend
        ImageActions["Image Actions"]:::backend
        TransactionActions["Transaction Actions"]:::backend
    end

    %% Database & Utils
    subgraph "Database & Utils"
        direction TB
        MongooseConn["Mongoose Connection"]:::db
        UserModel["User Model"]:::db
        ImageModel["Image Model"]:::db
        TransactionModel["Transaction Model"]:::db
        Utils["Utilities"]:::backend
        Constants["Constants"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ClerkAuth["Clerk Auth Service"]:::external
        StripeService["Stripe API"]:::external
        Cloudinary["Cloudinary CDN"]:::external
        AIEngine["External AI Engine"]:::external
    end

    %% User
    User["User (Browser)"]:::external

    %% User interactions
    User -->|"visits"| AuthLayout
    AuthLayout --> SignInPage
    AuthLayout --> SignUpPage
    User -->|"visits"| RootLayout
    RootLayout --> HomePage
    RootLayout --> CreditsPage
    RootLayout --> ProfilePage
    RootLayout --> ListTransform
    RootLayout --> UpdateTransform
    RootLayout --> AddTransform

    HomePage --> UIPrimitives
    CreditsPage --> UIPrimitives
    ProfilePage --> UIPrimitives
    ListTransform --> UIPrimitives
    UpdateTransform --> UIPrimitives
    AddTransform --> UIPrimitives
    UIPrimitives --> SharedComponents

    %% Frontend to External/Auth
    SignInPage -->|"auth SDK"| ClerkAuth
    SignUpPage -->|"auth SDK"| ClerkAuth

    %% Frontend to Backend
    HomePage -->|"REST API"| APIRoutes
    CreditsPage -->|"REST API"| APIRoutes
    ProfilePage -->|"REST API"| APIRoutes
    ListTransform -->|"REST API"| APIRoutes
    UpdateTransform -->|"REST API"| APIRoutes
    AddTransform -->|"REST API"| APIRoutes

    %% Backend flow
    APIRoutes --> Middleware
    Middleware --> UserActions
    Middleware --> ImageActions
    Middleware --> TransactionActions

    UserActions --> MongooseConn
    ImageActions --> Cloudinary
    ImageActions --> AIEngine
    TransactionActions --> StripeService
    TransactionActions --> MongooseConn

    %% Webhooks
    ClerkAuth --> ClerkWebhook
    StripeService --> StripeWebhook
    ClerkWebhook --> UserActions
    StripeWebhook --> TransactionActions

    %% DB Models
    MongooseConn --> UserModel
    MongooseConn --> ImageModel
    MongooseConn --> TransactionModel

    %% Utils & Constants
    Utils --> UserActions
    Utils --> ImageActions
    Utils --> TransactionActions
    Constants --> UserActions
    Constants --> ImageActions
    Constants --> TransactionActions

    %% Click Events
    click SignInPage "https://github.com/oyezaheer/imaginify/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
    click SignUpPage "https://github.com/oyezaheer/imaginify/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.tsx"
    click AuthLayout "https://github.com/oyezaheer/imaginify/blob/main/app/(auth)/layout.tsx"
    click HomePage "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/page.tsx"
    click CreditsPage "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/credits/page.tsx"
    click ProfilePage "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/profile/page.tsx"
    click ListTransform "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/transformations/[id]/page.tsx"
    click UpdateTransform "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/transformations/[id]/update/page.tsx"
    click AddTransform "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/transformations/add/[type]/page.tsx"
    click RootLayout "https://github.com/oyezaheer/imaginify/blob/main/app/(root)/layout.tsx"
    click GlobalLayout "https://github.com/oyezaheer/imaginify/blob/main/app/layout.tsx"
    click UIPrimitives "https://github.com/oyezaheer/imaginify/tree/main/components/ui/"
    click SharedComponents "https://github.com/oyezaheer/imaginify/tree/main/components/shared/"
    click ClerkWebhook "https://github.com/oyezaheer/imaginify/blob/main/app/api/webhooks/clerk/route.ts"
    click StripeWebhook "https://github.com/oyezaheer/imaginify/blob/main/app/api/webhooks/stripe/route.ts"
    click UserActions "https://github.com/oyezaheer/imaginify/blob/main/lib/actions/user.actions.ts"
    click ImageActions "https://github.com/oyezaheer/imaginify/blob/main/lib/actions/image.actions.ts"
    click TransactionActions "https://github.com/oyezaheer/imaginify/blob/main/lib/actions/transaction.action.ts"
    click MongooseConn "https://github.com/oyezaheer/imaginify/blob/main/lib/database/mongoose.ts"
    click UserModel "https://github.com/oyezaheer/imaginify/blob/main/lib/database/models/user.model.ts"
    click ImageModel "https://github.com/oyezaheer/imaginify/blob/main/lib/database/models/image.model.ts"
    click TransactionModel "https://github.com/oyezaheer/imaginify/blob/main/lib/database/models/transaction.model.ts"
    click Utils "https://github.com/oyezaheer/imaginify/blob/main/lib/utils.ts"
    click Constants "https://github.com/oyezaheer/imaginify/blob/main/constants/index.ts"
    click Middleware "https://github.com/oyezaheer/imaginify/blob/main/middleware.ts"
    click nextConfig "https://github.com/oyezaheer/imaginify/blob/main/next.config.mjs"
    click tsconfig "https://github.com/oyezaheer/imaginify/blob/main/tsconfig.json"
    click tailwindConfig "https://github.com/oyezaheer/imaginify/blob/main/tailwind.config.ts"
    click postcssConfig "https://github.com/oyezaheer/imaginify/blob/main/postcss.config.js"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
    classDef db fill:#FFFF99,stroke:#333,stroke-width:1px
```
