Overall Architecture

Deep Understanding of NextJS Base System Architecture

Architecture Diagram · Core Modules · Design Philosophy

🎯 Architecture Overview

NextJS Base adopts a layered architecture design, dividing the system into clear layers with explicit responsibilities, reducing coupling.

Core Features

Feature	Description
Configuration-Driven	UI and behavior driven by `fieldsConfig` configuration
Convention over Configuration	Automatic permission and routing handling through naming conventions
Layered Decoupling	Clear separation of presentation, business, and data layers
Automation	Automatic permission checks, logging, data validation

🏗️ Architecture Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                    Presentation Layer                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │   SmartCrudPage  │  │    SmartForm     │  │   Custom Pages   │  │
│  │  Universal Table │  │  Universal Form  │  │  Custom Pages     │  │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
│           │                     │                     │             │
│           └─────────────────────┼─────────────────────┘             │
│                                 │                                    │
│                      ┌──────────▼──────────┐                        │
│                      │    fieldsConfig     │                        │
│                      │  Field Config Hub   │                        │
│                      └──────────┬──────────┘                        │
│                                 │                                    │
└─────────────────────────────────┼────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Business Layer                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                      Server Actions                           │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │   │
│  │  │ sysGetList  │  │ sysCreate   │  │ sysUpdate   │   ...    │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │   │
│  │         └────────────────┼────────────────┘                  │   │
│  └──────────────────────────┼───────────────────────────────────┘   │
│                             │                                        │
│                  ┌──────────▼──────────┐                            │
│                  │     wrapAction      │                            │
│                  │   ┌─────────────┐   │                            │
│                  │   │ Auth Check  │   │                            │
│                  │   │ Permission  │   │                            │
│                  │   │ Logging     │   │                            │
│                  │   └─────────────┘   │                            │
│                  └──────────┬──────────┘                            │
│                             │                                        │
│                  ┌──────────▼──────────┐                            │
│                  │  createCrudActions  │                            │
│                  │   CRUD Factory      │                            │
│                  └──────────┬──────────┘                            │
│                             │                                        │
└─────────────────────────────┼────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Data Access Layer                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                         BaseDAO                               │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │   │
│  │  │Field Filter │  │Validation   │  │Hook Execute │          │   │
│  │  │Search Build │  │Soft Delete │  │Data Transform│          │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘          │   │
│  └──────────────────────────┬───────────────────────────────────┘   │
│                             │                                        │
│                  ┌──────────▼──────────┐                            │
│                  │    Prisma Client    │                            │
│                  │   ORM Database      │                            │
│                  └──────────┬──────────┘                            │
│                             │                                        │
└─────────────────────────────┼────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Storage Layer                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │   PostgreSQL     │  │  Cloud Storage   │  │     Redis        │  │
│  │  Relational DB   │  │ R2/S3/OSS/Qiniu  │  │  Cache (Optional)│  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

📦 Core Modules

1. SmartCrudPage - Universal Table

Configuration-driven data table component, one component implements complete CRUD functionality

<SmartCrudPage
  title="Data Management"
  fieldsConfig={fieldsConfig}    // Field Configuration
  actions={actions}              // Server Actions
  enableCreate={true}            // Enable Create
  enableEdit={true}              // Enable Edit
  enableDelete={true}            // Enable Delete
/>

Core Features:

📋 Data List (pagination, sorting, filtering)
🔍 Advanced Search (multiple search modes)
➕ Create Record (auto-generated form)
✏️ Edit Record (auto-filled form)
🗑️ Delete Record (confirmation popup)
👁️ View Details (drawer display)

2. fieldsConfig - Field Configuration

Unified field configuration that drives table, form, search, and details

const fieldsConfig = [
  {
    key: 'name',           // Field Name
    title: 'Name',          // Display Name
    type: 'text',          // Field Type
    table: { ... },        // Table Configuration
    form: { ... },         // Form Configuration
    search: { ... },       // Search Configuration
  }
]

Supported Types:

