# zainulabedeen123/best-saas-kit--v2 architecture

> Architecture diagram of the GitHub repository zainulabedeen123/best-saas-kit--v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zainulabedeen123/best-saas-kit--v2
- Repository: https://github.com/zainulabedeen123/best-saas-kit--v2

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Presentation Layer"
    LP["Landing Page"]:::ui
    LUC["Landing UI Components"]:::ui
    AU["Auth UI (Sign-in)"]:::ui
    AUC["Auth UI Components"]:::ui
    UDPage["User Dashboard Pages"]:::ui
    UDLayout["User Dashboard Layout"]:::ui
    DUC["Dashboard UI Components"]:::ui
    ChatComp["Chat Components"]:::ui
    BillingComp["Billing Components"]:::ui
    CreditsComp["Credits Display Component"]:::ui
    APnl["Admin Panel Pages"]:::ui
    ALayout["Admin Panel Layout"]:::ui
    AUCp["Admin UI Components"]:::ui
  end

  subgraph "API Layer"
    subgraph AuthAPI
      ANEXTAUTH["[...nextauth]"]:::api
      SAVEUSER["save-user"]:::api
    end
    subgraph ChatAPI
      CHAT["chat"]:::api
      CHATSTRM["chat/stream"]:::api
    end
    subgraph BillingAPI
      CHECKOUT["stripe/checkout"]:::api
      WEBHOOK["stripe/webhook"]:::api
      TESTS["stripe/test"]:::api
    end
    subgraph AdminAPI
      ADMINAN["admin/analytics"]:::api
      ADMINCR["admin/credits"]:::api
      ADMINST["admin/stats"]:::api
      ADMTST["admin/test-analytics"]:::api
      ADMUPG["admin/upgrade-user"]:::api
      ADMUSERS["admin/users"]:::api
      ADMUSERID["admin/users/[id]"]:::api
      ADMUSERCR["admin/users/[id]/credits"]:::api
      ADMDBG["admin/webhook-debug"]:::api
    end
    subgraph EmailAPI
      EMCONT["emails/contact"]:::api
      EMSUB["emails/subscription"]:::api
      EMWEL["emails/welcome"]:::api
      EMTEST["emails/test"]:::api
    end
    subgraph UsageAPI
      USG["usage"]:::api
      CRD["credits"]:::api
    end
    subgraph UserStatsAPI
      USTATS["users/stats"]:::api
      UUSR["users"]:::api
    end
  end

  subgraph "Services Layer"
    AUTHUTILS["Auth Utilities"]:::service
    DBACCESS["Database Access"]:::service
    STRIPESVC["Stripe Client & Helpers"]:::service
    AI["OpenRouter AI Client"]:::service
    ANALYTICS["Analytics Service"]:::service
    EMAILSVC["Email Service"]:::service
    USAGETRACK["Usage Tracking"]:::service
    MW["Global Middleware"]:::service
  end

  subgraph "Data Layer"
    PG["Neon PostgreSQL"]:::database
    SQL["SQL Initialization & Migrations"]:::database
  end

  subgraph "External Services"
    GOAUTH["Google OAuth"]:::external
    STRIPEEXT["Stripe"]:::external
    OROUTER["OpenRouter API"]:::external
    RESEND["Resend Email"]:::external
    VERCEL["Vercel Hosting"]:::external
  end

  %% Presentation to API
  LP -->|"HTTP"| AuthAPI
  LUC --> AuthAPI
  AU -->|"HTTP"| AuthAPI
  AUC --> AuthAPI
  UDPage -->|"HTTP/WS"| ChatAPI
  UDPage --> BillingAPI
  UDPage --> UsageAPI
  UDPage --> UserStatsAPI
  UDPage --> EmailAPI
  UDPage --> AdminAPI
  UDLayout --> MW
  APnl --> MW
  APnl --> AdminAPI
  AUCp --> AdminAPI

  %% API to Services
  AuthAPI --> AUTHUTILS
  AuthAPI --> DBACCESS
  ChatAPI --> AI
  ChatAPI --> DBACCESS
  BillingAPI --> STRIPESVC
  BillingAPI --> DBACCESS
  BillingAPI --> ANALYTICS
  AdminAPI --> DBACCESS
  AdminAPI --> ANALYTICS
  EmailAPI --> EMAILSVC
  EmailAPI --> DBACCESS
  UsageAPI --> USAGETRACK
  UsageAPI --> DBACCESS
  UserStatsAPI --> DBACCESS

  %% Services to Data & External
  DBACCESS --> PG
  SQL --> PG
  AUTHUTILS --> PG
  STRIPESVC --> STRIPEEXT
  AI --> OROUTER
  EMAILSVC --> RESEND
  ANALYTICS --> PG

  %% Webhooks and OAuth
  STRIPEEXT --> WEBHOOK
  GOAUTH --> ANEXTAUTH
  VERCEL --> AuthAPI
  VERCEL --> ChatAPI
  VERCEL --> BillingAPI
  VERCEL --> AdminAPI
  VERCEL --> EmailAPI
  VERCEL --> UsageAPI
  VERCEL --> UserStatsAPI

  %% Click Events
  click LP "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/app/page.tsx"
  click LUC "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/components/landing"
  click AU "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/app/auth/signin/page.tsx"
  click AUC "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/components/auth"
  click UDPage "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/dashboard"
  click UDLayout "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/app/dashboard/layout.tsx"
  click DUC "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/components/dashboard/dashboard-client.tsx"
  click ChatComp "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/components/chat"
  click BillingComp "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/components/billing/billing-client.tsx"
  click CreditsComp "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/components/credits/credits-display.tsx"
  click APnl "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/admin"
  click ALayout "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/app/admin/layout.tsx"
  click AUCp "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/components/admin"
  click ANEXTAUTH "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/auth"
  click ChatAPI "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/chat"
  click BillingAPI "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/stripe"
  click AdminAPI "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/admin"
  click EmailAPI "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/emails"
  click UsageAPI "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/usage"
  click UUSR "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/src/app/api/users"
  click AUTHUTILS "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/auth.ts"
  click DBACCESS "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/database.ts"
  click STRIPESVC "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/stripe-client.ts"
  click AI "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/openrouter.ts"
  click ANALYTICS "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/simple-analytics.ts"
  click EMAILSVC "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/resend.ts"
  click USAGETRACK "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/lib/usage-tracking.ts"
  click SQL "https://github.com/zainulabedeen123/best-saas-kit--v2/tree/main/sql-queries"
  click MW "https://github.com/zainulabedeen123/best-saas-kit--v2/blob/main/src/middleware.ts"

  %% Styles
  classDef ui fill:#e0ffe0,stroke:#2d7f2d,stroke-width:1px;
  classDef api fill:#e0f0ff,stroke:#1a5f9e,stroke-width:1px;
  classDef service fill:#fff4e0,stroke:#9e6a1a,stroke-width:1px;
  classDef database fill:#ffe0e0,stroke:#9e1a1a,stroke-width:1px;
  classDef external fill:#f0f0f0,stroke:#555555,stroke-width:1px;
```
