11 KiB
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
🔄 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:
- Level 0: Global system configuration
- Level 1: Tenant-specific features
- Level 2: Module and package definitions
- Level 3: Entity and form configurations
- 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:
- Use the search feature in your editor (Ctrl+F)
- Check the Reference Documentation
- Look at existing code examples
- 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
- New to MetaBuilder? Start with README.md and ATOMIC_QUICKSTART.md
- Building a feature? Check IMPLEMENTATION_ROADMAP.md and the implementation/ folder
- Setting up locally? See SASS_QUICK_REFERENCE.md and guides/
- Deploying to production? Review NGINX_INTEGRATION.md and deployments/
- Debugging issues? Check troubleshooting/ first
- Running CI/CD locally? See github-actions-local-testing.md