How stroller15/imagealchemy-ai works
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