Data Flow Design

Understanding Request Processing and Data Flow in NextJS Base

Request Flow · Permission Check · Data Transformation

🎯 Overview

This document details the data flow process in NextJS Base, from user operations to database storage.

🔄 Request Flow

Complete Request Chain

┌─────────────────────────────────────────────────────────────────────┐
│                        User Operation                               │
│                    (Click Button, Submit Form)                       │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      SmartCrudPage                                   │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 1. Collect User Input                                       │   │
│  │ 2. Transform Search Params Based on fieldsConfig            │   │
│  │ 3. Call Corresponding Server Action                         │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                │  Call actions.getList(params)
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       wrapAction                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 1. Parse Action Name, Determine Permission Level            │   │
│  │    - pub* → PUBLIC (No Login Required)                      │   │
│  │    - auth* → AUTH (Login Required)                          │   │
│  │    - sys* → SYSTEM (Admin Permission Required)              │   │
│  │                                                              │   │
│  │ 2. Execute Authentication Check                              │   │
│  │    - Get Current Session                                     │   │
│  │    - Verify User Identity                                    │   │
│  │                                                              │   │
│  │ 3. Execute Permission Check (sys* prefix)                   │   │
│  │    - Check Admin Access Permission                           │   │
│  │    - Check RBAC Permission                                   │   │
│  │                                                              │   │
│  │ 4. Execute Business Logic                                    │   │
│  │                                                              │   │
│  │ 5. Record Operation Log                                      │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                │  Execute handler(params, context)
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        BaseDAO                                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 1. Build Query Conditions                                    │   │
│  │    - Parse whereJson (Search Conditions)                      │   │
│  │    - Add Soft Delete Filter                                  │   │
│  │    - Build Sort Conditions                                   │   │
│  │                                                              │   │
│  │ 2. Execute Data Validation (create/update)                   │   │
│  │    - Schema Validation                                       │   │
│  │    - Custom Validators                                       │   │
│  │    - Uniqueness Check                                        │   │
│  │                                                              │   │
│  │ 3. Execute Hooks                                             │   │
│  │    - beforeCreate / beforeUpdate / beforeDelete             │   │
│  │                                                              │   │
│  │ 4. Field Filtering                                           │   │
│  │    - Only Keep creatable/updatable Fields                    │   │
│  │                                                              │   │
│  │ 5. Data Transformation (transforms)                         │   │
│  │    - input Transform (Before Write)                          │   │
│  │    - output Transform (After Read)                           │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                │  Call Prisma Methods
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Prisma Client                                   │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 1. Build SQL Query                                          │   │
│  │ 2. Execute Database Operation                               │   │
│  │ 3. Return Result                                             │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       PostgreSQL                                     │
└─────────────────────────────────────────────────────────────────────┘

🔐 Permission Check

Permission Levels

Prefix	Level	Auth	RBAC	Log
`pub`	PUBLIC	❌	❌	✅
`auth`	AUTH	✅	❌	✅
`sys`	SYSTEM	✅	✅	✅
`_`	PRIVATE	-	-	-

Permission Check Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    wrapAction Permission Check                      │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │   Parse Action Name   │
                    │   Determine Level     │
                    └───────────┬───────────┘
                                │
            ┌───────────────────┼───────────────────┐
            │                   │                   │
            ▼                   ▼                   ▼
    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
    │  pub* prefix  │   │  auth* prefix │   │  sys* prefix  │
    │  PUBLIC level  │   │  AUTH level   │   │  SYSTEM level │
    └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
            │                   │                   │
            ▼                   ▼                   ▼
    ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
    │ Optional Get  │   │ Must Login    │   │ Must Login    │
    │ User Info     │   │               │   │               │
    └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
            │                   │                   │
            │                   │                   ▼
            │                   │           ┌───────────────┐
            │                   │           │ Check Admin   │
            │                   │           │ Permission    │
            │                   │           │ hasBackendAccess │
            │                   │           └───────┬───────┘
            │                   │                   │
            │                   │                   ▼
            │                   │           ┌───────────────┐
            │                   │           │ RBAC Check    │
            │                   │           │ Check User    │
            │                   │           │ Roles Have    │
            │                   │           │ This Action   │
            │                   │           └───────┬───────┘
            │                   │                   │
            └───────────────────┴───────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │   Execute Business    │
                    │   Logic               │
                    └───────────────────────┘

RBAC Permission Check Details

// 1. Get User Roles
const user = await getUser(userId)
const roleIds = user.roles  // ['role_id_1', 'role_id_2']

// 2. Get Role Permissions
const roles = await prisma.role.findMany({
  where: { id: { in: roleIds }, enable: true }
})

// 3. Aggregate All Permission IDs
const permissionIds = roles.flatMap(role => role.permission)

// 4. Get Permission Details
const permissions = await prisma.permission.findMany({
  where: { id: { in: permissionIds } }
})

// 5. Check if Action is in Permission List
const allActions = permissions.flatMap(p => p.actions)
const hasPermission = allActions.includes(actionName)

🔄 Data Transformation

Search Parameter Transformation

SmartCrudPage automatically transforms search parameters into Prisma query conditions based on search configuration in fieldsConfig:

// User Input
{
  name: 'John',
  status: 'active',
  createdAt: ['2024-01-01', '2024-12-31']
}

// Transformed whereJson
{
  name: { contains: 'John' },           // like mode
  status: 'active',                     // exact mode
  createdAt: {                          // range mode
    gte: '2024-01-01T00:00:00.000Z',
    lte: '2024-12-31T23:59:59.999Z'
  }
}

