NextDevKit Project Architecture

A comprehensive guide to understanding NextDevKit's project structure, from basic Next.js setup to production-ready SaaS architecture.

This guide will help you understand how NextDevKit is organized by showing the evolution from a basic Next.js project to a complete production-ready SaaS template. Each step builds upon the previous one, making it easy to understand the rationale behind every architectural decision.

Understanding the Evolution

NextDevKit is designed as a production-ready starter template, which means it includes many features from day one. However, understanding how this structure evolved helps you:

Navigate the codebase with confidence
Extend features following established patterns
Make architectural decisions aligned with the project
Onboard new developers efficiently

Let's start from the beginning and build up to the complete architecture.

Step 1: Foundation - Next.js Basics

Every Next.js project starts with these essential files. This is the minimal setup you need to run a Next.js application.

layout.tsx

page.tsx

globals.css

next.config.ts

package.json

tsconfig.json

Key Files:

layout.tsx - Root layout wrapping all pages (global header, footer, metadata)
page.tsx - The homepage at /
globals.css - Global styles and Tailwind directives
next.config.ts - Next.js configuration
tsconfig.json - TypeScript configuration

Step 2: Adding Essential Tools

Before building features, we add development tools and styling foundations that ensure code quality and consistency.

We can run the following command to add more needed shadcn/ui base components:

pnpm dlx shadcn@latest add button input card

layout.tsx

page.tsx

globals.css

button.tsx

input.tsx

card.tsx

utils.ts

biome.json

components.json

next.config.ts

package.json

postcss.config.mjs

tsconfig.json

What's Added:

components/ui/ - shadcn/ui components (design system primitives)
lib/utils.ts - Utility functions (cn helper, formatters, etc.)
biome.json - Code formatting and linting configuration
components.json - shadcn/ui configuration
postcss.config.mjs - PostCSS configuration for Tailwind

Step 3: Organizing Routes with App Router

As the application grows, we organize routes using Next.js App Router patterns: route groups and internationalization.

layout.tsx

not-found.tsx

Architecture Patterns:

