metabuilder/docs/INDEX.md

MetaBuilder Documentation Index

Welcome to the MetaBuilder documentation. This is your central hub for all project information, organized by category for easy navigation.

<EFBFBD>️ MASTER NAVIGATION - Complete guide to all documentation
<EFBFBD>📋 View Documentation Organization - Understand the doc structure and guidelines

📚 Quick Navigation

🚀 Getting Started

Start here if you're new to the project:

• README - Project overview
• PRD.md - Product requirements & features
• QUICK_START.md - Set up your development environment

🏗️ Architecture

Understand the system design:

• 5-Level System - Core architecture layers
• Data-Driven Architecture - Declarative design patterns
• Database Design - Database schema and structure
• Packages System - Package-based components
• Generic Components - Rendering architecture
• CSS as an Abstract System - Styling as data and GUI mapping

🧪 Testing

Everything about testing the application:

• Testing Guidelines - Best practices and standards
• Unit Tests - Test implementation guide
• Quick Reference - Common testing patterns

🔒 Security

Security documentation and standards:

• Security Guide - Security best practices
• Secure Database Layer - Database security
• Database Security - Implementation details

🔧 API Reference

API documentation and integration guides:

• Platform Guide - Complete API reference
• Quick Reference - Common API patterns
• DBAL Integration - Database abstraction layer
• Packages API - Package installation and seed data endpoints

📋 Implementation Guides

Detailed implementation documentation:

• Component Map - Component structure
• Multi-Tenant System - Multi-tenancy guide
• Prisma Implementation - ORM setup
• TypeScript Enhancements - Type system improvements
• Nerd Mode IDE - Package templates and zip exports
• Permission Levels - Five-tier security and UI guide
• Codegen Studio Export - Zip generation service for package starters

🔄 Refactoring

Refactoring guides and tracking:

• Refactoring Strategy - Overall strategy
• Quick Reference - Common patterns
• Enforcement Guide - Standards
• Checklist - Implementation checklist

🚨 Troubleshooting

Solutions to common issues:

• Check for known issues and solutions
• Database setup problems
• Build and deployment issues

📚 Reference Documentation

Additional references:

• Documentation Index - Detailed doc structure
• Architecture and design patterns
• Lua scripting guide
• Database migration guides

---

🎯 Common Tasks

I want to...

...get started with development → Go to Getting Started

...understand the architecture → Read 5-Level System

...write tests → Check Testing Guidelines

...secure my code → Review Security Guide

...refactor code → See Refactoring Strategy

...integrate with the database → Learn about DBAL Integration

...create a new package → Follow Packages System

---

📂 Documentation Structure

docs/
├── README.md                          # Project overview
├── INDEX.md                           # This file - documentation map
│
├── getting-started/                   # For new developers
│   ├── PRD.md
│   └── QUICK_START.md
│
├── architecture/                      # System design
│   ├── 5-level-system.md
│   ├── data-driven-architecture.md
│   ├── database.md
│   ├── packages.md
│   ├── generic-page-system.md
│   └── css-as-abstract-system.md
│
├── testing/                           # Test documentation
│   ├── TESTING_GUIDELINES.md
│   ├── UNIT_TESTS_IMPLEMENTATION.md
│   └── quick-reference.md
│
├── security/                          # Security docs
│   ├── SECURITY.md
│   └── SECURE_DATABASE_LAYER.md
│
├── api/                               # API documentation
│   ├── platform-guide.md
│   ├── quick-reference.md
│   └── DBAL_INTEGRATION.md
│
├── implementation/                    # Detailed guides
│   ├── COMPONENT_MAP.md
│   ├── MULTI_TENANT_SYSTEM.md
│   ├── PRISMA_IMPLEMENTATION_COMPLETE.md
│   └── TYPESCRIPT_DBAL_ENHANCEMENTS.md
│
├── refactoring/                       # Refactoring guides
│   ├── REFACTORING_STRATEGY.md
│   ├── REFACTORING_QUICK_REFERENCE.md
│   ├── REFACTORING_ENFORCEMENT_GUIDE.md
│   └── REFACTORING_CHECKLIST.md
│
├── development/                       # Development guides
│   └── typescript-reduction-guide.md
│
├── troubleshooting/                   # Troubleshooting
│   └── (Known issues and solutions)
│
└── reference/                         # Additional references
    ├── documentation-index.md
    └── (Other reference materials)

