# MetaBuilder Project Structure Complete and accurate project folder structure with explanations. ## Root Level Directories ``` /Users/rmac/Documents/metabuilder/ ├── config/ Configuration and linting ├── dbal/ Database abstraction layer (Phase 2 & 3) ├── deployment/ Deployment scripts and Docker configs ├── docs/ Documentation (this file) ├── e2e/ End-to-end tests (Playwright) ├── fakemui/ Material-UI inspired component library ├── frontends/ Frontend applications ├── old/ Legacy code (archive) ├── packages/ Application packages (51 total) ├── playwright-report/ Test reports ├── schemas/ Data schemas (YAML and JSON) ├── scripts/ Utility scripts ├── services/ Daemon services ├── spec/ Specification files ├── storybook/ Component documentation └── test-results/ Test output files ``` ## Detailed Structure ### config/ - Configuration Files ``` config/ ├── lint/ Linting configurations ├── misc/ Miscellaneous configs │ ├── env/ Environment variables │ └── json/ JSON configurations └── test/ Test configurations ``` **Purpose**: Centralized configuration for linting, testing, and environment setup. ### dbal/ - Database Abstraction Layer ``` dbal/ ├── development/ Phase 2: TypeScript DBAL (CURRENT) │ ├── dist/ Compiled JavaScript output │ ├── node_modules/ Dependencies │ ├── prisma/ Prisma schema and migrations │ ├── src/ TypeScript source code │ │ ├── core/ Core DBAL implementation │ │ ├── runtime/ Runtime utilities │ │ ├── seeds/ Seed data orchestration │ │ └── adapters/ Database adapters │ └── tests/ Unit tests │ ├── production/ Phase 3: C++ DBAL (FUTURE) │ ├── build-config/ Build configuration │ ├── docs/ C++ documentation │ ├── include/ C++ headers │ ├── lint-config/ Linting config │ ├── src/ C++ source code │ ├── tests/ C++ tests │ └── third-party/ External libraries │ ├── shared/ Shared across both implementations │ ├── api/ │ │ └── schema/ YAML entity schemas (SOURCE OF TRUTH) │ │ ├── entities/ Database entity definitions │ │ ├── operations/ Operation definitions │ │ └── capabilities.yaml │ ├── backends/ Database connection utilities │ ├── docs/ Implementation guides │ ├── prisma/ Prisma schema location │ ├── seeds/ │ │ ├── database/ Root seed data (YAML) │ │ │ ├── installed_packages.yaml │ │ │ └── package_permissions.yaml │ │ └── README.md Seed architecture docs │ └── tools/ Code generation tools │ └── docs/ General DBAL documentation ``` **Status**: - ✅ **Phase 2 (TypeScript)**: Production-ready, actively used - ⏳ **Phase 3 (C++)**: Design complete, implementation future - ✅ **Shared**: YAML schemas are source of truth for both phases **Key Files**: - `dbal/shared/api/schema/entities/` - Database entity definitions (YAML) - `dbal/development/src/core/client/factory.ts` - DBALClient factory - `dbal/shared/seeds/database/` - Root bootstrap seed data ### deployment/ - Deployment Configuration ``` deployment/ ├── config/ Deployment configurations ├── docker/ Docker compose and dockerfiles ├── env/ Environment templates ├── scripts/ Deployment scripts │ ├── bootstrap-system.sh System bootstrap process │ └── [other scripts] └── [deployment files] ``` **Purpose**: All deployment-related configurations and scripts for various environments (dev, staging, production). ### docs/ - Documentation ``` docs/ ├── archive/ Old/archived documentation ├── README_COMPONENTS.md ⭐ Component system hub ├── FAKEMUI_*.md Component documentation (6 guides) ├── COMPONENT_*.md Component guides ├── PROJECT_STRUCTURE.md This file ├── TESTING_GUIDE.md Testing methodology ├── CONTAINER_IMAGES.md Docker image documentation ├── PIPELINE_CONSOLIDATION.md CI/CD configuration ├── TODO_MVP_IMPLEMENTATION.md MVP checklist └── [other documentation] ``` **Status**: Comprehensive documentation with focus on components and testing. ### e2e/ - End-to-End Tests (Playwright) ``` e2e/ ├── api/ API endpoint tests ├── auth/ Authentication tests ├── crud/ Create/Read/Update/Delete tests ├── dbal-daemon/ DBAL daemon tests ├── playwright-report/ Test report output └── [test specs] ``` **Purpose**: Comprehensive end-to-end testing using Playwright. ### fakemui/ - Material Design Component Library ``` fakemui/ ├── fakemui/ Main component library │ ├── atoms/ Basic building blocks │ ├── data-display/ Data display components (26) │ ├── feedback/ Feedback components (6) │ ├── inputs/ Form inputs (28) │ ├── lab/ Experimental components │ ├── layout/ Layout components (18) │ ├── navigation/ Navigation components (22) │ ├── surfaces/ Surface components (cards, etc.) │ ├── theming/ Theme configuration │ ├── utils/ Utility components │ └── x/ Advanced components ├── icons/ Icon library (27+ icons) ├── contexts/ React contexts ├── components/ Custom QML components ├── qml-components/ QML component library ├── styles/ SCSS stylesheets ├── theming/ Theming system ├── widgets/ Widget library ├── COMPONENT_MAPPING.md ⭐ Inventory of 151+ components ├── index.ts Main export barrel file └── package.json NPM configuration ``` **Status**: ✅ Production-ready with 151+ components across 9 categories. **Key Facts**: - 151+ Material Design components - 9 categories (form, display, layout, navigation, modal, table, icons, feedback, advanced) - Type-safe registry available in frontend - Fully integrated with JSON component system ### frontends/ - Frontend Applications ``` frontends/ ├── cli/ CLI frontend (command-line interface) ├── dbal/ DBAL frontend utilities ├── nextjs/ Next.js web frontend (CURRENT) │ ├── node_modules/ Dependencies │ ├── public/ Static assets │ ├── src/ │ │ ├── app/ Next.js pages and API routes │ │ ├── components/ React components │ │ ├── lib/ │ │ │ ├── fakemui-registry.ts ⭐ 151+ component registry │ │ │ ├── packages/json/ JSON component rendering │ │ │ ├── dbal-client/ DBAL integration │ │ │ └── [other utilities] │ │ ├── styles/ CSS/SCSS │ │ └── types/ TypeScript types │ ├── package.json Dependencies │ └── tsconfig.json TypeScript configuration │ └── qt6/ Qt6 desktop frontend (future) ``` **Status**: - ✅ **Next.js**: Production-ready web frontend - 🔧 **CLI**: Utilities for command-line interface - ⏳ **Qt6**: Desktop frontend (future) **Key Integration**: - `frontends/nextjs/src/lib/fakemui-registry.ts` - Type-safe component registry - `frontends/nextjs/src/lib/packages/json/render-json-component.tsx` - JSON renderer ### old/ - Legacy Code ``` old/ └── src/ Legacy/archived source code ``` **Purpose**: Archive of old code from previous implementation phases. ### packages/ - Application Packages (51 Total) ``` packages/ ├── Core UI Packages (8) │ ├── ui_home/ Landing page │ ├── ui_header/ Header/navbar │ ├── ui_footer/ Footer │ ├── ui_auth/ Authentication UI │ ├── ui_login/ Login page │ ├── ui_intro/ Introduction page │ ├── ui_dialogs/ Dialog components │ └── ui_pages/ General pages │ ├── Admin/Management Packages (6) │ ├── admin_dialog/ │ ├── dashboard/ User dashboard │ ├── database_manager/ Database management │ ├── package_manager/ Package installation │ ├── role_editor/ Role management │ ├── schema_editor/ Schema editor │ └── user_manager/ User management │ ├── Feature Packages (37) │ ├── code_editor/ Code editing │ ├── component_editor/ Component editor │ ├── data_table/ Data table widget │ ├── form_builder/ Form builder │ ├── json_script_example/ JSON Script examples │ ├── media_center/ Media management │ ├── notification_center/ Notifications │ ├── workflow_editor/ Workflow editor │ ├── github_tools/ GitHub integration │ ├── social_hub/ Social features │ ├── forum_forge/ Forum │ ├── stream_cast/ Streaming │ ├── irc_webchat/ IRC chat │ ├── theme_editor/ Theme customization │ ├── css_designer/ CSS design tool │ ├── screenshot_analyzer/ Screenshot analysis │ ├── codegen_studio/ Code generation │ ├── testing/ Testing tools │ ├── arcade_lobby/ Arcade games │ ├── quick_guide/ Quick guide │ ├── config_summary/ Configuration summary │ ├── dropdown_manager/ Dropdown UI │ ├── nerd_mode_ide/ IDE mode │ ├── stats_grid/ Statistics │ ├── audit_log/ Audit logging │ ├── smtp_config/ SMTP configuration │ ├── nav_menu/ Navigation menu │ ├── route_manager/ Route management │ ├── package_validator/ Package validation │ ├── dbal_demo/ DBAL demonstrations │ └── [more packages...] │ └── Each package structure: ├── package.json Package manifest ├── page-config/ ⭐ Page definitions (routes) │ ├── metadata.json │ └── *.json Page configurations ├── component/ ⭐ Component definitions (NEW) │ ├── metadata.json │ └── *.json Component definitions (JSON declarative) ├── workflow/ Workflow definitions │ ├── metadata.json │ └── *.json Workflow configurations ├── credential/ API credentials │ ├── metadata.json │ └── *.json ├── notification/ Notification templates │ ├── metadata.json │ └── *.json ├── seed/ Package seed data │ └── metadata.json ├── src/ TypeScript source (if needed) └── [other files] ``` **Status**: 51 packages total - ✅ 12 core packages (bootstrap automatically) - ✅ 39 optional packages - ✅ Each package organized by entity type - ✅ Component system fully integrated (NEW) **Key Package**: - `ui_home` - Contains 5 example components showing all patterns ### schemas/ - Data Schemas ``` schemas/ ├── package-schemas/ Package system schemas (18+ files) │ ├── component.schema.json ⭐ Component definition schema │ ├── metadata_schema.json Package metadata │ ├── entities_schema.json Entity definitions │ ├── script_schema.json JSON Script specification │ ├── types_schema.json Type system │ ├── validation_schema.json Validation rules │ ├── api_schema.json API definitions │ ├── events_schema.json Event definitions │ ├── jobs_schema.json Job definitions │ ├── actions_schema.json Action definitions │ ├── permissions_schema.json Permission schema │ ├── workflow_schema.json Workflow schema │ └── [more schemas...] │ ├── yaml-schema/ YAML schema utilities │ ├── seed-data/ ⭐ Seed data validation schemas │ ├── page-config.schema.json Page/route validation │ ├── workflow.schema.json Workflow validation │ ├── credential.schema.json Credential validation │ ├── notification.schema.json Notification validation │ └── component.schema.json Component validation │ ├── SCHEMAS_README.md Schema system overview └── QUICKSTART.md Quick start guide ``` **Purpose**: - Define all system structures (database, packages, components) - Validate seed data before loading - Provide type definitions ### scripts/ - Utility Scripts ``` scripts/ └── [utility scripts] ``` **Purpose**: General-purpose scripts for development and maintenance. ### services/ - Daemon Services ``` services/ └── media_daemon/ Media processing daemon └── [media service implementation] ``` **Purpose**: Long-running services (Phase 3 includes DBAL daemon at `/dbal/production/`). ### spec/ - Specification Files ``` spec/ └── [specification documents] ``` **Purpose**: Technical specifications and design documents. ### storybook/ - Component Documentation ``` storybook/ ├── public/ Static assets └── src/ Storybook stories ``` **Purpose**: Interactive component documentation using Storybook. ## Key Files at Root Level | File | Purpose | |------|---------| | `CLAUDE.md` | **AI Assistant Instructions** (THIS IS CRITICAL) | | `ARCHITECTURE.md` | System architecture and data flow | | `AGENTS.md` | Core principles for AI agents | | `README.md` | Project overview and quick start | | `ROADMAP.md` | Project vision and timeline | | `TESTING.md` | Testing strategy and guides | | `DBAL_REFACTOR_PLAN.md` | Phase 2 cleanup implementation | | `TECH_DEBT.md` | Technical debt tasks (bot-actionable) | | `package.json` | Root dependencies and scripts | | `tsconfig.json` | TypeScript configuration | | `playwright.config.ts` | E2E test configuration | | `.github/` | GitHub Actions, issue templates, workflow | ## Important Directories to Know ### For AI Assistants 1. **Read First**: `CLAUDE.md` - All instructions for you 2. **Second**: `AGENTS.md` - Core principles and patterns 3. **Reference**: `ARCHITECTURE.md` - System design ### For Development 1. **Frontend Code**: `frontends/nextjs/src/` 2. **DBAL Code**: `dbal/development/src/` 3. **Packages**: `packages/` (51 packages) 4. **Schemas**: `schemas/` (YAML and JSON) 5. **Components**: `fakemui/` (151+ components) ### For Testing 1. **E2E Tests**: `e2e/` 2. **Unit Tests**: `dbal/development/tests/` 3. **Test Config**: `playwright.config.ts` ### For Deployment 1. **Scripts**: `deployment/scripts/` 2. **Docker**: `deployment/docker/` 3. **Environment**: `deployment/env/` ## Statistics | Metric | Value | |--------|-------| | Total Directories | 104+ | | Packages | 51 | | Core Packages | 12 | | Optional Packages | 39 | | Fakemui Components | 151+ | | Component Categories | 9 | | Documentation Files | 30+ | | Schema Files | 25+ | ## Structure Consistency ✅ **Well-organized**: Clear separation of concerns ✅ **Documented**: Each major section has clear purpose ✅ **Modular**: Packages are self-contained ✅ **Layered**: Clear separation between DBAL, frontend, packages ✅ **Scalable**: Easy to add new packages or components ## Alignment with CLAUDE.md This document aligns with CLAUDE.md by: - ✅ Documenting exact file locations mentioned in CLAUDE.md - ✅ Explaining package-based architecture - ✅ Highlighting DBAL layers (Phase 2 & 3) - ✅ Showing component system integration - ✅ Providing complete directory listing - ✅ Clarifying which directories are current vs. future **See CLAUDE.md for** development instructions, workflow, and patterns. **Use this file for** understanding actual directory structure. --- **Last Updated**: 2026-01-16 **Version**: 1.0.0 **Status**: Comprehensive and Accurate