Project Structure Guide

Understand NextJS Base Directory Structure in 5 Minutes

Directory Overview · Core Directories · Naming Conventions

📁 Directory Overview

nextjs-base/
│
├── 📂 app/                         # Next.js App Router
│   ├── 📂 (admin)/                # Admin Panel Module
│   │   ├── 📂 admin/              # Admin Pages
│   │   ├── 📂 actions/            # Admin Server Actions
│   │   ├── layout.js              # Admin Layout
│   │   └── admin-styles.css      # Admin Styles
│   │
│   ├── 📂 (client)/               # Frontend Module
│   │   ├── 📂 [locale]/           # Multi-language Routes
│   │   └── 📂 actions/            # Frontend Server Actions
│   │
│   ├── 📂 api/                    # API Routes
│   │   ├── 📂 auth/               # Authentication API
│   │   ├── 📂 upload/             # Upload API
│   │   └── 📂 v1/                 # REST API v1
│   │
│   ├── globals.css                # Global Styles
│   └── page.js                    # Root Page (Redirect)
│
├── 📂 components/                  # React Components
│   ├── 📂 admin/                  # Admin Components
│   ├── 📂 client/                 # Frontend Components
│   ├── 📂 common/                 # Common Components
│   ├── 📂 motion/                 # Animation Components
│   └── 📂 ui/                     # UI Base Components
│
├── 📂 lib/                        # Core Library
│   ├── 📂 api/                    # API Utilities
│   ├── 📂 auth/                   # Authentication
│   ├── 📂 core/                   # Core Features
│   ├── 📂 database/               # Database Utilities
│   ├── 📂 function/               # Utility Functions (nb.pubfn)
│   ├── 📂 logging/                # Logging System
│   ├── 📂 upload/                 # Upload Utilities
│   └── 📂 validation/             # Validation Utilities
│
├── 📂 prisma/                     # Prisma ORM
│   └── schema.prisma              # Database Model Definition
│
├── 📂 i18n/                       # Internationalization
│   ├── 📂 messages/               # Translation Files
│   ├── config.js                  # i18n Configuration
│   └── request.js                 # Request Configuration
│
├── 📂 templates/                  # Development Templates
│   └── 📂 crud/                   # CRUD Templates
│
├── 📂 docs/                       # Project Documentation
├── 📂 public/                     # Static Assets
├── 📂 hooks/                      # React Hooks
├── 📂 config/                     # Configuration Files
└── 📂 scripts/                    # Script Tools

🎯 Core Directories

`app/(admin)/` - Admin Panel

app/(admin)/
├── admin/                          # Pages Directory
│   ├── rbac/                       # RBAC Permission Management
│   │   ├── roles/page.js          # Role Management
│   │   ├── permissions/page.js    # Permission Management
│   │   ├── menus/page.js          # Menu Management
│   │   └── users/page.js          # User Management
│   │
│   ├── system/                     # System Management
│   │   ├── action_logs/page.js    # Action Logs
│   │   └── assets/page.js         # Asset Management
│   │
│   └── [your-module]/              # Your Module
│       └── [resource]/page.js
│
├── actions/                        # Server Actions
│   ├── dao/                        # Data Access Object
│   │   └── base.js                # BaseDAO
│   │
│   ├── rbac/                       # RBAC Actions
│   │   ├── crud-action.role.js
│   │   ├── crud-action.permission.js
│   │   └── crud-action.menu.js
│   │
│   └── [module]/                   # Your Module
│       └── crud-action.[resource].js
│
├── layout.js                       # Admin Layout
└── admin-styles.css               # Admin Styles

Naming Conventions

Type	Convention	Example
Page Directory	Plural Form	`roles/`, `users/`, `posts/`
Action File	`crud-action.{resource}.js`	`crud-action.role.js`
Action Function	`{prefix}{Action}{Resource}Action`	`sysGetRoleListAction`

`app/(client)/` - Frontend Module

app/(client)/
├── [locale]/                       # Multi-language Routes
│   ├── layout.js                  # Frontend Layout
│   ├── page.js                    # Home Page
│   ├── auth/                      # Authentication Pages
│   │   ├── login/page.js
│   │   └── register/page.js
│   └── [your-page]/page.js
│
└── actions/                        # Frontend Actions
    ├── user-actions.js            # User Related
    └── [module]-actions.js

`components/` - React Components

