metabuilder/docs

MetaBuilder Documentation

Welcome to the MetaBuilder documentation. This directory contains comprehensive documentation organized into logical categories.

🚀 Quick Start

New to the project? Start here:

1. Platform Guide - Overview of the 5-level system
2. Quick Reference - Common tasks and patterns
3. Data-Driven Architecture - Core concepts

Ready to build?

• Package System - Create and use packages
• Lua Integration - Add custom logic
• Generic Page System - Build pages without code

📁 Current Directory Structure

docs/
├── README.md (this file)
├── RELOCATION_SUMMARY.md        # Guide for organizing docs
├── FILE_RELOCATION_GUIDE.md     # Detailed relocation instructions
│
├── architecture/                 # System Architecture
│   ├── data-driven-architecture.md
│   ├── declarative-components.md
│   └── generic-page-system.md
│
├── database/                     # Database Documentation
│   └── overview.md
│
├── development/                  # Development Guides
│   ├── typescript-reduction-guide.md
│   ├── cruft-removal-report.md
│   └── improvements.md
│
├── iterations/                   # Project History
│   ├── iteration-24-summary.md
│   ├── iteration-25-summary.md
│   ├── iteration-25-complete.md
│   ├── iteration-26-summary.md
│   └── the-transformation.md
│
├── lua/                         # Lua Integration
│   ├── integration.md
│   └── snippets-guide.md
│
├── packages/                    # Package System
│   ├── package-system.md
│   ├── import-export.md
│   ├── scripts-guide.md
│   ├── modular-packages-guide.md
│   ├── modular-seed-data-guide.md
│   └── irc-conversion-guide.md
│
├── reference/                   # Quick Reference
│   ├── quick-reference.md
│   ├── documentation-index.md
│   └── platform-guide.md
│
└── security/                    # Security
    └── guide.md

📖 Documentation Categories

Architecture

Deep dives into system design and implementation patterns:

• Data-Driven Architecture - How the system minimizes TypeScript dependencies
• Declarative Components - Component system built on JSON + Lua
• Generic Page System - Dynamic page rendering from configuration

Database

Database layer documentation:

• Overview - KV persistence, schemas, and CRUD operations

Development

Guides for contributors and developers:

• TypeScript Reduction Guide - Strategy for data-driven approach
• Improvements - UI/UX enhancements and builder tools
• Cruft Removal Report - Cleanup and maintenance history

Iterations

Project evolution and milestone documentation:

• Iteration Summaries - What was accomplished in each iteration
• The Transformation - Before/after comparison of the data-driven shift

Lua

Lua scripting integration:

• Integration - How Lua works in MetaBuilder
• Snippets Guide - Reusable Lua patterns and examples

Packages

Package system documentation:

• Package System - Overview and architecture
• Import/Export - Sharing and distributing packages
• Modular Guides - Creating modular, reusable components
• IRC Conversion - Case study of converting components to declarative

Reference

Quick lookup and overview materials:

• Quick Reference - Common tasks and code snippets
• Documentation Index - Finding the right docs for your needs
• Platform Guide - High-level overview of the 5-level system

Security

Security practices and guidelines:

• Guide - Authentication, authorization, and best practices

## 🔗 Quick Links

**Getting Started:**
- [Platform Guide](reference/platform-guide.md) - 5-level architecture overview
- [Quick Reference](reference/quick-reference.md) - Common tasks
- [Documentation Index](reference/documentation-index.md) - Find what you need

**Core Concepts:**
- [Data-Driven Architecture](architecture/data-driven-architecture.md)
- [Generic Page System](architecture/generic-page-system.md)
- [Declarative Components](architecture/declarative-components.md)

**Building With MetaBuilder:**
- [Package System](packages/package-system.md)
- [Lua Integration](lua/integration.md)
- [Modular Seed Data](packages/modular-seed-data-guide.md)

**Development:**
- [TypeScript Reduction Strategy](development/typescript-reduction-guide.md)
- [Recent Improvements](development/improvements.md)
- [Security Guide](security/guide.md)

**Project History:**
- [The Transformation](iterations/the-transformation.md)
- [Iteration 25 Complete](iterations/iteration-25-complete.md)
- [Iteration 26 Summary](iterations/iteration-26-summary.md)

## 🎯 Find What You Need

### I want to understand...
- **The big picture**: [Platform Guide](reference/platform-guide.md)
- **How data-driven works**: [Data-Driven Architecture](architecture/data-driven-architecture.md)
- **Project evolution**: [The Transformation](iterations/the-transformation.md)

### I want to build...
- **A new package**: [Package System](packages/package-system.md) → [Modular Packages](packages/modular-packages-guide.md)
- **Custom logic**: [Lua Integration](lua/integration.md) → [Lua Snippets](lua/snippets-guide.md)
- **A new page**: [Generic Page System](architecture/generic-page-system.md)

### I want to learn from...
- **Examples**: [IRC Conversion Guide](packages/irc-conversion-guide.md)
- **Quick patterns**: [Quick Reference](reference/quick-reference.md)
- **History**: Browse [iterations/](iterations/)

## 📝 Documentation Standards

All documentation in this directory follows these standards:

1. **Markdown Format**: All files use GitHub-flavored markdown
2. **Code Examples**: Include practical, working examples
3. **Cross-References**: Link to related documentation
4. **Up-to-Date**: Documentation is updated with each iteration
5. **Comprehensive**: Cover both basic and advanced use cases

## 🔄 Relocating Documentation

If documentation files need to be organized from the root:

1. See [RELOCATION_SUMMARY.md](RELOCATION_SUMMARY.md) for overview
2. Run the provided `move-docs.sh` script from the project root
3. Or follow [FILE_RELOCATION_GUIDE.md](FILE_RELOCATION_GUIDE.md) for manual steps

## 🤝 Contributing to Documentation

When adding new documentation:

1. Place it in the appropriate category directory
2. Follow the naming convention: lowercase-with-hyphens.md
3. Add cross-references to related docs
4. Include code examples where applicable
5. Update this README's Quick Links if adding important docs

## 📊 Documentation Metrics

- **Total Categories**: 8 (Architecture, Database, Development, Iterations, Lua, Packages, Reference, Security)
- **Key Documents**: 20+ comprehensive guides
- **Iteration History**: 4 detailed summaries
- **Last Updated**: Iteration 27