metabuilder/packages/PACKAGE_STRUCTURE.md

Package Structure Guide

Quick Reference

Every MetaBuilder package follows this simple structure:

packages/my-package/
├── page-config/              [If package defines routes/pages]
│   ├── metadata.json
│   └── *.json                [Page configuration data]
├── workflow/                 [If package defines workflows]
│   ├── metadata.json
│   └── *.json                [Workflow definitions]
├── credential/               [If package needs API credentials]
│   ├── metadata.json
│   └── *.json                [Credential templates]
├── notification/             [If package sends notifications]
│   ├── metadata.json
│   └── *.json                [Notification templates]
├── component/                [If package defines reusable components]
│   ├── metadata.json
│   └── *.json                [Component definitions]
├── package.json              [Standard NPM package file]
├── README.md                 [Documentation]
└── ...other files...         [Source, tests, etc.]

Entity Folders

Each entity folder contains:

Folder	Purpose	When to Use
page-config	Routes/pages exposed by this package	If package has public pages/routes
workflow	Automation workflows	If package provides workflows
credential	API credentials or secrets	If package integrates with external APIs
notification	Notification templates	If package sends notifications
component	Reusable component definitions	If package defines UI components
ui_component	UI-specific components	Alternative for UI packages

File Organization

Inside each entity folder:

metadata.json (Required)

Describes what's in this folder:

{
  "entity": "page-config",
  "packageId": "my_package",
  "description": "Page routes defined by my_package",
  "version": "1.0.0"
}

Data Files (Optional)

Named by what they define:

page-config/
├── metadata.json
├── home.json          [Route /my-package/home]
└── dashboard.json     [Route /my-package/dashboard]

workflow/
├── metadata.json
├── user_onboard.json  [Workflow: onboard users]
└── sync_data.json     [Workflow: sync data]

credential/
├── metadata.json
└── api_keys.json      [API credential template]

Rules

1. One folder per entity type - Don't mix entities
2. Only data files - No code, scripts, or utilities
3. Always include metadata.json - Describes the folder
4. Keep it minimal - Only what the package actually needs

Examples

Package with Pages Only

packages/ui_home/
├── page-config/
│   ├── metadata.json
│   └── home.json
└── package.json

Package with Multiple Entity Types

packages/dashboard/
├── page-config/
│   ├── metadata.json
│   └── dashboard.json
├── workflow/
│   ├── metadata.json
│   └── daily_sync.json
└── package.json

Package with Just Components

packages/form_builder/
├── component/
│   ├── metadata.json
│   └── form_field.json
└── package.json

Navigation

When you see a package folder, immediately know what it provides:

• See page-config/ → This package defines routes
• See workflow/ → This package provides workflows
• See credential/ → This package needs API keys
• See notification/ → This package sends alerts
• See component/ → This package provides components

No guessing. No overthinking. Just look at the folders.

Anti-Patterns (What NOT to Do)

❌ DON'T create other folders:
packages/my-package/
├── seed/              ← Put this in page-config/, workflow/, etc.
├── seeds/             ← Wrong location
├── data/              ← Wrong location
├── schemas/           ← Wrong location
└── utils/             ← Wrong location

❌ DON'T put code files here:
packages/my-package/
├── page-config/
│   ├── loader.ts      ← NO: TypeScript code
│   └── utils.js       ← NO: Utilities

Adding to Your Package

To add entity data to an existing package:

1. Create the entity folder: packages/my-package/page-config/
2. Add metadata.json describing what's in it
3. Add data files for each entity (home.json, dashboard.json, etc.)
4. Done - the system will find and load it

See /packages/SEED_FORMAT.md for detailed seed data specification.

See Also

• /packages/SEED_FORMAT.md - Complete seed data documentation
• /packages/PACKAGE_AUDIT.md - Analysis of all 51 packages
• /dbal/shared/api/schema/entities/ - Entity definitions (source of truth)