> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understanding Components, Packages, Content Types, and Content in Metabind

Metabind is built around an integrated system of concepts that work together to enable flexible content creation and management. This page explains the key building blocks of the platform.

## Components

**Components** are the fundamental building blocks of Metabind. They define reusable UI elements that can be rendered across multiple platforms.

Components come in two varieties:

<CardGroup cols={2}>
  <Card title="View Components" icon="eye">
    Standard UI components for displaying content. Examples: `ProductCard`, `ArticleParagraph`, `HeroImage`
  </Card>

  <Card title="Layout Components" icon="table-columns">
    Define the overall structure for entire content types. Examples: `ArticleLayout`, `ProductPageLayout`
  </Card>
</CardGroup>

### Key Characteristics

* Written in **BindJS** (JavaScript with SwiftUI-inspired API)
* Render as **native UI** on each platform (SwiftUI, Jetpack Compose, React)
* Maintain **draft** and **published** states
* Can have **bound assets** (images, fonts, etc.)
* Only receive version numbers when included in a Package

```javascript theme={null}
// Example BindJS component
const metadata = () => ({
  title: 'Product Card',
  description: 'Displays product information in a card format'
});

const properties = () => ({
  title: PropertyString({ title: 'Title', required: true }),
  price: PropertyNumber({ title: 'Price', min: 0 }),
  image: PropertyAsset({ title: 'Product Image' })
});

const body = (props) => {
  return VStack({ spacing: 12 }, [
    Image(props.image),
    Text(props.title).font('headline'),
    Text(`$${props.price}`).foregroundStyle(Color('secondary'))
  ]);
};
```

## Component Collections

**Component Collections** are organizational units that group related components together. They provide logical grouping in the CMS UI without affecting the final package structure.

* Can exist at the root level or within folders
* Help teams organize components by feature, type, or any other criteria
* Collection structure is flattened when creating packages

## Packages

**Packages** create immutable snapshots of all components in a project at a specific point in time.

### Key Characteristics

* Use **semantic versioning** (e.g., `1.0.0`, `2.1.3`)
* **Immutable** once created (cannot be modified)
* Automatically **publish** all draft/modified components
* Include all **component-bound assets**
* Snapshot **project dependencies** at creation time

| Package Actions       | Effect on Components                                                 |
| --------------------- | -------------------------------------------------------------------- |
| Creation              | Publishes all draft and modified components with new version numbers |
| Versioning            | Uses semantic versioning (MAJOR.MINOR.PATCH)                         |
| Dependency Management | Snapshots project dependencies at creation time                      |
| Asset Management      | Includes all component-bound assets                                  |

### Draft Package Workflow

For development and preview, Metabind provides a **draft package**: a virtual package composed of the latest draft components. This enables preview and iteration before formal publication.

## Content Types

**Content Types** define specific kinds of content (e.g., "Article", "Product", "Recipe").

### Key Characteristics

* Associated with a **layout component** that determines structure
* Specify an **allowlist of components** that can be used within the content
* Reference specific **package versions** for component stability
* Include **template content** examples to help users get started
* Support **draft** and **published** status with independent versioning

```json theme={null}
{
  "name": "Article",
  "layoutComponentId": "ArticleLayout",
  "componentIdsAllowList": [
    "ArticleParagraph",
    "ArticleHeading",
    "ArticleImage",
    "ArticleQuote"
  ],
  "packageVersion": "1.0.0"
}
```

### Component Groups

Content Types can organize allowed components into logical groups:

```json theme={null}
{
  "componentIdsAllowList": [
    {
      "id": "questions",
      "name": "Question Components",
      "componentIds": ["Paragraph", "MathEquation", "Diagram"]
    },
    {
      "id": "answers",
      "name": "Answer Components",
      "componentIds": ["MultipleChoice", "NumericInput", "Drawing"]
    }
  ]
}
```

## Content

**Content** items are concrete instances of Content Types. They contain the actual data that will be rendered by components.

### Key Characteristics

* Reference a specific **Content Type version**
* Derive **package version** and **allowed components** from the Content Type
* Can be created from **templates** or from scratch
* Follow the same **status management** as other entities (draft, published, etc.)
* Store content as **JSON** matching the layout component's schema

```json theme={null}
{
  "name": "Getting Started with Metabind",
  "typeId": "article",
  "typeVersion": 2,
  "packageVersion": "1.0.0",
  "content": {
    "title": "Getting Started with Metabind",
    "heroImage": "asset123",
    "author": "Jane Doe",
    "components": [
      {
        "type": "ArticleParagraph",
        "text": "Welcome to Metabind..."
      },
      {
        "type": "ArticleHeading",
        "text": "Key Features",
        "level": 2
      }
    ]
  }
}
```

## Template Content

**Template Content** provides pre-built content examples that demonstrate how to use a Content Type.

* Serve as starting points for creating new content
* Follow the structure defined by the layout component
* Are locked to specific package versions
* Can be published and versioned independently

## Assets

**Assets** represent media files (images, videos, documents, etc.) stored on the CDN.

### Two Types of Asset Usage

1. **Component-bound assets**: Attached to components (e.g., icons, backgrounds). These are included in packages.
2. **Content assets**: Referenced by content items (e.g., article images). These are managed separately.

## Saved Searches

**Saved Searches** are project-level search configurations for filtering content and assets.

* Support user favorites for quick access
* Maintain usage statistics for optimization
* Can be organized in folders

## Folders

**Folders** create hierarchical structures for organizing saved searches.

* Support custom ordering
* Use a decimal-based ordering system for easy reordering

<Note>
  Component Collections serve as the folder mechanism for organizing components. The Folders feature is specifically designed for saved search organization.
</Note>

## How It All Fits Together

```mermaid theme={null}
graph TD
    A[Components] -->|Snapshot into| B[Package v1.0.0]
    B -->|Referenced by| C[Content Type]
    C -->|Defines structure for| D[Content]
    C -->|Provides| E[Template Content]
    E -->|Starting point for| D
    D -->|Delivered via| F[REST/GraphQL API]
    F -->|Rendered by| G[Mobile App]
```

The typical workflow:

1. **Create Components** using BindJS
2. **Publish a Package** to snapshot components
3. **Create a Content Type** referencing the package
4. **Create Content** using the Content Type
5. **Deliver Content** via API to mobile apps
6. **Render natively** using the BindJS runtime