Metadata Discovery Architecture

Framework M utilizes a Code-First Metadata Discovery system that automatically exposes DocType configuration to the frontend and other consumers through a generalized, secure, and extensible API.

Core Philosophy

Metadata is defined directly on the DocType as an internal Meta class. The framework automatically indexes, whitelists, and serves this metadata, ensuring the UI remains in sync with the backend requirements without manual "bridge" code.

1. Automated Extraction

The BaseDocType provides a get_meta_flags() helper that automatically collects "simple" attributes (bool, str, int, float) and the specialized ui_meta dictionary from the internal Meta class. This ensures all UI and behavioral flags are immediately available for the discovery engine.

class Invoice(DocType):
    class Meta:
        show_in_desk = True    # Automatically collected as a flag
        label = "Tax Invoice" # Automatically collected as a flag
        ui_meta = {           # Whitelisted structured config
            "icon": "FileText",
            "group": "Accounts"
        }

2. Dynamic Whitelist (Security)

To prevent "Discovery Escalation" and Information Leakage, the metadata discovery API only exposes and filters flags that are explicitly registered in the Metadata Whitelist.

Safe-by-Default

By default, the MetaRegistry whitelists standard UI and behavior flags:

• show_in_desk
• api_resource
• is_child_table
• is_submittable
• label
• module
• ui_meta (Structured configuration)

Extensibility for Apps

Custom apps and plugins can "publish" their own metadata flags to the discovery API during their initialization phase:

# In your app's initialization
from framework_m_core.registry import MetaRegistry

registry = MetaRegistry.get_instance()
registry.register_meta_key("wms_enabled")
registry.register_meta_key("pos_sync_priority")

3. Discovery API

The discovery API (/api/meta/doctypes) provides a generalized filtering mechanism. It accepts any whitelisted metadata key as a query parameter and returns a flexible metadata dictionary.

Examples

• Filter by Sidebar Visibility: GET /api/meta/doctypes?show_in_desk=true
• Filter for Submittable Records: GET /api/meta/doctypes?is_submittable=true

Unified Response Structure

The API returns a metadata dictionary for each DocType:

{
  "name": "Todo",
  "label": "To-Do",
  "module": "Personnel",
  "metadata": {
    "show_in_desk": true,
    "api_resource": true,
    "ui_meta": {
      "icon": "FileText",
      "group": "Accounts",
      "order": 100,
      "list": {
        "columns": [
          { "field": "name", "label": "ID", "width": 120 },
          { "field": "customer", "label": "Customer" }
        ]
      }
    }
  }
}

4. UI Meta Property Reference

Below are the standard properties supported by the Framework M Desk shell. These can be defined directly in your DocType's Meta.ui_meta dictionary.

Namespace	Property	Description
Root	label	Sidebar navigation label (overrides DocType name).
	icon	Navigation icon name (e.g., Lucide icon names).
	group	Sidebar module grouping/category.
	order	Sorting order within the sidebar group (lower is higher).
list	columns	Array of { field, label, width, sortable } for the table.
	defaultSort	{ field, direction } (e.g., "asc", "desc").
form	sections	Array of { label, fields, collapsible } for layout.
	tabs	Array of { label, sections } for tabbed layouts.
additional_views	kanban	{ groupByField, cardTitleField, cardSubtitleField }.
	tree	{ parentField, labelField, orderField }.
	calendar	{ startField, endField, titleField, colorField }.

5. UI Shell Integration

The @framework-m/desk shell utilizes this API to build its navigation dynamically. By fetching with ?show_in_desk=true, the shell maintains a lean sidebar that only shows DocTypes intended for user interaction, while still allowing the "Omni-Search" and "Info" hovers to use the expanded metadata dictionary.

[!IMPORTANT] Always register your meta keys in the MetaRegistry if you want them to be filterable or visible in the basic listing API.