components/
├── admin/                          # Admin Components
│   ├── smart-crud-page.jsx        # 🌟 Universal Table
│   ├── smart-form/                # 🌟 Universal Form
│   │   ├── index.js
│   │   ├── smart-form.jsx
│   │   ├── smart-modal-form.jsx
│   │   └── smart-drawer-form.jsx
│   ├── admin-layout.jsx           # Admin Layout
│   ├── icon-picker.jsx            # Icon Picker
│   ├── json-editor.jsx            # JSON Editor
│   ├── markdown-editor.jsx        # Markdown Editor
│   └── uploads/                   # Upload Components
│
├── client/                         # Frontend Components
│   ├── layout/                    # Layout Components
│   └── home/                      # Home Page Components
│
├── common/                         # Common Components
│   ├── LanguageSwitcher.jsx       # Language Switcher
│   └── theme-provider.jsx         # Theme Provider
│
└── ui/                            # UI Base Components (shadcn/ui)
    ├── button.jsx
    ├── input.jsx
    └── ...

`lib/` - Core Library

lib/
├── core/                           # 🌟 Core Features
│   ├── action-wrapper.js          # Action Wrapper
│   ├── crud-helper.js             # CRUD Factory Functions
│   └── permission-naming.js       # Permission Naming Parser
│
├── database/                       # Database
│   ├── prisma.js                  # Prisma Client
│   └── selects.js                 # Join Query Utilities
│
├── function/                       # 🌟 Utility Functions (nb.pubfn)
│   ├── index.js                   # Export Entry
│   ├── array.js                   # Array Utilities
│   ├── object.js                  # Object Utilities
│   ├── string.js                  # String Utilities
│   ├── time.js                    # Time Utilities
│   ├── validator.js               # Validation Utilities
│   └── tree.js                    # Tree Utilities
│
├── auth/                           # Authentication
│   ├── auth.js                    # Better Auth Configuration
│   ├── admin-auth.js              # Admin Authentication
│   └── permission-auth.js         # Permission Authentication
│
├── api/                            # API Utilities
│   ├── action-client.js           # Action Client
│   └── api-auth.js                # API Authentication
│
└── validation/                     # Validation
    └── schema-validator.js        # Schema Validator

`prisma/` - Database Models

prisma/
└── schema.prisma                   # Data Model Definition
    │
    ├── User                       # User
    ├── Session                    # Session
    ├── Account                    # OAuth Account
    │
    ├── Role                       # Role
    ├── Permission                 # Permission
    ├── Menu                       # Menu
    │
    ├── Asset                      # Asset Files
    ├── ActionLog                  # Action Log
    │
    └── [YourModel]                # Your Model

📐 Naming Conventions

File Naming

Type	Convention	Example
Page File	`page.js`	`app/(admin)/admin/roles/page.js`
Layout File	`layout.js`	`app/(admin)/layout.js`
Action File	`crud-action.{resource}.js`	`crud-action.role.js`
Component File	`kebab-case.jsx`	`smart-crud-page.jsx`
Utility File	`kebab-case.js`	`action-wrapper.js`

Function Naming

Type	Convention	Example
Server Action	`{prefix}{Action}{Resource}Action`	`sysGetRoleListAction`
Component	`PascalCase`	`SmartCrudPage`
Utility Function	`camelCase`	`createCrudActions`
Constant	`UPPER_SNAKE_CASE`	`DEFAULT_PAGE_SIZE`

Action Prefixes

Prefix	Permission Level	Description
`pub`	PUBLIC	Public access, no login required
`auth`	AUTH	Login required
`sys`	SYSTEM	Admin permission + RBAC check required
`_`	PRIVATE	Internal function, cannot be called directly

🔄 Data Flow

┌─────────────────────────────────────────────────────────────┐
│                        Frontend Page                         │
│  app/(admin)/admin/roles/page.js                           │
│  - Uses SmartCrudPage Component                             │
│  - Configures fieldsConfig                                  │
│  - Passes actions                                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Server Actions                          │
│  app/(admin)/actions/rbac/crud-action.role.js              │
│  - Created using createCrudActions                         │
│  - Automatically wrapped with wrapAction                    │
│  - Automatic permission check and logging                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        BaseDAO                              │
│  app/(admin)/actions/dao/base.js                           │
│  - Universal Data Access Object                            │
│  - Handles CRUD Operations                                 │
│  - Field Filtering, Validation, Hooks                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Prisma Client                           │
│  lib/database/prisma.js                                    │
│  - Type-safe Database Operations                            │
│  - Auto-generated Query Methods                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      PostgreSQL                             │
│  prisma/schema.prisma                                      │
│  - Data Model Definition                                    │
│  - Relationship Mapping                                     │
└─────────────────────────────────────────────────────────────┘

Overall Architecture

System architecture, core components, and design trade-offs

Data Flow Design

Complete flow from request to database

Permission Model

RBAC permission layering and naming conventions

Overall Architecture

Data Flow Design

Permission Model

On this page