---
title: App Metadata
description: Define application containers with navigation, branding, and access control
---

# App Metadata

An **App** is a logical container that bundles objects, views, pages, and dashboards into a cohesive application experience. It defines the navigation structure, branding, and access permissions.

## Basic Structure

```typescript
const crmApp = {
  name: 'crm',
  label: 'CRM',
  version: '1.0.0',
  description: 'Customer Relationship Management',
  icon: 'briefcase',
  active: true,

  branding: {
    primaryColor: '#1a73e8',
    logo: '/assets/crm-logo.svg',
    favicon: '/assets/favicon.ico',
  },

  navigation: [
    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
    { type: 'dashboard', label: 'Sales Dashboard', dashboardName: 'sales_overview', icon: 'bar-chart' },
  ],

  requiredPermissions: ['crm_access'],
};
```

## App Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | `string` | ✅ | Machine name (`snake_case`) |
| `label` | `string` | ✅ | Display name |
| `version` | `string` | optional | App version |
| `description` | `string` | optional | App description |
| `icon` | `string` | optional | App icon (Lucide/Material) |
| `active` | `boolean` | optional | Is app active (default: `true`) |
| `isDefault` | `boolean` | optional | Is default app |
| `navigation` | `NavigationItem[]` | ✅ | Navigation tree |
| `branding` | `AppBranding` | optional | Visual customization |
| `requiredPermissions` | `string[]` | optional | Required permissions to access |
| `homePageId` | `string` | optional | Custom home page ID |
| `objects` | `string[]` | optional | Objects included in this app |
| `apis` | `string[]` | optional | API endpoints included |
| `mobileNavigation` | `object` | optional | Mobile-specific navigation |

## Navigation Items

The navigation tree supports five item types, combined to create rich menu structures:

### Object Navigation

Links to an object's list view:

```typescript
{ type: 'object', label: 'Accounts', objectName: 'account', icon: 'building', viewName: 'all_accounts' }
```

### Dashboard Navigation

Links to a dashboard:

```typescript
{ type: 'dashboard', label: 'Analytics', dashboardName: 'sales_overview', icon: 'bar-chart' }
```

### Page Navigation

Links to a custom page:

```typescript
{ type: 'page', label: 'Settings', pageName: 'app_settings', icon: 'settings', params: { tab: 'general' } }
```

### URL Navigation

Links to an external URL:

```typescript
{ type: 'url', label: 'Help Center', url: 'https://help.example.com', icon: 'help-circle', target: '_blank' }
```

### Group Navigation

Groups items into collapsible sections with children:

```typescript
{
  type: 'group',
  label: 'Sales',
  icon: 'dollar-sign',
  expanded: true,
  children: [
    { type: 'object', label: 'Accounts', objectName: 'account', icon: 'building' },
    { type: 'object', label: 'Contacts', objectName: 'contact', icon: 'users' },
    { type: 'object', label: 'Opportunities', objectName: 'opportunity', icon: 'trending-up' },
  ],
}
```

### Common Navigation Properties

All navigation items share these base properties:

| Property | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | Unique identifier |
| `label` | `string` | Display label |
| `icon` | `string` | Icon name |
| `visible` | `boolean \| string` | Visibility (boolean or expression) |

## Branding

Customize the visual appearance of the app:

```typescript
branding: {
  primaryColor: '#1a73e8',    // Hex color code
  logo: '/assets/logo.svg',   // Logo URL
  favicon: '/assets/icon.ico', // Favicon URL
}
```

| Property | Type | Description |
| :--- | :--- | :--- |
| `primaryColor` | `string` | Primary brand color (hex) |
| `logo` | `string` | Logo image URL |
| `favicon` | `string` | Favicon URL |

## Mobile Navigation

Configure mobile-specific navigation behavior:

```typescript
mobileNavigation: {
  mode: 'bottom',
  bottomNavItems: ['home', 'accounts', 'contacts', 'settings'],
}
```

## Complete Example

```typescript
const projectApp = {
  name: 'project_management',
  label: 'Project Management',
  version: '2.0.0',
  description: 'Track projects, tasks, and team workload',
  icon: 'folder-kanban',
  active: true,

  branding: {
    primaryColor: '#6366f1',
    logo: '/assets/pm-logo.svg',
  },

  navigation: [
    {
      type: 'page',
      label: 'Home',
      pageName: 'pm_home',
      icon: 'home',
    },
    {
      type: 'group',
      label: 'Projects',
      icon: 'folder',
      expanded: true,
      children: [
        { type: 'object', label: 'Projects', objectName: 'project', icon: 'folder' },
        { type: 'object', label: 'Tasks', objectName: 'project_task', icon: 'check-square', viewName: 'task_board' },
        { type: 'object', label: 'Milestones', objectName: 'milestone', icon: 'flag' },
      ],
    },
    {
      type: 'group',
      label: 'Reports',
      icon: 'bar-chart',
      children: [
        { type: 'dashboard', label: 'Overview', dashboardName: 'project_overview', icon: 'layout-dashboard' },
        { type: 'dashboard', label: 'Team Workload', dashboardName: 'team_workload', icon: 'users' },
      ],
    },
    {
      type: 'url',
      label: 'Documentation',
      url: 'https://docs.example.com/pm',
      icon: 'book-open',
      target: '_blank',
    },
  ],

  requiredPermissions: ['pm_access'],
  homePageId: 'pm_home',
};
```

## Related

- [Page Metadata](./page) — Custom pages referenced from navigation
- [Dashboard Metadata](./dashboard) — Dashboards referenced from navigation
- [View Metadata](./view) — Views displayed within navigation items
- [Permission Metadata](./permission) — Access control for apps