[locale]/ - Dynamic segment for internationalization (e.g., /en, /zh)
(marketing)/ - Route group for public pages (doesn't affect URL)
(app)/ - Route group for authenticated pages
[[...slug]] - Optional catch-all for flexible routing (docs)
[...slug] - Required catch-all for blog posts and legal pages

URL Examples:

/en/pricing → English pricing page
/zh/blog/nextdevkit-tech-stack → Chinese blog post
/en/docs/getting-started/overview → Documentation page
/en/credits → Credits pricing page
/auth/login → Login page (no locale needed)
/app/dashboard → Dashboard (protected route)
/app/admin/users → Admin users page
/app/ai/chat → AI chat feature

Step 4: Component Architecture

In addition to page routing, we also need to organize frontend component style files so we can better reuse these frontend components. All reusable frontend components are placed in the src/components/ directory.

Frontend Component Organization:

ui/ - Primitive, reusable UI components from shadcn/ui (More shadcn/ui components...)
auth/ - Authentication forms and components
marketing/ - Landing page and marketing components organized by feature
dashboard/ - Application dashboard layout component examples
settings/ - User settings forms organized by category (account, billing, notification, security, usage)
admin/ - Admin panel components
ai-elements/ - Vercel AI SDK related UI components (conversation, message, code-block, etc.)
shared/ - Shared across multiple features (header, footer, cookie, etc.)
docs/ & blog/ - MDX content components
examples/ - Example implementations (AI chat, AI image generation, dashboard examples)
icons/ - Logo, social media, and tech stack icons

Step 5: Content Management

MDX-based content management makes the APP easy to customize and maintain. Use MDX to build blog and documentation with internationalization support. All content is placed in the src/content/ directory.

en.json

zh.json

Configuration Structure:

content/ - MDX content for blog (8 posts), docs, and legal pages
i18n/ - Internationalization utilities
messages/ - Translation files (English and Chinese)

Step 6: Database and Authentication

The data layer and authentication system form the backbone of the application. You need to be familiar with Drizzle ORM and Better Auth usage to build your database and authentication system.

Database client and corresponding tables are placed in the src/database/ directory. Authentication related files are placed in the src/lib/auth/ directory.

auth.ts

utils.ts

metadata.ts

safe-action.ts

source.ts

toc.ts

urls.ts

i18n.ts

drizzle.config.ts

Database Layer:

database/client.ts - Drizzle ORM client instance
database/schema.ts - Database tables and relations (users, sessions, credits, transactions, etc.)
drizzle/ - Migration files and history

Authentication System:

lib/auth.ts - Better Auth configuration
lib/auth/client.ts - Client-side auth utilities (useSession, reloadSession)
lib/auth/server.ts - Server-side auth utilities (getSession)
lib/auth/api.ts - API route helpers
lib/auth/edge.ts - Edge runtime helpers
lib/auth/session-context.ts - React context for session
lib/auth/errors.ts - Auth error handling

Supporting Libraries:

lib/actions/ - Server actions for data mutations
lib/hooks/ - Custom React hooks
lib/stores/ - Zustand stores for global state
lib/safe-action.ts - Type-safe server action wrapper
lib/source.ts - Fumadocs source configuration
types/ - Shared TypeScript type definitions

Step 7: API Routes and Server Functions

Backend functionality is implemented through API routes and server actions. You need to be familiar with Next.js API routes, you can create new /api/**/route.ts to implement your API routes.

robots.ts

sitemap.ts

middleware.ts

API Routes:

api/auth/[...all]/route.ts - Better Auth API handler (catch-all route)
api/ai/demo/chat/route.ts - AI chat demo endpoint
api/ai/demo/image/route.ts - AI image generation demo endpoint
api/search/route.ts - Documentation search functionality
api/jobs/credits/expire/route.ts - Cron job to expire credits
api/jobs/credits/grant/route.ts - Cron job to grant subscription credits
api/webhooks/stripe/route.ts - Stripe webhook handler
api/webhooks/creem/route.ts - Creem webhook handler

Special Routes:

image-proxy/[...path]/route.ts - Image proxy for optimization
robots.ts - Dynamic robots.txt generation
sitemap.ts - Dynamic sitemap generation

Middleware:

middleware.ts - Route protection, redirects, internationalization

Step 8: Business Logic Modules

Enterprise features like AI, credits, payments, email, and storage are organized as modular systems. You need to be familiar with these modules usage to build your business logic.

ai/ - AI related files are placed in src/ai/ directory.
credits/ - Credits related files are placed in src/credits/ directory.
payment/ - Payment related files are placed in src/payment/ directory.
mail/ - Mail related files are placed in src/mail/ directory.
storage/ - Storage related files are placed in src/storage/ directory.

AI System:

ai/models/ - AI model configurations (chat, image)
ai/agents/ - AI agents and tools (weather agent)
ai/image/ - Image generation utilities and hooks
ai/prompts.ts - System prompts and templates
ai/errors.ts - AI-specific error handling

Credits System:

credits/actions/ - Server actions for credits management (10+ action files)
- Consume, grant, expire credits
- Track user transactions
- Handle subscription and purchase bonuses
credits/types.ts - Credits-related TypeScript types

Payment System:

payment/actions/ - Server actions for payment operations (10 action files)
- Create checkout links and customer portals
- Handle subscriptions and one-time payments
- Process webhooks from payment providers
payment/providers/ - Payment provider implementations (Stripe, Creem)
payment/types.ts - Payment-related TypeScript types

Email System:

mail/providers/resend.ts - Resend email service integration
mail/templates/ - React Email templates
mail/components/ - Reusable email components (button, layout)
mail/actions.ts - Newsletter subscriptions, email sending

Storage System:

storage/providers/s3.ts - AWS S3 storage integration
storage/actions.ts - File upload, signed URLs

Provider Pattern Benefits:

Easy to add new providers by implementing the same interface
Test with mock providers
Support multiple payment providers simultaneously (Stripe + Creem)
Consistent API across different services

Step 9: Complete Production Architecture

The final architecture includes all pieces working together for a production-ready SaaS application.

images, fonts, icons, manifests

i18n translation files

migration files and metadata

Architecture Principles

NextDevKit follows these core principles to maintain quality and scalability:

1. Separation of Concerns

Presentation Layer (components/):

UI components that render interfaces
No direct database or business logic
Use hooks and actions for data

Business Logic Layer (ai/, credits/, payment/, mail/):

Server actions for data mutations
Business rules and validations
Integration with external services

Data Layer (database/):

Database schema definitions
Data models and relationships
Migration management

2. Configuration Over Code

Centralized config - Change behavior without touching components
Type-safe configuration - TypeScript ensures correctness
Environment-based - Different configs for dev/staging/production

3. Modular Architecture

Independent modules - AI, credits, payment, mail, storage are self-contained
Provider pattern - Easy to implement your own providers
Feature folders - Related code stays together