# zainulabedeen123/best-saas-kit architecture

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

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

## Overview

##### Project Type & Purpose
- This is a full‐stack SaaS starter kit built with Next.js 15 (App Router + Server Actions), TypeScript, Tailwind CSS, and shadcn/ui.
- It provides user authentication (Supabase), subscription billing (Stripe), email notifications (Resend), and even an AI‐powered chat endpoint.

##### High‐Level File Structure Analysis
- **src/app/** – Next.js App Router pages and API routes:
- **/api/** – Serverless endpoints for AI chat, payments (create/cancel sessions), credits, email, Stripe webhooks
- **/auth/** – Auth pages (login, reset/update password), callback routes
- **/dashboard/** – Protected dashboard pages (analytics, billing, profile)
- Top-level pages (/, /pricing, /features, /docs)
- **src/components/** – Reusable UI components for auth flows, dashboard, common UI cards.
- **src/lib/** & **src/utils/** – Business‐logic helpers: email templates & sending, Supabase client/server wrappers.
- **supabase/migrations/** – SQL scripts to build your Postgres schema (users, profiles, subscriptions, credits).
- **configuration files** – Next.js (next.config.js), Tailwind (tailwind.config.js), ESLint, TypeScript, environment (.env.example).

##### Key Architecture Insights from README
- **Front‐end**: React/Tailwind/shadcn UI served by Next.js; fully responsive, SEO optimized, dark mode.
- **Back‐end (Server Actions & API Routes)**: Next.js serverless functions handle all dynamic business logic.
- **Database**: Supabase (Postgres) for auth, user profiles, subscriptions, credits.
- **Payments**: Stripe API for checkout sessions and webhooks.
- **Emails**: Resend API sends welcome/reset password emails.
- **External AI**: An AI chat endpoint (likely calls OpenAI or similar).

a. **Main Components**
- Web Client (Next.js React pages + assets)
- Next.js Server (Server Actions & API Routes)
- Supabase (Auth + Postgres DB)
- Stripe (Checkout, Webhook events)
- Resend (Email service)
- AI Service (external LLM endpoint)
b. **Data Flow & Interactions**
1. User → Web Client: requests pages, submits auth/login forms.
2. Web Client → Next.js API: calls /auth, /api/create-checkout-session, /api/ai/chat, etc.
3. Next.js API → Supabase: user sign‐up, session management, CRUD on profiles/subscriptions/credits.
4. Next.js API → Stripe: create checkout sessions, cancel subscriptions; Stripe → Next.js webhook for events.
5. Next.js API → Resend: send welcome/reset emails via library in src/lib/email.
6. Next.js API → AI Service: proxy chat requests and return LLM responses.
c. **Architectural Patterns**
- **Serverless Microservices**: each endpoint is an isolated function.
- **Layered Pattern**: UI layer → API layer → Service layer (lib/utils) → Data/External Services.
- **Third‐Party Integration Layer**: clean wrappers in lib/email and utils/supabase-*.
d. **Technologies & Frameworks**
- Next.js 15 (App Router, Server Actions)
- React + TypeScript + Tailwind CSS + shadcn/ui
- Supabase (Auth + Postgres)
- Stripe API & webhooks
- Resend API (email)
- Node.js runtime (serverless)

##### Detail Is Key – Don’t Overthink
- Break out the project into all logical components: pages, API domains (auth, billing, AI, email), service libraries, data stores, webhook listeners.
- Core workflows: signup → welcome email, login → dashboard, purchase → webhook updates credit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Client" 
        direction TB
        Home["Home<br>/page.tsx"]:::frontend
        Pricing["Pricing<br>/pricing/page.tsx"]:::frontend
        Features["Features<br>/features/page.tsx"]:::frontend
        Docs["Docs<br>/docs/page.tsx"]:::frontend
        Layout["Global Layout<br>& Globals"]:::frontend
        subgraph "Auth UI & Flows"
            direction TB
            AuthLogin["Login Page"]:::frontend
            AuthReset["Reset Password"]:::frontend
            AuthUpdate["Update Password"]:::frontend
            AuthCallback["Auth Callback"]:::frontend
        end
        subgraph "Dashboard (Protected)"
            direction TB
            DashboardRoot["Dashboard Home"]:::frontend
            Analytics["Analytics"]:::frontend
            BillingPage["Billing"]:::frontend
            Profile["Profile"]:::frontend
            ChatUI["Chat Component"]:::frontend
            Header["Dashboard Header"]:::frontend
        end
    end

    %% API Layer
    subgraph "Next.js API (Serverless)" 
        direction TB
        subgraph AuthAPI
            AuthAPI["/api/auth"]:::backend
        end
        subgraph BillingAPI
            CreateCheckout["Create Checkout Session"]:::backend
            CancelSub["Cancel Subscription"]:::backend
        end
        subgraph CreditsAPI
            Credits["Credits Management"]:::backend
        end
        subgraph EmailAPI
            WelcomeEmail["Send Welcome Email"]:::backend
        end
        subgraph Webhooks
            StripeWebhook["Stripe Webhook"]:::backend
        end
        AIChat["AI Chat Endpoint"]:::backend
    end

    %% Library & Utils
    subgraph "Service Layer (Lib/Utils)" 
        direction TB
        EmailService["Email Service & Templates"]:::service
        SupabaseClient["Supabase Client Helpers"]:::service
        SupabaseServer["Supabase Server Helpers"]:::service
        Utils["General Utilities"]:::service
    end

    %% Database
    subgraph "Database (Supabase/Postgres)"
        direction TB
        Postgres["Supabase Postgres"]:::database
        Migrations["Migrations Scripts"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Stripe["Stripe API"]:::external
        Resend["Resend Email Service"]:::external
        AIService["External AI Service"]:::external
    end

    %% Connections
    Home -->|"HTTP"| AuthAPI
    Pricing -->|"HTTP"| BillingAPI
    Features -->|"HTTP"| AIChat
    Docs -->|"HTTP"| CreditsAPI

    AuthLogin -->|"Form Submit"| AuthAPI
    AuthReset -->|"Form Submit"| AuthAPI
    AuthUpdate -->|"Form Submit"| AuthAPI
    AuthCallback -->|"OAuth Response"| AuthAPI

    DashboardRoot -->|"Fetch Data"| CreditsAPI
    Analytics -->|"Fetch Analytics"| AuthAPI
    BillingPage -->|"Manage Subscriptions"| BillingAPI
    Profile -->|"Update Profile"| AuthAPI
    ChatUI -->|"Chat Request"| AIChat
    Header -->|"User Session"| AuthAPI

    %% API to Services & DB
    AuthAPI -->|"RPC"| SupabaseClient
    AuthAPI -->|"RPC"| SupabaseServer
    CreateCheckout -->|"Calls"| Stripe
    CancelSub -->|"Calls"| Stripe
    StripeWebhook -->|"Webhook"| AuthAPI
    CreditsAPI -->|"CRUD"| Postgres
    WelcomeEmail -->|"Uses"| EmailService
    EmailService -->|"Sends"| Resend
    AIChat -->|"Proxy"| AIService

    %% Service to DB
    SupabaseClient -->|"Query"| Postgres
    SupabaseServer -->|"Query"| Postgres

    %% Migrations
    Migrations -->|"Schema Setup"| Postgres

    %% Click Events
    click Home "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/page.tsx"
    click Pricing "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/pricing/page.tsx"
    click Features "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/features/page.tsx"
    click Docs "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/docs/page.tsx"
    click Layout "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/layout.tsx"
    click AuthLogin "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/auth/page.tsx"
    click AuthReset "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/auth/reset-password/page.tsx"
    click AuthUpdate "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/auth/update-password/page.tsx"
    click AuthCallback "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/auth/callback/route.ts"
    click DashboardRoot "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/dashboard/page.tsx"
    click Analytics "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/dashboard/analytics/page.tsx"
    click BillingPage "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/dashboard/billing/page.tsx"
    click Profile "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/dashboard/profile/page.tsx"
    click ChatUI "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/components/dashboard/Chat.tsx"
    click Header "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/components/dashboard/Header.tsx"
    click AIChat "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/ai/chat/route.ts"
    click CreateCheckout "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/create-checkout-session/route.ts"
    click CancelSub "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/cancel-subscription/route.ts"
    click CreditsAPI "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/credits/route.ts"
    click WelcomeEmail "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/email/welcome/route.ts"
    click StripeWebhook "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/app/api/webhooks/stripe/route.ts"
    click EmailService "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/lib/email/index.ts"
    click EmailService "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/lib/email/send-welcome-email.ts"
    click EmailService "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/lib/email/templates/WelcomeEmail.tsx"
    click SupabaseClient "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/utils/supabase.ts"
    click SupabaseServer "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/utils/supabase-server.ts"
    click Utils "https://github.com/zainulabedeen123/best-saas-kit/blob/master/src/lib/utils.ts"
    click Migrations "https://github.com/zainulabedeen123/best-saas-kit/tree/master/supabase/migrations"
    click Postgres "https://github.com/zainulabedeen123/best-saas-kit/blob/master/supabase/migrations/20231212_community_tables.sql"
    click Postgres "https://github.com/zainulabedeen123/best-saas-kit/blob/master/supabase/migrations/20231213_users_table.sql"
    click Postgres "https://github.com/zainulabedeen123/best-saas-kit/blob/master/supabase/migrations/20240000000000_create_profiles.sql"
    click Postgres "https://github.com/zainulabedeen123/best-saas-kit/blob/master/supabase/migrations/20240000000001_create_subscriptions.sql"
    click Postgres "https://github.com/zainulabedeen123/best-saas-kit/blob/master/supabase/migrations/20240311_create_user_credits.sql"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#02457a,color:#02457a;
    classDef backend fill:#e0f7fa,stroke:#007c91,color:#007c91;
    classDef database fill:#ffe5b4,stroke:#cc7a00,color:#cc7a00;
    classDef external fill:#d4edda,stroke:#216e39,color:#216e39;
    classDef service fill:#f0f4c3,stroke:#9e9d24,color:#9e9d24;
```
