How zainulabedeen123/best-saas-kit--v2 works
Project type and purpose
• This is a full-stack, monolithic SAAS starter kit built with Next.js 15 (App Router).
• It provides production-ready features: Authentication (NextAuth.js + Google OAuth), Payments (Stripe), AI Chat (OpenRouter API), Analytics, an Admin Panel, and a User Dashboard.
File structure
• Top-level directories and files:
• src/app – Next.js “App Router” pages organized by feature (admin, api, auth, dashboard, landing, demo, docs).
• src/components – React UI components, broken into feature areas (admin, auth, billing, chat, etc.) and a shared UI library (ShadCN).
• src/lib – Service and utility modules for auth, database, Stripe, OpenRouter, analytics, email, usage tracking, etc.
• sql-queries – SQL scripts for DB setup, migrations, sample data.
• public – Static assets.
• Configs: next.config.ts, tsconfig.json, postcss.config.mjs.
• Root scripts (package.json) include db:setup, dev, build, etc.
Key insights from README
• Tech stack: Next.js 15, TypeScript, Tailwind CSS, ShadCN UI
• Integrations: NextAuth.js (Google), Stripe (payments & webhooks), OpenRouter (AI), Neon PostgreSQL, Resend (email)
• App features: landing page, auth flows, user dashboard (chat, analytics, billing, profile, settings), admin panel (user management, stats, revenue tracking)
Main components
a. Presentation layer (Frontend)
• Landing Page (public)
• Auth UI (sign-in, user session)
• User Dashboard (chat, analytics, billing, profile, settings)
• Admin Panel (analytics, user management)
b. API Layer (Serverless Functions via Next.js API Routes)
• Auth routes ([...nextauth], save-user)
• Chat routes (chat, chat/stream)
• Billing & Stripe routes (checkout, webhook, test)
• Admin routes (analytics, users, credits, upgrade-user, stats, webhook-debug)
• Email routes (contact, subscription, welcome, test)
• Usage & credits routes
c. Business-Logic Layer (src/lib)
• Auth utilities (NextAuth config, session actions)
• Database access (PG client, custom SQL functions, usage tracking)
• Stripe client & helpers
• OpenRouter API client
• Analytics & email services
d. Data layer
• Neon PostgreSQL (tables: users, credits, analytics, subscriptions, etc.)
• SQL initialization scripts (sql-queries)
e. External services
• Google OAuth (via NextAuth)
• Stripe (payments and webhooks)
• OpenRouter API (AI models & streaming)
• Email provider (Resend)
• Vercel (hosting & serverless)
Relationships and data flow
• Browser → Next.js Frontend (React pages & components)
• Frontend invokes API routes (fetch/stream)
• API routes call src/lib modules to:
• Authenticate & manage sessions
• Read/write PostgreSQL via database.ts & SQL functions
• Interact with Stripe for checkout, subscription, webhook handling
• Call OpenRouter for AI chat streaming
• Send emails via Resend
• Record analytics & usage data
• NextAuth middleware guards protected routes (dashboard, admin)
• Webhooks (Stripe) → API route → business logic → DB updates → optional analytics
Architectural patterns & design principles
• Layered architecture: Presentation → API → Services → Data
• Feature-based grouping: each feature (chat, billing, analytics) has its own pages, components, API routes, and service modules
• Serverless functions isolate backend logic per endpoint
• Monorepo style: frontend & backend in same Next.js codebase for simplified deployment
• Separation of concerns: UI vs. API vs. utilities vs. data