# stroller15/imagealchemy-ai architecture

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

- Interactive diagram: https://gitdiagram.com/stroller15/imagealchemy-ai
- Repository: https://github.com/stroller15/imagealchemy-ai

## Overview

##### Project Type and Purpose
- This is a full-stack, Next.js-based web application (“ImageAlchemy”) for AI-powered image editing.
- Frontend: Next.js + React + TailwindCSS + Radix UI
- Backend: Node.js serverless/API routes + Mongoose + MongoDB
- Integrations: Cloudinary-AI for image processing, Clerk for auth, Stripe for payments

##### Main Components
a. Frontend (UI Layer)
- app/(root), app/(auth), app/(marketing) folders define pages and layouts
- components/ui (UI primitives: buttons, forms, toasts)
- components/shared (feature-level React components: TransformationForm, MediaUploader, Sidebar, etc.)

b. Backend / API Layer
- app/api/webhooks (Clerk, Stripe webhooks)
- lib/actions (business logic: image.actions.ts, transaction.action.ts, user.actions.ts)
- lib/utils.ts (shared utility functions)
- middleware.ts (Next.js middleware for auth/session handling)

c. Data Layer
- lib/database/mongoose.ts (connects to MongoDB)
- lib/database/models (Mongoose schemas: user, image, transaction)

d. External Services
- Cloudinary-AI (image restoration, outpainting, object removal/recoloring, bg removal)
- Stripe (checkout flow, subscription/credits purchase)
- Clerk (user authentication/management)

e. Static Assets / CDN
- Next.js static hosting via Vercel (or similar)

##### Relationships & Data Flow
1) User → Next.js Frontend
- Client-side navigation & SSR/SSG via app/ routes
- Forms (React Hook Form) submit to server actions or API endpoints

2) Frontend → API
- Fetch and mutate data via RESTful endpoints or Next.js Server Actions in pages
- E.g., POST /api/transform → lib/actions/image.actions calls Cloudinary
- POST /api/transactions → lib/actions/transaction.action interacts with Stripe & DB

