metabuilder/docs/getting-started/NEW_CONTRIBUTOR_PATH.md

New Contributor Path

A guided learning path through MetaBuilder documentation for new team members.

🎯 Your Learning Journey (2-3 hours)

This path guides you through the essential concepts in a logical order. Follow the sections sequentially.

Phase 1: Foundation (30 minutes)

Understand what MetaBuilder is and how it's structured.

1. Project Overview ⭐ START HERE

   • What MetaBuilder does
   • Key features
   • Tech stack overview

2. Executive Brief

   • High-level business context
   • Key stakeholders
   • Project goals

3. Product Requirements

   • Feature list
   • User personas
   • Requirements breakdown

Phase 2: Architecture Fundamentals (45 minutes)

Learn how MetaBuilder is architected.

4. 5-Level Permission System ⭐ CRITICAL

   • Permission hierarchy (Public → User → Admin → God → Supergod)
   • Role-based access patterns
   • Multi-tenant considerations

5. Data-Driven Architecture

   • 95% JSON/Lua philosophy
   • Minimal TypeScript
   • Declarative patterns

6. Package System

   • How packages work
   • Package structure
   • Self-contained modules

7. Generic Component Rendering

   • Component declaration via JSON
   • RenderComponent pattern
   • Dynamic UI composition

8. Database Design

   • Schema overview
   • Multi-tenant isolation
   • DBAL integration

Phase 3: Development Workflow (45 minutes)

Learn how to develop with MetaBuilder.

9. Quick Start (if available in getting-started/README.md)

   • Development environment setup
   • Running the project locally
   • Common commands

10. Testing Guidelines ⭐ REQUIRED

    • Test structure
    • Parameterized testing
    • Coverage requirements

11. Refactoring Strategy

    • Code quality standards
    • Component size limits (150 LOC)
    • TypeScript reduction principles

12. Lua Scripting Guide

    • Lua sandbox execution
    • Script patterns
    • Integration with TypeScript

Phase 4: Common Tasks (30 minutes)

Learn how to accomplish typical work items.

13. Component Development (or component development guide)

    • Creating new components
    • Using RenderComponent
    • Testing components

14. DBAL Integration

    • Database operations
    • Using Database helper class
    • Query patterns

15. Package Creation

    • Creating new packages
    • Package structure
    • Seed data

---

🔑 Key Concepts to Remember

As you work through this path, keep these principles in mind:

✅ DO:

• ✅ Use Database class for all database operations (never raw Prisma)
• ✅ Filter queries by tenantId for multi-tenant safety
• ✅ Use generic RenderComponent instead of hardcoded JSX
• ✅ Keep components < 150 LOC
• ✅ Write parameterized tests for every function
• ✅ Use Lua for data transformation, TypeScript for orchestration

❌ DON'T:

• ❌ Hardcode values in TypeScript (move to database/config)
• ❌ Forget tenantId in queries (breaks multi-tenancy)
• ❌ Create new database fields without running npm run db:generate
• ❌ Commit code without tests passing
• ❌ Build custom components when JSON config would work
• ❌ Add fields/operations to DBAL without updating YAML first

---

📚 Reference Resources

Keep these handy as you develop:

• Copilot Instructions - AI assistant context
• Master Navigation - Complete docs index
• Troubleshooting - Common issues
• Quick References - Testing patterns

---

🎓 Learning Paths by Role

Frontend Developer

1-4, 7, 10-15 in the main path, plus:

• Component Architecture
• SASS Configuration

Backend Developer

1-6, 8-9, 14 in the main path, plus:

• DBAL Integration
• Database Migrations
• API Reference

DevOps/Infrastructure

1-2, plus:

• Deployment Guide
• Docker Setup
• CI/CD Workflows

QA/Testing

1-3, 10-11, plus:

• Testing Implementation
• E2E Testing

---

✅ Completion Checklist

After completing this path, you should be able to:

• Explain the 5-level permission system
• Describe why MetaBuilder is 95% JSON/Lua
• Create a new component using RenderComponent
• Write a parameterized test with 3+ cases
• Run the project locally and make a simple code change
• Query data safely with tenantId filtering
• Create a new package with seed data
• Run the test suite and see all tests pass
• Explain the package system architecture
• Understand DBAL's role in the system

---

💬 Questions?

If something isn't clear:

1. Check Troubleshooting
2. Search for keywords in Master Navigation
3. Review the Copilot Instructions for patterns

Welcome to MetaBuilder! 🚀