Type	Description	Table	Form	Search
`text`	Text	✅	✅	✅
`textarea`	Multi-line Text	✅	✅	✅
`number`	Number	✅	✅	✅
`select`	Dropdown	✅	✅	✅
`switch`	Switch	✅	✅	✅
`date`	Date	✅	✅	✅
`datetime`	DateTime	✅	✅	✅
`tree-select`	Tree Select	✅	✅	✅
`image`	Image	✅	✅	❌
`markdown`	Markdown	✅	✅	❌

3. wrapAction - Action Wrapper

Action wrapper that automatically handles authentication, authorization, and logging

export const sysGetRoleListAction = wrapAction(
  'sysGetRoleList',      // Action Name (determines permission level)
  async (params, ctx) => {
    // ctx contains userId, user, isAdmin
    return await dao.getList(params)
  }
)

Automatic Handling:

Feature	Description
Authentication Check	Automatically checks login status based on prefix
Permission Verification	`sys` prefix automatically checks RBAC permissions
Logging	Automatically records operation logs
Error Handling	Unified error response format

4. createCrudActions - CRUD Factory

Quickly create standard CRUD Actions

const { getList, create, update, delete: del } = createCrudActions({
  modelName: 'role',
  fields: {
    creatable: ['name', 'remark'],
    updatable: ['name', 'remark'],
    searchable: ['name'],
  },
  validation: { ... },
  hooks: { ... },
})

Generated Actions:

sysGet{Resource}ListAction - Get List
sysGet{Resource}DetailAction - Get Detail
sysCreate{Resource}Action - Create Record
sysUpdate{Resource}Action - Update Record
sysDelete{Resource}Action - Delete Record
sysBatchUpdate{Resource}Action - Batch Update
sysBatchDelete{Resource}Action - Batch Delete

5. BaseDAO - Data Access Object

Universal data access layer that encapsulates Prisma operations

const dao = new BaseDAO({
  modelName: 'role',
  primaryKey: 'id',
  softDelete: true,
  fields: { ... },
  validation: { ... },
  hooks: { ... },
})

Core Features:

Method	Description
`getList()`	Paginated query, search, sorting
`getDetail()`	Single query, relation loading
`create()`	Create record, validation, Hooks
`update()`	Update record, field filtering
`delete()`	Delete/Soft Delete
`batchUpdate()`	Batch Update
`batchDelete()`	Batch Delete

💡 Design Philosophy

1. Configuration over Code

Traditional approach requires writing lots of repetitive code:

// ❌ Traditional Approach - Need to write table columns, form fields, search config separately
const columns = [...]
const formFields = [...]
const searchFields = [...]

NextJS Base uses unified configuration:

// ✅ Configuration-Driven - One configuration drives all UI
const fieldsConfig = [
  {
    key: 'name',
    title: 'Name',
    type: 'text',
    table: { width: 200 },
    form: { required: true },
    search: { enabled: true },
  }
]

2. Convention over Configuration

Automatic permission handling through naming conventions:

// Action name determines permission level
sysGetRoleList    // sys prefix → requires admin permission + RBAC check
authGetUserInfo   // auth prefix → requires login
pubGetConfig      // pub prefix → public access

3. Layered Decoupling

Each layer only focuses on its own responsibilities:

Layer	Responsibility	Doesn't Care About
Presentation	UI Rendering, User Interaction	How data is fetched
Business	Business Logic, Permission Control	How data is stored
Data	Data Access, Validation	How data is displayed

4. Extensibility

Each module can be extended:

// Extend CRUD Actions
const { getList, create, ...rest } = createCrudActions(config)

// Add Custom Action
export const customAction = wrapAction('sysCustomAction', async (params) => {
  // Custom logic
})

Data Flow Design

Request processing flow and module interaction

Permission Model

RBAC permission design and data structure

SmartCrudPage

Implementation details from architecture to components

Server Actions

Backend implementation guide combined with architecture

Project Structure

Architecture implementation at directory level

Data Flow Design

Permission Model

SmartCrudPage

Server Actions

Project Structure

On this page