3) API → Database
- lib/actions/*.action.ts calls Mongoose models to create/read/update documents

4) API → External Services
- Cloudinary-AI SDK calls for image transformations
- Stripe SDK for checkout sessions and webhooks
- Clerk for session validation & webhooks

5) Webhooks → API
- Stripe and Clerk send events to /api/webhooks/stripe and /api/webhooks/clerk
- Handlers update DB (e.g., credit balance, user profile)

##### Architectural Patterns & Principles
- Layered Architecture:
- UI Layer (Next.js pages & React components)
- Service/Action Layer (lib/actions)
- Data Access Layer (Mongoose models)
- External Integration Layer (Cloudinary, Stripe, Clerk)
- Separation of Concerns: Clear division between presentation, business logic, data persistence
- Next.js App Router: Server Components with async data fetching & server actions
- Event-Driven via Webhooks for async payment and auth events

##### Additional Guidance
- Grouping: cluster related components (e.g., lib/actions next to API routes)
- Critical flows (e.g., image transformation workflow: upload → Cloudinary → DB → UI)
- Middleware/auth layer between Frontend and API to denote Clerk’s session checks

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client (Browser)" 
    direction TB
    Browser["Web Browser"]:::client
  end

  %% Frontend Layer
  subgraph "Next.js Frontend (UI Layer)" 
    direction TB
    subgraph "Root Routes" 
      direction TB
      RootLayout["Root Layout"]:::frontend
      HomePage["Home Page"]:::frontend
      CreditsPage["Credits Page"]:::frontend
      ProfilePage["Profile Page"]:::frontend
      TransformationDetail["Transformation Detail Page"]:::frontend
      TransformationAdd["Add Transformation Page"]:::frontend
    end
    subgraph "Auth Routes"
      direction TB
      AuthLayout["Auth Layout"]:::frontend
      SignInPage["Sign-In Page"]:::frontend
      SignUpPage["Sign-Up Page"]:::frontend
    end
    MarketingPage["Marketing Page"]:::frontend
    subgraph "UI Primitives"
      direction TB
      Button["Button"]:::frontend
      Form["Form"]:::frontend
      Input["Input"]:::frontend
      AlertDialog["Alert Dialog"]:::frontend
      Toast["Toast"]:::frontend
      Toaster["Toaster"]:::frontend
      UseToast["useToast Hook"]:::frontend
    end
    subgraph "Shared Components"
      direction TB
      TransformationForm["TransformationForm"]:::frontend
      MediaUploader["MediaUploader"]:::frontend
      Sidebar["Sidebar"]:::frontend
      TransformedImage["TransformedImage"]:::frontend
      CheckoutComponent["Checkout"]:::frontend
      InsufficientCreditsModal["InsufficientCreditsModal"]:::frontend
      DeleteConfirmation["DeleteConfirmation"]:::frontend
    end
    subgraph "Icons"
      direction TB
      LogoIcon["Logo Icon"]:::frontend
      Icons["Icons"]:::frontend
    end
    GlobalStyles["globals.css & Configs"]:::frontend
  end

  %% API / Service Layer
  subgraph "Next.js API / Services Layer"
    direction TB
    Middleware["Clerk Middleware"]:::backend
    subgraph "API Routes"
      direction TB
      WebhookClerk["Clerk Webhook Route"]:::backend
      WebhookStripe["Stripe Webhook Route"]:::backend
    end
    subgraph "Service / Business Logic"
      direction TB
      ImageActions["ImageActions Service"]:::backend
      TransactionActions["TransactionActions Service"]:::backend
      UserActions["UserActions Service"]:::backend
      Utils["Shared Utilities"]:::backend
    end
  end

  %% Database Layer
  subgraph "Database (MongoDB)"
    direction TB
    MongoDB[(MongoDB)]:::database
    MongooseConn["Mongoose Connection"]:::database
    subgraph "Models"
      direction TB
      UserModel["User Model"]:::database
      ImageModel["Image Model"]:::database
      TransactionModel["Transaction Model"]:::database
    end
  end

  %% External Services
  subgraph "External Services"
    direction TB
    Cloudinary["Cloudinary-AI"]:::external
    Stripe["Stripe"]:::external
    ClerkService["Clerk"]:::external
  end

  %% Connections
  Browser -->|"Page Requests & Form Submissions"| RootLayout
  Browser -->|...| AuthLayout
  Browser -->|...| MarketingPage

  RootLayout -->|uses| Button
  RootLayout -->|uses| Sidebar

  TransformationForm -->|submits to| ImageActions
  MediaUploader -->|uploads| Cloudinary
  CheckoutComponent -->|initiates| TransactionActions

  ImageActions -->|CRUD| MongoDB
  TransactionActions -->|CRUD| MongoDB
  UserActions -->|CRUD| MongoDB

  ImageActions -->|calls| Cloudinary
  TransactionActions -->|calls| Stripe
  Middleware -->|validates| ClerkService

  WebhookStripe -->|receives events| Stripe
  WebhookStripe -->|updates| TransactionActions
  WebhookClerk -->|receives events| ClerkService
  WebhookClerk -->|updates| UserActions

  MongooseConn -->|connects to| MongoDB
  ImageActions -->|uses| Utils
  TransactionActions -->|uses| Utils
  UserActions -->|uses| Utils

  Browser -.->|SSR/SSG| RootLayout

  %% Click Events
  click RootLayout "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/layout.tsx"
  click HomePage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/home/page.tsx"
  click CreditsPage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/credits/page.tsx"
  click ProfilePage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/profile/page.tsx"
  click TransformationDetail "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/transformations/[id]/page.tsx"
  click TransformationAdd "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(root)/transformations/add/[type]/page.tsx"
  click AuthLayout "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(auth)/layout.tsx"
  click SignInPage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
  click SignUpPage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.tsx"
  click MarketingPage "https://github.com/stroller15/imagealchemy-ai/blob/main/app/(marketing)/page.tsx"
  click Button "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/button.tsx"
  click Form "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/form.tsx"
  click Input "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/input.tsx"
  click AlertDialog "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/alert-dialog.tsx"
  click Toast "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/toast.tsx"
  click Toaster "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/toaster.tsx"
  click UseToast "https://github.com/stroller15/imagealchemy-ai/blob/main/components/ui/use-toast.ts"
  click TransformationForm "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/TransformationForm.tsx"
  click MediaUploader "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/MediaUploader.tsx"
  click Sidebar "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/Sidebar.tsx"
  click TransformedImage "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/TransformedImage.tsx"
  click CheckoutComponent "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/Checkout.tsx"
  click InsufficientCreditsModal "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/InsuffientCreditsModal.tsx"
  click DeleteConfirmation "https://github.com/stroller15/imagealchemy-ai/blob/main/components/shared/DeleteConfirmation.tsx"
  click LogoIcon "https://github.com/stroller15/imagealchemy-ai/blob/main/components/icons/Logo.tsx"
  click Icons "https://github.com/stroller15/imagealchemy-ai/blob/main/components/icons/icons.tsx"
  click WebhookClerk "https://github.com/stroller15/imagealchemy-ai/blob/main/app/api/webhooks/clerk/route.ts"
  click WebhookStripe "https://github.com/stroller15/imagealchemy-ai/blob/main/app/api/webhooks/stripe/route.ts"
  click ImageActions "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/actions/image.actions.ts"
  click TransactionActions "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/actions/transaction.action.ts"
  click UserActions "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/actions/user.actions.ts"
  click Utils "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/utils.ts"
  click Middleware "https://github.com/stroller15/imagealchemy-ai/blob/main/middleware.ts"
  click MongooseConn "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/database/mongoose.ts"
  click UserModel "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/database/models/user.model.ts"
  click ImageModel "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/database/models/image.model.ts"
  click TransactionModel "https://github.com/stroller15/imagealchemy-ai/blob/main/lib/database/models/transaction.model.ts"
  classDef client fill:#E3F2FD,stroke:#90CAF9
  classDef frontend fill:#BBDEFB,stroke:#64B5F6
  classDef backend fill:#C8E6C9,stroke:#81C784
  classDef database fill:#EEEEEE,stroke:#BDBDBD
  classDef external fill:#FFECB3,stroke:#FFD54F
```