---

🏆 Key Concepts

Five-Level Architecture

MetaBuilder uses a sophisticated 5-level architecture:

1. Level 0: Global system configuration
2. Level 1: Tenant-specific features
3. Level 2: Module and package definitions
4. Level 3: Entity and form configurations
5. Level 4: Individual records and data

→ Learn more: 5-Level System

Data-Driven Design

95% of functionality is defined through JSON and Lua, not TypeScript. → Learn more: Data-Driven Architecture

Package System

Components are organized as self-contained packages with seeds, scripts, and assets. → Learn more: Packages System

Multi-Tenancy

Each tenant has isolated configurations, data, and customizations. → Learn more: Multi-Tenant System

---

📞 Support

If you can't find what you're looking for:

1. Use the search feature in your editor (Ctrl+F)
2. Check the Reference Documentation
3. Look at existing code examples
4. Review the Troubleshooting section

---

Last Updated: December 2025

Migrations

Data migrations, code refactoring, and relocation guides.

• MIGRATION_STATUS.md - Migration progress tracking
• FILE_RELOCATION_GUIDE.md - File organization
• RELOCATION_SUMMARY.md - Relocation completion status

Troubleshooting

Diagnostics, debugging guides, and common issues.

• WORKFLOW_FAILURE_DIAGNOSIS.md - CI/CD debugging
• CORS-BYPASS-EXPLANATION.md - CORS issues
• TEST_COVERAGE_SUMMARY.md - Test coverage info
• PACKAGE_TESTS.md - Package testing guide

Archive

Completed phases and historical work.

• PHASE2_SUMMARY.md - Phase 2 completion summary

Code-to-Documentation Mapping

Source Code (src/)

Documentation for TypeScript/React source code

• components/ - React components (atoms, molecules, organisms)
• lib/ - Core library modules (auth, database, lua, packages)
• hooks/ - React custom hooks
• seed-data/ - Database seed data
• types/ - TypeScript type definitions
• styles/ - Styling system and Tailwind configuration
• tests/ - Unit and integration tests

DBAL (Data Abstraction Layer)

Documentation for C++ and TypeScript database layer

• api/ - API schemas and versioning
• backends/ - Database backend implementations (Prisma, SQLite)
• common/ - Shared DBAL utilities
• cpp/ - C++ implementation
• ts/ - TypeScript implementation
• tools/ - Development tools
• scripts/ - Automation scripts

Packages

Documentation for feature packages

• admin_dialog.md - Admin dialog components
• dashboard.md - Dashboard components
• data_table.md - Data table component
• form_builder.md - Form builder system
• nav_menu.md - Navigation menu components
• notification_center.md - Notification system
• spark-tools.md - Development tools package

Additional Topics

Architecture

Fundamental architecture and design patterns.

• architecture/ - Core architecture documents

Database

Database-specific documentation.

• database/ - Database design and setup

Development

Development workflow and best practices.

• development/ - Development guides

Lua Scripting

Lua integration and scripting.

• lua/ - Lua documentation and examples

Reference

Quick lookup and API reference.

• reference/ - Technical references

Security

Security policies and guidelines.

• security/ - Security documentation

Navigation Tips

1. New to MetaBuilder? Start with README.md and ATOMIC_QUICKSTART.md
2. Building a feature? Check IMPLEMENTATION_ROADMAP.md and the implementation/ folder
3. Setting up locally? See SASS_QUICK_REFERENCE.md and guides/
4. Deploying to production? Review NGINX_INTEGRATION.md and deployments/
5. Debugging issues? Check troubleshooting/ first
6. Running CI/CD locally? See github-actions-local-testing.md