# πŸ“š MetaBuilder Documentation Organization Guide Welcome! All MetaBuilder documentation is organized in the `/docs` folder. This guide helps you navigate it effectively. TODO: This file is already in docs/; links that start with ./docs/ are broken and should be updated to correct relative paths. ## πŸš€ Quick Start (Choose Your Path) ### πŸ‘€ I'm New to MetaBuilder **β†’ Start here:** [docs/getting-started/NEW_CONTRIBUTOR_PATH.md](./docs/getting-started/NEW_CONTRIBUTOR_PATH.md) A structured 2-3 hour learning path that teaches you everything you need to know. ### πŸ” I Need Something Specific **β†’ Use this:** [docs/NAVIGATION.md](./docs/NAVIGATION.md) Master navigation hub with links to all documentation organized by category. ### πŸ“– I Want to Browse **β†’ Go here:** [docs/INDEX.md](./docs/INDEX.md) Quick navigation with highlighted quick-reference links. ### πŸ—‚οΈ I Want to Understand the Structure **β†’ Read this:** [docs/ORGANIZATION.md](./docs/ORGANIZATION.md) Detailed breakdown of how documentation is organized. --- ## πŸ“‚ Directory Structure ``` docs/ β”œβ”€β”€ NAVIGATION.md ← πŸ—ΊοΈ Master navigation (use this!) β”œβ”€β”€ INDEX.md ← Quick nav hub β”œβ”€β”€ ORGANIZATION.md ← How docs are organized β”œβ”€β”€ README.md ← Docs overview β”‚ β”œβ”€β”€ getting-started/ β”‚ β”œβ”€β”€ NEW_CONTRIBUTOR_PATH.md ← πŸ‘ˆ NEW TEAM MEMBERS START HERE β”‚ β”œβ”€β”€ README.md β”‚ β”œβ”€β”€ PRD.md β”‚ └── ... β”‚ β”œβ”€β”€ architecture/ ← System design & concepts β”œβ”€β”€ testing/ ← Testing guidelines & patterns β”œβ”€β”€ implementation/ ← How-to guides for features β”œβ”€β”€ refactoring/ ← Code quality standards β”œβ”€β”€ packages/ ← Package system docs β”œβ”€β”€ guides/ ← How-to guides & tutorials β”œβ”€β”€ dbal/ ← Database abstraction layer β”œβ”€β”€ api/ ← API reference β”œβ”€β”€ deployments/ ← Deployment & DevOps β”œβ”€β”€ development/ ← Development workflows β”œβ”€β”€ database/ ← Database documentation β”œβ”€β”€ quality-metrics/ ← Code quality & metrics β”œβ”€β”€ security/ ← Security best practices β”œβ”€β”€ lua/ ← Lua scripting β”œβ”€β”€ troubleshooting/ ← Problem solving β”œβ”€β”€ reference/ ← Quick reference & lookup β”œβ”€β”€ archive/ ← Historical/deprecated docs β”œβ”€β”€ stub-detection/ ← Stub detection system β”œβ”€β”€ src/ ← Source code documentation β”œβ”€β”€ migrations/ ← Database migrations β”œβ”€β”€ iterations/ ← Project iteration histories └── builds/ ← Build system docs ``` --- ## 🎯 Common Tasks | I want to... | Link | Time | |---|---|---| | **Get started developing** | [NEW_CONTRIBUTOR_PATH.md](./docs/getting-started/NEW_CONTRIBUTOR_PATH.md) | 2-3 hrs | | **Understand the architecture** | [5-level-system.md](./docs/architecture/5-level-system.md) | 15 min | | **Write a test** | [TESTING_GUIDELINES.md](./docs/testing/TESTING_GUIDELINES.md) | 10 min | | **Create a new component** | [implementation/COMPONENT_MAP.md](./docs/implementation/COMPONENT_MAP.md) | 20 min | | **Add a database feature** | [DBAL_INTEGRATION.md](./docs/implementation/DBAL_INTEGRATION.md) | 30 min | | **Deploy the application** | [deployments/README.md](./docs/deployments/README.md) | 15 min | | **Fix a bug** | [refactoring/REFACTORING_STRATEGY.md](./docs/refactoring/REFACTORING_STRATEGY.md) | varies | | **Create a package** | [packages/README.md](./docs/packages/README.md) | 30 min | | **Solve a problem** | [troubleshooting/README.md](./docs/troubleshooting/README.md) | varies | | **Run tests locally** | [guides/ACT_CHEAT_SHEET.md](./docs/guides/ACT_CHEAT_SHEET.md) | 5 min | --- ## πŸ“Š Documentation Quick Facts - **Total Files**: 144+ markdown documents - **Main Categories**: 23 directories - **Quick References**: 10+ cheat sheets & quick-start guides - **Implementation Guides**: 15+ detailed step-by-step guides - **Architecture Documentation**: 8+ core architecture files --- ## πŸ”‘ Key Documentation ### **MUST READ** (Everyone) 1. **[5-level-system.md](./docs/architecture/5-level-system.md)** - Permission hierarchy 2. **[TESTING_GUIDELINES.md](./docs/testing/TESTING_GUIDELINES.md)** - How we test 3. **[Copilot Instructions](./docs/../../.github/copilot-instructions.md)** - Development standards ### **MUST READ** (By Role) **Frontend Developers**: - [generic-page-system.md](./docs/architecture/generic-page-system.md) - Component rendering - [packages/README.md](./docs/packages/README.md) - Package system - [guides/SASS_CONFIGURATION.md](./docs/guides/SASS_CONFIGURATION.md) - Styling **Backend Developers**: - [DBAL_INTEGRATION.md](./docs/implementation/DBAL_INTEGRATION.md) - Database layer - [database/PRISMA_SETUP.md](./docs/database/PRISMA_SETUP.md) - ORM setup - [migrations/README.md](./docs/migrations/README.md) - Migrations **DevOps/Infrastructure**: - [deployments/README.md](./docs/deployments/README.md) - Deployment - [deployments/GITHUB_WORKFLOWS_AUDIT.md](./docs/deployments/GITHUB_WORKFLOWS_AUDIT.md) - CI/CD - [builds/CROSS_PLATFORM_BUILD.md](./docs/builds/CROSS_PLATFORM_BUILD.md) - Builds **QA/Testing**: - [TESTING_GUIDELINES.md](./docs/testing/TESTING_GUIDELINES.md) - Test standards - [testing/TESTING_IMPLEMENTATION_SUMMARY.md](./docs/testing/TESTING_IMPLEMENTATION_SUMMARY.md) - Implementation - [testing/FUNCTION_TEST_COVERAGE.md](./docs/testing/FUNCTION_TEST_COVERAGE.md) - Coverage --- ## πŸ” Search Tips ### Using VS Code 1. **Quick Open**: `Ctrl+P` (or `Cmd+P` on Mac) 2. **Search Examples**: - `testing` - Find testing files - `DBAL` - Find DBAL documentation - `refactoring` - Find refactoring guides - `arch/` - Browse architecture files ### Using File Search - `Ctrl+Shift+F` (or `Cmd+Shift+F` on Mac) to search within files - Search for "ERROR:", "TODO:", "FIXME:" to find action items --- ## πŸ“ Navigation Patterns ### From Root Files at the root level are kept minimal: - `README.md` - Project overview - `CONTRIBUTING.md` - Contribution guidelines - `START_HERE.md` - Entry point - All other docs are in `/docs` folder βœ… ### By Category Browse `/docs/{category}/README.md` for category overview: - `docs/architecture/README.md` - Architecture overview - `docs/testing/README.md` - Testing overview - `docs/implementation/README.md` - Implementation overview ### Quick References Most categories have quick-reference guides: - `QUICK_START.md` - Fast onboarding - `CHEAT_SHEET.md` - Quick lookup - `QUICK_REFERENCE.md` - Common patterns --- ## πŸ’‘ Pro Tips ### βœ… DO: - βœ… Start with [NEW_CONTRIBUTOR_PATH.md](./docs/getting-started/NEW_CONTRIBUTOR_PATH.md) if you're new - βœ… Use [NAVIGATION.md](./docs/NAVIGATION.md) to find anything - βœ… Check [troubleshooting/](./docs/troubleshooting/) if stuck - βœ… Reference [archive/](./docs/archive/) for historical context - βœ… Keep [Copilot Instructions](./docs/../../.github/copilot-instructions.md) handy ### ❌ DON'T: - ❌ Search randomly - use the navigation files - ❌ Refer to archived docs for current practices - ❌ Ignore the [5-level-system.md](./docs/architecture/5-level-system.md) - it's critical - ❌ Skip the [TESTING_GUIDELINES.md](./docs/testing/TESTING_GUIDELINES.md) - ❌ Add docs to root - everything goes in `/docs` folder --- ## 🀝 Contributing When you add new documentation: 1. **Save it in the right place** - Use the category structure 2. **Update the README.md** in that category 3. **Update [NAVIGATION.md](./docs/NAVIGATION.md)** - Add a link 4. **Add a brief description** - Help others find it 5. **Use consistent formatting** - Follow existing doc style For guidelines, see [ORGANIZATION.md](./docs/ORGANIZATION.md). --- ## πŸ†˜ Still Lost? Try these in order: 1. **[NAVIGATION.md](./docs/NAVIGATION.md)** - Find by category 2. **[NEW_CONTRIBUTOR_PATH.md](./docs/getting-started/NEW_CONTRIBUTOR_PATH.md)** - Structured learning 3. **[troubleshooting/](./docs/troubleshooting/)** - Common issues 4. **[INDEX.md](./docs/INDEX.md)** - Quick nav hub 5. **[Copilot Instructions](./docs/../../.github/copilot-instructions.md)** - Ask for help --- ## πŸ“š Full Documentation Tree See the complete documentation tree in [NAVIGATION.md](./docs/NAVIGATION.md). --- **Last Updated**: December 2025 **Next Task**: Go to [docs/getting-started/NEW_CONTRIBUTOR_PATH.md](./docs/getting-started/NEW_CONTRIBUTOR_PATH.md) to start learning! πŸš€