A comprehensive guide to the architecture and core features of ShipNowKit, built with Next.js 16 and React 19.

ShipNowKit Project Architecture and Core Features Guide

Overview

ShipNowKit is a modern SaaS application boilerplate built with Next.js 16 and React 19. This guide provides an in-depth analysis of the project's architecture, core modules, and technical implementation details.

1. Technology Stack

1.1 Frontend Stack

Next.js 16: App Router architecture
React 19
TypeScript: Provides type safety and better development experience
TailwindCSS v4: Utility-first CSS framework
shadcn/ui: Modern component library based on Radix UI
Framer Motion: Smooth animation library

1.2 Backend Stack

Better Auth: Next-generation authentication solution
Prisma ORM: Modern database toolkit supporting multiple databases
Server Actions: Next.js server-side actions for simplified data processing
Winston: Enterprise-grade logging system

1.3 Database Support

SQLite (development default)
PostgreSQL
MySQL
MongoDB

1.4 Payment Systems

Stripe: Complete payment processing platform
Paddle: Alternative payment provider
Unified payment interface design

1.5 Additional Services

React Email: Email template system
Resend: Email delivery service
next-intl: Internationalization support
Vercel Analytics: Website analytics

2. Project Directory Structure

shipnow-boilerplate/
├── app/                    # Next.js App Router application directory
│   ├── [locale]/          # Internationalized routes
│   │   ├── docs/          # Documentation pages
│   │   ├── page.tsx       # Homepage
│   │   ├── signin/        # Sign-in page
│   │   ├── register/      # Registration page
│   │   ├── payment/       # Payment-related pages
│   │   └── policies/      # Policy pages
│   ├── api/               # API routes
│   │   ├── auth/          # Authentication API
│   │   ├── payment/       # Payment API
│   │   └── search/        # Search API
│   ├── _templates/        # Template system
│   │   ├── T1/            # Template T1
│   │   └── T2/            # Template T2
│   └── layout.tsx         # Root layout
├── components/             # React components
│   ├── auth/              # Authentication components
│   ├── payment/           # Payment components
│   ├── ui/                # shadcn/ui base components
│   ├── feature/           # Feature components
│   ├── header/            # Header components
│   ├── footer/            # Footer components
│   └── hero/              # Hero section components
├── config/                # Configuration files
│   ├── site.ts            # Site configuration
│   ├── index.ts           # Main configuration
│   ├── languages.ts       # Language configuration
│   └── types.ts           # Type definitions
├── lib/                   # Utility libraries
│   ├── actions/           # Server Actions
│   ├── payment/           # Payment integrations (Stripe/Paddle)
│   ├── auth-client.ts     # Authentication client
│   ├── logger.ts          # Logging utilities
│   └── utils.ts           # General utilities
├── db/                    # Database
│   ├── prisma/            # Prisma configuration
│   ├── services/          # Database services
│   ├── client.ts          # Database client
│   └── types.ts           # Database types
├── content/               # Content management
│   └── docs/              # Documentation content
├── messages/              # Internationalization messages
│   ├── en.json            # English messages
│   └── zh.json            # Chinese messages
├── public/                # Static assets
├── styles/                # Style files
└── providers/             # React providers

3. Core Functional Modules

3.1 Authentication System

ShipNowKit uses Better Auth as the authentication solution.

3.1.1 Multiple Authentication Methods

OAuth Providers: Google, GitHub, Apple, Discord, Facebook, LinkedIn, Slack, Twitter
Email/Password Authentication: Traditional username/password login
Magic Links: Passwordless email login

3.1.2 Client Usage

import { useSession, signIn, signOut } from "@/lib/auth-client";

export function Protected({ children }: { children: React.ReactNode }) {
  const { data, status } = useSession();
  if (status === "loading") return null;
  if (!data) return <button onClick={() => signIn("google")}>Sign In</button>;
  return <>{children}</>;
}

3.1.3 Session Management

JWT token strategy
Secure cookie configuration
Automatic session refresh
Cross-domain SSO support

3.2 Payment System

3.2.1 Unified Payment Interface

ShipNowKit provides unified checkout flows for Stripe and Paddle.

3.2.2 Stripe Integration

Subscription management
One-time payments
Customer portal
Webhook handling

3.2.3 Paddle Integration

Alternative payment solution
Global tax handling
Multi-currency support

3.3 Database Architecture

3.3.1 Prisma Model Design

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  
  // Relationships
  sessions      Session[]
  subscriptions Subscription[]
  payments      OneTimePayment[]
}

