MetaBuilder is a powerful, declarative enterprise data platform built on a 5-level permission system. It enables rapid development of multi-tenant data applications with JSON configurations and Lua scripting.

📋 Table of Contents

Features
Quick Start
Architecture
Documentation
Development
Project Structure

✨ Features

5-Level Permission System - Granular access control (User, Admin, God, SuperGod, SystemRoot)
Multi-Tenant Architecture - Built-in support for tenant isolation
Declarative Configuration - Define features in JSON, not code
Lua Scripting - Dynamic business logic without recompilation
Database-Driven - All configuration stored and managed in database
Package System - Modular, reusable feature packages
Type-Safe - Full TypeScript support throughout
CI/CD Ready - Automated testing, linting, and deployment workflows

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn
Docker (optional, for deployment)

Development Setup

# Clone repository
git clone <repo>
cd metabuilder

# Install dependencies
npm install

# Set up database
npm run db:generate
npm run db:push

# Start development server
npm run dev

Visit http://localhost:5173 to access the application.

Build for Production

npm run build
npm run preview  # Preview production build locally

📐 Architecture

MetaBuilder uses a 5-level permission system:

SuperGod (Level 5) - System administrator, full access
   ↓
God (Level 4) - Power user, can modify system configuration
   ↓
Admin (Level 3) - Tenant administrator, manage users and data
   ↓
User (Level 2) - Regular user, standard data access
   ↓
Guest (Level 1) - Read-only access (not implemented)

Key Components

Prisma ORM - Type-safe database queries
React + TypeScript - Modern UI framework
Vite - Fast build tool
Tailwind CSS - Utility-first CSS framework
Lua (Fengari) - Embedded scripting

For detailed architecture information, see Architecture Documentation.

📚 Documentation

Getting Started

Getting Started Guide - Setup and first steps
5-Level Permission System - Understanding permissions

Development Guides

API Development - Creating API routes
Package System - Building packages
Database Guide - Working with Prisma

Reference

Full Documentation

See docs/README.md for the complete documentation index.

🔧 Development

Available Scripts

# Development & Building
npm run dev              # Start dev server
npm run build            # Production build
npm run preview          # Preview production build

# Testing
npm run test             # Run tests in watch mode
npm run test:e2e         # Run end-to-end tests
npm run test:e2e:ui      # Run e2e tests with UI
npm run lint             # Check code quality
npm run lint:fix         # Auto-fix linting issues

# Database
npm run db:generate      # Generate Prisma client
npm run db:push          # Apply schema changes
npm run db:studio        # Open database UI

# Other
npm run act              # Run GitHub Actions locally

Code Quality

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Run all tests
npm run test:e2e

📁 Project Structure

metabuilder/
├── src/                    # React application source
│   ├── app/               # App layout and pages
│   ├── components/        # React components
│   ├── lib/              # Utility libraries
│   ├── hooks/            # Custom React hooks
│   ├── types/            # TypeScript type definitions
│   └── seed-data/        # Database initialization data
├── prisma/               # Database schema & migrations
│   └── schema.prisma     # Prisma schema
├── packages/             # Modular feature packages
│   ├── admin_dialog/
│   ├── dashboard/
│   ├── data_table/
│   ├── form_builder/
│   └── ...
├── docs/                 # Documentation
│   ├── architecture/     # Architecture guides
│   ├── guides/          # Development guides
│   └── ...
├── e2e/                 # End-to-end tests
├── scripts/             # Utility scripts
│   └── doc-quality-checker.sh  # Documentation quality assessment
├── deployment/          # Deployment configurations
├── vite.config.ts       # Vite configuration
├── tsconfig.json        # TypeScript configuration
├── middleware.ts        # Next.js middleware
└── package.json         # Dependencies & scripts

Directory Guide

src/ - See src/README.md
packages/ - See packages/README.md
docs/ - See docs/README.md
prisma/ - Database schema and migrations
e2e/ - Playwright end-to-end tests
scripts/ - Utility scripts including documentation quality checker

🔐 Security

All credentials stored as SHA-512 hashes
5-level permission system for granular access control
Sandboxed Lua script execution
Type-safe database queries with Prisma
Security documentation: SECURITY.md

📦 Deployment

Docker

# Development
docker-compose -f deployment/docker-compose.development.yml up

# Production
docker-compose -f deployment/docker-compose.production.yml up

Manual Deployment

See deployment/README.md for detailed instructions.

🤝 Contributing

Check documentation guidelines
Follow code conventions in Copilot instructions
Run linter: npm run lint:fix
Run tests: npm run test:e2e
Update documentation as needed

📊 Documentation Quality

This project maintains high documentation standards:

# Check documentation quality
./scripts/doc-quality-checker.sh /workspaces/metabuilder

Current metrics:

README Coverage: 60%+
JSDoc Coverage: 100%
Type Annotations: 80%+
Security Docs: 100%

📄 License

See LICENSE file.

📞 Support

For questions or issues:

Check the documentation
Review example code
Check existing tests for patterns
Review SECURITY.md for security questions

Quick Links

Permission Model: 5-Level System
Database Schema: Prisma Schema
API Patterns: API Development Guide
Security: Security Guidelines
Packages: Package System

Languages

TypeScript 30.6%

JavaScript 19.3%

Jupyter Notebook 12.7%

C++ 9.5%

SCSS 8.8%

Other 18.8%