metabuilder/docs

MetaBuilder - Enterprise Data Platform

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.

TODO: This file lives under docs/; links that start with ./docs/ are broken and PRD/SECURITY paths are outdated.

📋 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

🧪 Testing Workflows Locally

New: Test GitHub Actions workflows locally before pushing!

# Quick start - runs full CI pipeline
npm run act

# Test specific components
npm run act:lint        # ESLint linting
npm run act:build       # Production build
npm run act:e2e         # End-to-end tests
npm run act:typecheck   # TypeScript validation

# Interactive testing
npm run act:test        # Menu-driven testing

# Diagnostics
npm run act:diagnose    # Check setup (no Docker required)

See ACT Cheat Sheet for quick reference or Act Testing Guide for detailed documentation.

Benefits:

• ✅ Catch CI failures before pushing to GitHub
• ✅ No more "fix CI" commits
• ✅ Fast feedback loop (5-10 minutes per run)
• ✅ Works offline after first run

---

🚀 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

• Project Requirements (PRD)
• Security Guidelines
• Code Documentation Index

Local Testing with Act

• Act Cheat Sheet - Quick reference for common commands
• Act Testing Guide - Complete documentation
• GitHub Actions Reference - Technical details

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

# Local Workflow Testing (Act)
npm run act              # Run full CI pipeline locally
npm run act:lint         # Test linting
npm run act:build        # Test production build
npm run act:e2e          # Test E2E tests
npm run act:test         # Interactive testing menu
npm run act:diagnose     # Check setup (no Docker)

# 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

TODO: src/README.md does not exist under docs/; confirm correct location or add missing docs/src.

• 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

TODO: Manual deployment docs are not under docs/deployment; update this link to the correct location. See deployment/README.md for detailed instructions.

🤝 Contributing

1. Check documentation guidelines
2. Follow code conventions in Copilot instructions
3. Run linter: npm run lint:fix
4. Run tests: npm run test:e2e
5. 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:

1. Check the documentation
2. Review example code
3. Check existing tests for patterns
4. 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