model Subscription {
  id                String            @id @default(cuid())
  userId            String
  stripeCustomerId  String?
  paddleCustomerId  String?
  status            SubscriptionStatus
  currentPeriodEnd  DateTime?
  
  user User @relation(fields: [userId], references: [id])
}

3.3.2 Database Service Layer

// User service example
export async function createUser(data: CreateUserData) {
  return await prisma.user.create({
    data: {
      email: data.email,
      name: data.name,
      // Other fields
    },
  });
}

3.4 Internationalization System

3.4.1 Multi-language Support

Implemented with next-intl
Supports Chinese and English
Dynamic language switching
Localized routing

3.4.2 Message Management

// messages/en.json
{
  "auth": {
    "signin": "Sign In",
    "signup": "Sign Up",
    "signout": "Sign Out"
  },
  "payment": {
    "subscribe": "Subscribe",
    "cancel": "Cancel Subscription"
  }
}

3.5 Template System

3.5.1 Multi-template Architecture

ShipNowKit provides two complete template sets:

ShipNowLike: Modern minimalist style
NotionLike: Notion-style design

3.5.2 Template Switching

npm run template:t1
npm run template:t2

4. Core Component Details

4.1 Authentication Components

4.1.1 SignInButton Component

export function SignInButton({ provider }: { provider: string }) {
  const handleSignIn = async () => {
    await signIn(provider);
  };

  return (
    <button onClick={handleSignIn}>
      Sign in with {provider}
    </button>
  );
}

4.1.2 Protected Route Component

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { data: session, status } = useSession();

  if (status === "loading") return <div>Loading...</div>;
  if (!session) redirect("/signin");

  return <>{children}</>;
}

4.2 Payment Components

4.2.1 Price Button Component

import { PriceBtn } from "@/components/price/PriceBtn";

export function Pricing({ plans }: { plans: any[] }) {
  return (
    <div>
      {plans.map((p) => (
        <PriceBtn key={p.id} btnText="Subscribe" targetPlan={{ isSubscription: true, priceId: p.priceId }} activePlans={[]} />
      ))}
    </div>
  );
}

4.3 UI Components

4.3.1 Theme Toggle Component

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
    >
      {theme === "dark" ? <Sun /> : <Moon />}
    </button>
  );
}

5. API Route Design

5.1 Authentication API

5.1.1 Auth Routes

Better Auth routes are mounted under app/api/auth/[...all]/route.ts.

5.2 Payment API

5.2.1 Checkout

Stripe checkout is initiated via server actions in lib/payment/stripe/server.ts. Paddle checkout uses a route at app/[locale]/payment/paddle/checkout/[priceId]/page.tsx.

5.3 Webhook Handling

5.3.1 Stripe Webhook

// app/api/payment/stripe/webhook/route.ts
export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature')!;

  try {
    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    await handleStripeEvent(event);
    
    return NextResponse.json({ received: true });
  } catch (error) {
    return NextResponse.json({ error: "Webhook processing failed" }, { status: 400 });
  }
}

6. Configuration Management

6.1 Environment Variables Configuration

# Database
DATABASE_URL="sqlite:./dev.db"

# Authentication
BETTER_AUTH_SECRET="your-secret-key"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Payment
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Email
RESEND_API_KEY="re_..."

6.2 Site Configuration

// config/site.ts
export const siteConfig = {
  name: "ShipNowKit",
  description: "Modern SaaS application boilerplate",
  url: "https://shipnowkit.com",
  ogImage: "https://shipnowkit.com/og.jpg",
  links: {
    twitter: "https://twitter.com/shipnowkit",
    github: "https://github.com/shipnowkit",
  },
};

7. Development Tools and Scripts

7.1 Database Management Scripts

{
  "scripts": {
    "db:generate": "prisma generate",
    "db:studio": "prisma studio",
    "db:migrate": "prisma migrate dev",
    "db:use:mysql": "node scripts/switch-database.js mysql",
    "db:use:postgresql": "node scripts/switch-database.js postgresql"
  }
}

7.2 Development Server

# Start development server
npm run dev

# Build production version
npm run build

# Start production server
npm start

8. Best Practices

8.1 Code Organization

Component Layering: Organize components by functional modules
Type Safety: Fully utilize TypeScript type system
Error Handling: Unified error handling mechanism
Logging: Use Winston for structured logging

8.2 Performance Optimization

Server Components: Prioritize React Server Components
Code Splitting: Automatic code splitting by routes
Image Optimization: Use Next.js Image component
Caching Strategy: Reasonable use of caching mechanisms

8.3 Security Considerations

