Project Structure

NextShip follows a well-organized structure optimized for scalability.

Directory Overview

├── config/                 # Configuration files
│   └── rbac-defaults.json  # Default RBAC policies
├── content/                # MDX content
│   ├── blog/               # Blog posts
│   └── docs/               # Documentation
├── public/                 # Static assets
├── scripts/                # Build & deployment scripts
└── src/
    ├── app/
    │   ├── [locale]/
    │   │   ├── (auth)/           # Auth pages
    │   │   │   ├── login/
    │   │   │   ├── register/
    │   │   │   └── forgot-password/
    │   │   ├── (dashboard)/      # Protected pages
    │   │   │   ├── dashboard/    # Main dashboard
    │   │   │   ├── users/        # User management (admin)
    │   │   │   ├── audit-logs/   # System logs (admin)
    │   │   │   ├── emails/       # Email logs (admin)
    │   │   │   ├── payments/     # Payment history (admin)
    │   │   │   ├── skus/         # Credit packages (admin)
    │   │   │   ├── api-pricing/  # API pricing (admin)
    │   │   │   ├── permissions/  # RBAC management (admin)
    │   │   │   ├── settings/     # User settings
    │   │   │   ├── billing/      # Subscription management
    │   │   │   ├── credits/      # Credit balance
    │   │   │   ├── api-keys/     # API key management
    │   │   │   └── files/        # File storage
    │   │   └── (marketing)/      # Public pages
    │   │       ├── pricing/
    │   │       ├── blog/
    │   │       ├── docs/
    │   │       └── contact/
    │   └── api/                  # API Routes
    │       ├── auth/             # Better Auth endpoints
    │       ├── stripe/           # Stripe webhooks
    │       ├── creem/            # Creem webhooks
    │       └── v1/               # Public API (AI Gateway)
    │
    ├── components/
    │   ├── ui/             # shadcn/ui components
    │   ├── layout/         # Layout components (sidebar, header)
    │   ├── billing/        # Billing components
    │   ├── files/          # File management components
    │   └── shared/         # Shared components
    │
    ├── server/
    │   └── actions/        # Server Actions
    │       ├── admin.ts    # Admin user management
    │       ├── audit.ts    # Audit logging
    │       ├── credits.ts  # Credit operations
    │       ├── email.ts    # Email logs
    │       ├── files.ts    # File operations
    │       ├── permission.ts # RBAC operations
    │       ├── skus.ts     # SKU management
    │       └── ...
    │
    ├── lib/
    │   ├── db/             # Database
    │   │   ├── index.ts    # Drizzle client
    │   │   └── schema.ts   # Table definitions
    │   ├── casbin/         # RBAC with Casbin
    │   │   ├── enforcer.ts # Casbin enforcer
    │   │   └── adapter.ts  # Database adapter
    │   ├── payment/        # Payment providers
    │   │   ├── stripe.ts
    │   │   └── creem.ts
    │   ├── ai-gateway/     # AI API proxy
    │   ├── auth.ts         # Better Auth config
    │   ├── auth-client.ts  # Client-side auth
    │   ├── permissions.ts  # Permission helpers
    │   ├── mail.ts         # Email sending
    │   └── utils.ts        # Utility functions
    │
    ├── hooks/              # Custom React hooks
    ├── i18n/               # Internationalization
    ├── messages/           # Translation files (en/zh)
    ├── mail/               # Email templates
    │   ├── templates/      # React Email templates
    │   └── components/     # Email components
    └── types/              # TypeScript definitions

Route Groups

Next.js uses route groups to organize pages:

`(auth)` - Authentication Pages

/login - Sign in page
/register - Sign up page
/forgot-password - Password reset

`(dashboard)` - Protected Pages

Requires authentication. Includes sidebar layout.

User Pages:

/dashboard - Main dashboard with stats
/settings - Profile and account settings
/billing - Subscription management
/credits - Credit balance and purchase
/api-keys - API key management
/files - File storage

Admin Pages (requires admin role):

/users - User management
/audit-logs - System audit logs
/emails - Email logs and subscribers
/payments - Payment history
/skus - Credit package management
/api-pricing - API pricing configuration
/permissions - RBAC policy management

`(marketing)` - Public Pages

Public-facing pages for marketing.

/pricing - Pricing plans
/blog - Blog listing
/docs - Documentation
/contact - Contact form

Key Files

File	Purpose
`src/lib/auth.ts`	Better Auth configuration
`src/lib/db/schema.ts`	Database table definitions
`src/lib/permissions.ts`	Permission check helpers
`src/lib/casbin/enforcer.ts`	Casbin RBAC enforcer
`config/rbac-defaults.json`	Default RBAC policies
`src/i18n/config.ts`	Supported locales

Adding New Features

New Page: Add to appropriate route group in src/app/[locale]/
New Component: Add to src/components/ (ui/ for primitives, shared/ for reusable)
New Server Action: Add to src/server/actions/
New DB Table: Add to src/lib/db/schema.ts, run pnpm db:push
New Permission: Add policy in admin dashboard or config/rbac-defaults.json