Search Mode Comparison

Mode	User Input	Prisma Query
`like`	`"John"`	`{ contains: "John" }`
`exact`	`"active"`	`"active"`
`in`	`["a", "b"]`	`{ in: ["a", "b"] }`
`range`	`["2024-01", "2024-12"]`	`{ gte: ..., lte: ... }`

Data Output Transformation

BaseDAO automatically handles special types returned by Prisma:

// Prisma Returns
{
  id: 'cuid123',
  price: Decimal(99.99),      // Prisma Decimal Type
  count: BigInt(1000000),     // BigInt Type
  createdAt: Date(...)        // Date Type
}

// After Transformation
{
  id: 'cuid123',
  price: 99.99,               // Converted to number
  count: 1000000,             // Converted to number
  createdAt: Date(...)        // Keep Date (Next.js will serialize)
}

📊 List Query Flow

Complete getList Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    SmartCrudPage Request                            │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                │  params: { current, pageSize, sort, filter }
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Search Parameter Transformation                  │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ generateSearchTransform(fieldsConfig)                        │   │
│  │                                                              │   │
│  │ Input: { name: 'John', status: 'active' }                   │   │
│  │ Output: { whereJson: { name: { contains: 'John' }, ... }   │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    actions.getList(params)                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ params: {                                                   │   │
│  │   page: 1,                                                  │   │
│  │   pageSize: 20,                                             │   │
│  │   whereJson: { ... },                                       │   │
│  │   sort: { createdAt: 'desc' }                               │   │
│  │ }                                                           │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    BaseDAO.getList()                                │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 1. Build WHERE Conditions                                    │   │
│  │    - Merge whereJson                                        │   │
│  │    - Add Soft Delete Filter (deletedAt: null)               │   │
│  │                                                              │   │
│  │ 2. Build Sort Conditions                                     │   │
│  │    - Parse sort Parameter                                   │   │
│  │    - Apply Default Sort                                     │   │
│  │                                                              │   │
│  │ 3. Execute Query                                             │   │
│  │    - Query Data (findMany)                                  │   │
│  │    - Query Total (count)                                    │   │
│  │                                                              │   │
│  │ 4. Data Transformation                                      │   │
│  │    - serializeRecord (Handle Decimal/BigInt)                │   │
│  │    - output transform (Custom Transform)                    │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Return Result                                    │
│  {                                                                   │
│    success: true,                                                    │
│    data: {                                                           │
│      list: [...],                                                    │
│      total: 100,                                                     │
│      page: 1,                                                        │
│      pageSize: 20                                                    │
│    }                                                                 │
│  }                                                                   │
└─────────────────────────────────────────────────────────────────────┘

✏️ Create/Update Flow

Complete create/update Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    SmartModalForm Submit                             │
│  formData: { name: 'Test', enable: true, remark: 'Note' }          │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    actions.create(formData)                          │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    wrapAction Processing                            │
│  - Auth Check ✓                                                     │
│  - Permission Check ✓                                                │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    BaseDAO.create()                                  │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 1: Field Filtering                                      │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ Only Keep creatable Fields                                    │   │
│  │ { name: 'Test', enable: true, remark: 'Note' }               │   │
│  │         ↓                                                     │   │
│  │ { name: 'Test', enable: true, remark: 'Note' }               │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 2: Data Validation                                      │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ - Schema Validation (required, maxLength, enum...)           │   │
│  │ - Custom Validators                                          │   │
│  │ - Uniqueness Check                                           │   │
│  │                                                              │   │
│  │ Validation Failed → Throw ValidationError                   │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 3: Execute beforeCreate Hook                            │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ beforeCreate: async (data) => {                              │   │
│  │   // Can Modify Data                                         │   │
│  │   data.code = data.code.toUpperCase()                       │   │
│  │   return data                                                │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 4: Execute input Transform                             │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ transforms: {                                                │   │
│  │   input: (data) => {                                        │   │
│  │     // Data Transform Before Write                           │   │
│  │     return { ...data, updatedBy: userId }                   │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 5: Execute Prisma create                                │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ prisma.model.create({ data: filteredData })                │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 6: Execute afterCreate Hook                             │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ afterCreate: async (record) => {                            │   │
│  │   // Post-Create Operations, e.g., Send Notification        │   │
│  │   await sendNotification(record)                            │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Step 7: Execute output Transform                             │   │
│  │ ─────────────────────────────────────────────────────────── │   │
│  │ transforms: {                                                │   │
│  │   output: (record) => {                                     │   │
│  │     // Data Transform Before Return                          │   │
│  │     return { ...record, displayName: `#${record.id}` }      │   │
│  │   }                                                          │   │
│  │ }                                                            │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    wrapAction Log Record                            │
│  {                                                                   │
│    action: 'sysCreateRole',                                          │
│    resource: 'role',                                                 │
│    params: { name: 'Test' },                                         │
│    result: { id: 'xxx' },                                           │
│    success: true,                                                    │
│    duration: 123                                                     │
│  }                                                                   │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Return Result                                    │
│  { success: true, data: { id: 'xxx', name: 'Test', ... } }          │
└─────────────────────────────────────────────────────────────────────┘

Overall Architecture

System architecture overview and module relationships

Permission Model

RBAC permission design and roles in data flow

BaseDAO API

Data access object and connection point in data flow

wrapAction API

Action wrapper and request chain

Overall Architecture

Permission Model

BaseDAO API

wrapAction API

On this page