Environment Variables: Use environment variables for sensitive information
CSRF Protection: Built-in CSRF protection mechanism
Input Validation: Use Zod for data validation
Session Security: Secure session management

Summary

ShipNowKit provides a complete, modern SaaS application development framework. Through modular architectural design, unified interface specifications, and rich functional components, developers can quickly build high-quality SaaS applications.

The next guide will detail the in-depth configuration and best practices of the authentication system.

ShipNowKit Project Architecture and Core Features Guide

Overview

1. Technology Stack

1.1 Frontend Stack

Next.js 16: App Router architecture
React 19
TypeScript: Provides type safety and better development experience
TailwindCSS v4: Utility-first CSS framework
shadcn/ui: Modern component library based on Radix UI
Framer Motion: Smooth animation library

1.2 Backend Stack

Better Auth: Next-generation authentication solution
Prisma ORM: Modern database toolkit supporting multiple databases
Server Actions: Next.js server-side actions for simplified data processing
Winston: Enterprise-grade logging system

1.3 Database Support

SQLite (development default)
PostgreSQL
MySQL
MongoDB

1.4 Payment Systems

Stripe: Complete payment processing platform
Paddle: Alternative payment provider
Unified payment interface design

1.5 Additional Services

React Email: Email template system
Resend: Email delivery service
next-intl: Internationalization support
Vercel Analytics: Website analytics

2. Project Directory Structure

shipnow-boilerplate/
├── app/                    # Next.js App Router application directory
│   ├── [locale]/          # Internationalized routes
│   │   ├── docs/          # Documentation pages
│   │   ├── page.tsx       # Homepage
│   │   ├── signin/        # Sign-in page
│   │   ├── register/      # Registration page
│   │   ├── payment/       # Payment-related pages
│   │   └── policies/      # Policy pages
│   ├── api/               # API routes
│   │   ├── auth/          # Authentication API
│   │   ├── payment/       # Payment API
│   │   └── search/        # Search API
│   ├── _templates/        # Template system
│   │   ├── T1/            # Template T1
│   │   └── T2/            # Template T2
│   └── layout.tsx         # Root layout
├── components/             # React components
│   ├── auth/              # Authentication components
│   ├── payment/           # Payment components
│   ├── ui/                # shadcn/ui base components
│   ├── feature/           # Feature components
│   ├── header/            # Header components
│   ├── footer/            # Footer components
│   └── hero/              # Hero section components
├── config/                # Configuration files
│   ├── site.ts            # Site configuration
│   ├── index.ts           # Main configuration
│   ├── languages.ts       # Language configuration
│   └── types.ts           # Type definitions
├── lib/                   # Utility libraries
│   ├── actions/           # Server Actions
│   ├── payment/           # Payment integrations (Stripe/Paddle)
│   ├── auth-client.ts     # Authentication client
│   ├── logger.ts          # Logging utilities
│   └── utils.ts           # General utilities
├── db/                    # Database
│   ├── prisma/            # Prisma configuration
│   ├── services/          # Database services
│   ├── client.ts          # Database client
│   └── types.ts           # Database types
├── content/               # Content management
│   └── docs/              # Documentation content
├── messages/              # Internationalization messages
│   ├── en.json            # English messages
│   └── zh.json            # Chinese messages
├── public/                # Static assets
├── styles/                # Style files
└── providers/             # React providers

3. Core Functional Modules

3.1 Authentication System

ShipNowKit uses Better Auth as the authentication solution.

3.1.1 Multiple Authentication Methods

OAuth Providers: Google, GitHub, Apple, Discord, Facebook, LinkedIn, Slack, Twitter
Email/Password Authentication: Traditional username/password login
Magic Links: Passwordless email login

3.1.2 Client Usage

import { useSession, signIn, signOut } from "@/lib/auth-client";

export function Protected({ children }: { children: React.ReactNode }) {
  const { data, status } = useSession();
  if (status === "loading") return null;
  if (!data) return <button onClick={() => signIn("google")}>Sign In</button>;
  return <>{children}</>;
}

3.1.3 Session Management

JWT token strategy
Secure cookie configuration
Automatic session refresh
Cross-domain SSO support

3.2 Payment System

3.2.1 Unified Payment Interface

ShipNowKit provides unified checkout flows for Stripe and Paddle.

3.2.2 Stripe Integration

Subscription management
One-time payments
Customer portal
Webhook handling

3.2.3 Paddle Integration

Alternative payment solution
Global tax handling
Multi-currency support

3.3 Database Architecture

3.3.1 Prisma Model Design

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  
  // Relationships
  sessions      Session[]
  subscriptions Subscription[]
  payments      OneTimePayment[]
}

