ShipNowKit uses a standard Next.js App Router project structure, optimized for SaaS applications. This document will help you quickly understand the overall layout of the codebase and the responsibilities of each directory.

Basic Repository Structure

ShipNowKit is a single-repository (monorepo) Next.js application that primarily contains the following directories:

Main Directory Overview

app/ - Next.js Application Directory

The app/ directory follows Next.js 16 App Router conventions and contains all routes and page components:

• [locale]/ - Internationalized routes directory

  • page.tsx - Homepage (marketing landing page)
  • blog/ - Blog-related pages
  • docs/ - Documentation pages
  • dashboard/ - User dashboard
  • signin/, register/ - Sign-in and registration pages
  • payment/ - Payment-related pages
  • policies/ - Privacy policy and terms pages

• api/ - API routes directory

  • auth/ - Authentication-related APIs (Better Auth proxy)
  • dashboard/ - Dashboard management APIs
  • payment/ - Payment webhook handlers
  • search/ - Search functionality API

• _templates/ - Template files directory

  • T1/ - Page components for template T1
  • T2/ - Page components for template T2
  • Each template includes independent page layouts and styles

• layout.tsx - Root layout component, includes global configuration and theme providers

components/ - Component Library

Reusable React components organized by functional modules:

• auth/ - Authentication-related components

  • SignInButton.tsx - Sign-in button
  • SignOutButton.tsx - Sign-out button
  • SignedIn.tsx - Signed-in state check component

• dashboard/ - Dashboard components

  • app-sidebar.tsx - Sidebar navigation
  • data-table.tsx - Data table component
  • InvoiceDialog.tsx - Invoice dialog
  • settings/ - Settings page related components

• price/ - Pricing and payment components

  • PriceBtn.tsx - Price button
  • paddle/ - Paddle payment-related components
  • hooks/ - Custom hooks for pricing

• ui/ - Base UI components (based on shadcn/ui)

  • button.tsx, card.tsx, dialog.tsx, and other base components
  • All components support theme switching (dark/light mode)

• T1/, T2/ - Template-specific components

  • Each template has independent Hero, Feature, Price, FAQ, and other components

config/ - Configuration Files

Centralized application configuration management:

• site.ts - Site metadata configuration

  • Website name, title, description
  • Open Graph and Twitter Card configuration
  • Social media account links
  • Icon and logo configuration

• index.ts - Core functionality configuration

  • authConfig - Authentication-related configuration (sign-in page path, etc.)
  • paymentConfig - Payment-related configuration (payment provider, success page, etc.)

• languages.ts - Internationalization configuration

  • List of supported languages
  • Language codes, names, flags, and locales

• types.ts - TypeScript type definitions for configuration

content/ - Content Directory

MDX-format documentation and blog content managed with Fumadocs:

• docs/ - Documentation content

  • meta.json - Documentation navigation configuration
  • *.mdx - Documentation files for each section
  • Supports multiple language versions (.en.mdx, .zh.mdx)

• blog/ - Blog posts

  • meta.json - Blog metadata
  • Articles organized by category
  • Also supports multiple languages

db/ - Database Related

Prisma ORM and database service layer:

• prisma/ - Prisma configuration

  • schema.prisma - Database model definitions
  • variants/ - Schema variants for different databases
    • mysql.prisma, postgresql.prisma, sqlite.prisma, mongodb.prisma
  • migrations/ - Database migration files

• services/ - Database service layer

  • user.ts - User-related database operations
  • subscription.ts - Subscription management
  • oneTimePayment.ts - One-time payments
  • order.ts - Order management
  • price.ts - Price configuration
  • customer.ts - Customer information
  • stats.ts - Statistics data
  • config.ts - System configuration

lib/ - Core Logic Library

Core business logic and utility functions for the application:

• actions/ - Server Actions

  • auth.ts - Authentication-related server operations
  • payment.ts - Payment-related server operations
  • user.ts - User management operations
  • email.ts - Email sending operations

• payment/ - Payment integrations

  • stripe/ - Stripe payment integration
    • client.ts - Stripe client configuration
    • server.ts - Server-side payment logic
    • config.ts - Stripe configuration
  • paddle/ - Paddle payment integration
    • server.ts - Paddle server-side logic
    • config.ts - Paddle configuration
  • utils.ts - Payment utility functions

• auth/ - Authentication core logic

  • index.ts - Better Auth main configuration
  • config-loader.ts - Configuration loader
  • proxy.ts - Authentication proxy

• utils/ - Utility functions

  • encryption.ts - Encryption utilities
  • utils.ts - General utility functions
  • zod.ts - Zod validation utilities

• admin.ts - Admin permission checks

• config-manager.ts - Configuration manager

• logger.ts - Logging utilities

messages/ - Internationalization Translation Files

Internationalization using next-intl:

• en.json - English translations
• zh.json - Chinese translations

All user interface text is managed through translation files, making it easy to add support for new languages.

emailTemplate/ - Email Templates

Email templates built with React Email:

• verification/ - Email verification templates

  • ShipNow.tsx - ShipNow-style verification email
  • registry.ts - Template registry

• magicLinks/ - Magic Link email templates

  • NotionLike.tsx - Notion-style Magic Link email
  • registry.ts - Template registry

scripts/ - Utility Scripts

Node.js scripts for project maintenance and development:

• switch-database.js - Switch database type
• switch-template.js - Switch page template
• create-test-user.js - Create test user
• test-subscription-renewal.js - Test subscription renewal
• cleanup-stripe-test-data.js - Clean up Stripe test data
• custom_stripe_billing_portal.js - Stripe billing portal configuration

public/ - Static Assets

Static files directory:

• logo.svg - Website logo
• favicon.ico - Website icon
• T1/, T2/ - Template-specific image resources
• paddle/ - Paddle-related resources
• social-icons/ - Social media icons

Other Important Files

• mdx-components.tsx - MDX component configuration for the documentation system
• next.config.mjs - Next.js configuration file
• tsconfig.json - TypeScript configuration
• tailwind.config.ts - Tailwind CSS configuration
• package.json - Project dependencies and script configuration

Directory Organization Principles

ShipNowKit's directory organization follows these principles:

1. Organized by Functional Modules: Related functionality is grouped in the same directory (e.g., components/auth/, lib/payment/)
2. Convention over Configuration: Follows Next.js and React best practices
3. Extensibility: Template system and multi-database support facilitate expansion
4. Type Safety: Uses TypeScript to ensure type safety
5. Internationalization First: Multi-language support considered from the design stage