metabuilder/frontends/nextjs/src/lib

Libraries (src/lib/)

Core utilities, database access, authentication, and business logic for MetaBuilder.

Key Modules

Database Access

• database.ts - Prisma ORM wrapper and database operations
  • User management
  • Tenant data isolation
  • Schema queries
  • CRUD operations

Authentication & Authorization

• auth.ts - Permission and access control
  • canAccessLevel(user, level) - Check if user can access level
  • hashPassword() - SHA-512 password hashing
  • Permission matrices for 5-level system

Data Initialization

• seed-data/ - Initial database population
  • User templates
  • Default configurations
  • Example workflows
  • Component templates

Utilities

• package-loader.ts - Package system management
• lua-sandbox.ts - Secure Lua script execution with Fengari
• validators.ts - Input validation schemas
• helpers.ts - Common utility functions

5-Level Architecture

The permission system provides granular access control:

// Level definitions
const LEVELS = {
  LEVEL_1: 1,  // Public/Unauthenticated
  LEVEL_2: 2,  // Authenticated User
  LEVEL_3: 3,  // Admin
  LEVEL_4: 4,  // God Mode
  LEVEL_5: 5,  // Supergod (Full Control)
}

// Usage
if (canAccessLevel(user.level, 3)) {
  // Show admin features
}

Database Schema

Prisma ORM manages the database schema defined in prisma/schema.prisma:

model User {
  id        String    @id @default(cuid())
  email     String    @unique
  password  String    // SHA-512 hashed
  level     Int       // 1-5
  tenant    Tenant    @relation(fields: [tenantId], references: [id])
  tenantId  String
}

Package System

Dynamic feature loading through packages:

import { initializePackageSystem } from '@/lib/package-loader'

// Loads packages from /packages/ directory
await initializePackageSystem()

Each package can include:

• React components
• Lua scripts
• Seed data
• Configuration
• Static assets

Lua Scripting

Safe, sandboxed Lua execution for business logic:

import { executeLua } from '@/lib/lua-sandbox'

const result = await executeLua(`
  function add(a, b)
    return a + b
  end
  return add(2, 3)
`)
// result = 5

Security

Password Hashing

import { hashPassword } from '@/lib/database'

const hashed = hashPassword('userPassword')
// Uses SHA-512 for security

Lua Sandbox

All Lua scripts execute in a restricted environment:

• Limited standard library access
• No file system access
• No network access
• Memory limits enforced
• Timeout protection

Usage Examples

Check User Permissions

import { canAccessLevel } from '@/lib/auth'

const canAdmin = canAccessLevel(user.level, 3)
if (canAdmin) {
  // Show admin UI
}

Database Query

import { Database } from '@/lib/database'

const db = new Database()
const user = await db.getUser(userId)
const updated = await db.updateUser(userId, { level: 3 })

Initialize App

import { seedDatabase } from '@/lib/seed-data'
import { initializePackageSystem } from '@/lib/package-loader'

// Seed initial data
await seedDatabase()

// Load packages
await initializePackageSystem()

File Organization

lib/
├── auth.ts                 # Authorization logic
├── database.ts             # Prisma wrapper
├── lua-sandbox.ts          # Lua execution
├── package-loader.ts       # Package system
├── validators.ts           # Input validation
├── helpers.ts              # Utilities
├── seed-data/
│   ├── index.ts            # Main seed entry
│   ├── users.ts            # User templates
│   ├── workflows.ts        # Workflow templates
│   └── components.ts       # Component templates
└── level-types.ts          # TypeScript type definitions

Best Practices

1. ✅ Keep business logic in libraries, not components
2. ✅ Use database for configuration (declarative)
3. ✅ Sandbox all Lua execution
4. ✅ Hash all passwords with SHA-512
5. ✅ Validate all user input
6. ❌ Don't expose secrets in code
7. ❌ Don't trust client-side permissions alone
8. ❌ Don't execute unsanitized code

See /docs/ for detailed architecture documentation.