model Subscription {
  id                String            @id @default(cuid())
  userId            String
  stripeCustomerId  String?
  paddleCustomerId  String?
  status            SubscriptionStatus
  currentPeriodEnd  DateTime?
  
  user User @relation(fields: [userId], references: [id])
}

3.3.2 Database Service Layer

// User service example
export async function createUser(data: CreateUserData) {
  return await prisma.user.create({
    data: {
      email: data.email,
      name: data.name,
      // Other fields
    },
  });
}

3.4 Internationalization System

3.4.1 Multi-language Support

Implemented with next-intl
Supports Chinese and English
Dynamic language switching
Localized routing

3.4.2 Message Management

// messages/en.json
{
  "auth": {
    "signin": "Sign In",
    "signup": "Sign Up",
    "signout": "Sign Out"
  },
  "payment": {
    "subscribe": "Subscribe",
    "cancel": "Cancel Subscription"
  }
}

3.5 Template System

3.5.1 Multi-template Architecture

ShipNowKit provides two complete template sets:

ShipNowLike: Modern minimalist style
NotionLike: Notion-style design

3.5.2 Template Switching

npm run template:t1
npm run template:t2

4. Core Component Details

4.1 Authentication Components

4.1.1 SignInButton Component

export function SignInButton({ provider }: { provider: string }) {
  const handleSignIn = async () => {
    await signIn(provider);
  };

  return (
    <button onClick={handleSignIn}>
      Sign in with {provider}
    </button>
  );
}

4.1.2 Protected Route Component

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { data: session, status } = useSession();

  if (status === "loading") return <div>Loading...</div>;
  if (!session) redirect("/signin");

  return <>{children}</>;
}

4.2 Payment Components

4.2.1 Price Button Component

import { PriceBtn } from "@/components/price/PriceBtn";

export function Pricing({ plans }: { plans: any[] }) {
  return (
    <div>
      {plans.map((p) => (
        <PriceBtn key={p.id} btnText="Subscribe" targetPlan={{ isSubscription: true, priceId: p.priceId }} activePlans={[]} />
      ))}
    </div>
  );
}

4.3 UI Components

4.3.1 Theme Toggle Component

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
    >
      {theme === "dark" ? <Sun /> : <Moon />}
    </button>
  );
}

// app/api/payment/stripe/webhook/route.ts
export async function POST(request: Request) {
  const body = await request.text();
  const signature = request.headers.get('stripe-signature')!;

  try {
    const event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    await handleStripeEvent(event);
    
    return NextResponse.json({ received: true });
  } catch (error) {
    return NextResponse.json({ error: "Webhook processing failed" }, { status: 400 });
  }
}

6. Configuration Management

6.1 Environment Variables Configuration

# Database
DATABASE_URL="sqlite:./dev.db"

# Authentication
BETTER_AUTH_SECRET="your-secret-key"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Payment
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Email
RESEND_API_KEY="re_..."

6.2 Site Configuration

// config/site.ts
export const siteConfig = {
  name: "ShipNowKit",
  description: "Modern SaaS application boilerplate",
  url: "https://shipnowkit.com",
  ogImage: "https://shipnowkit.com/og.jpg",
  links: {
    twitter: "https://twitter.com/shipnowkit",
    github: "https://github.com/shipnowkit",
  },
};

7. Development Tools and Scripts

7.1 Database Management Scripts

{
  "scripts": {
    "db:generate": "prisma generate",
    "db:studio": "prisma studio",
    "db:migrate": "prisma migrate dev",
    "db:use:mysql": "node scripts/switch-database.js mysql",
    "db:use:postgresql": "node scripts/switch-database.js postgresql"
  }
}

7.2 Development Server

# Start development server
npm run dev

# Build production version
npm run build

# Start production server
npm start

8. Best Practices

8.1 Code Organization

Component Layering: Organize components by functional modules
Type Safety: Fully utilize TypeScript type system
Error Handling: Unified error handling mechanism
Logging: Use Winston for structured logging

8.2 Performance Optimization

Server Components: Prioritize React Server Components
Code Splitting: Automatic code splitting by routes
Image Optimization: Use Next.js Image component
Caching Strategy: Reasonable use of caching mechanisms

8.3 Security Considerations

Environment Variables: Use environment variables for sensitive information
CSRF Protection: Built-in CSRF protection mechanism
Input Validation: Use Zod for data validation
Session Security: Secure session management

Summary

The next guide will detail the in-depth configuration and best practices of the authentication system.

ShipNowKit Project Architecture and Core Features Guide

On this page

ShipNowKit Project Architecture and Core Features Guide

On this page