# App Manifest

The app manifest (`teachfloor-app.json`) defines your app's metadata, capabilities, permissions, and behavior.

## Overview

The manifest is a JSON file at the root of your project:
- Defines app name, description, and version
- Specifies where your app displays (viewports)
- Declares required permissions
- Sets distribution type (public/private)
- Configures post-installation actions

## Basic Structure

Here's a minimal manifest:

```json
{
  "id": "abc123def456",
  "version": "1.0.0",
  "name": "My App",
  "description": "A simple Teachfloor app",
  "distribution_type": "private"
}
```

## Complete Manifest Example

```json
{
  "id": "abc123def456",
  "version": "1.2.0",
  "name": "Course Notes",
  "description": "Take notes while browsing courses and modules",
  "distribution_type": "public",

  "ui_extension": {
    "views": [
      {
        "viewport": "teachfloor.dashboard.course.detail",
        "component": "CourseNotesView"
      },
      {
        "viewport": "teachfloor.dashboard.course.module.detail",
        "component": "ModuleNotesView"
      }
    ],
    "permissions_policy": {
      "microphone": ["http://localhost:3000"],
      "purpose": "Enable speech-to-text for note taking"
    }
  },

  "permissions": [
    {
      "permission": "user_read",
      "purpose": "Display your name and profile"
    },
    {
      "permission": "course_read",
      "purpose": "Display course information in notes"
    }
  ],

  "post_install_action": {
    "type": "settings",
    "url": "https://example.com/setup"
  }
}
```

## Field Reference

### Required Fields

#### `id` (string)
Unique identifier for your app. Auto-generated during app creation.

```json
"id": "abc123def456"
```

**Rules:**
- Must be unique across all Teachfloor apps
- Cannot be changed after creation
- Automatically generated by CLI

#### `version` (string)
Semantic version of your app following [semver](https://semver.org/) format.

```json
"version": "1.2.3"
```

**Rules:**
- Must follow `MAJOR.MINOR.PATCH` format
- Examples: `1.0.0`, `2.1.5`, `0.5.0-beta`
- Increment when uploading new versions

**Versioning Guidelines:**
- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

#### `name` (string)
Display name shown to users in the marketplace and dashboard.

```json
"name": "Course Notes"
```

**Rules:**
- Maximum 50 characters
- Should be descriptive and unique
- Used in app listings and UI

#### `description` (string)
Short description of what your app does.

```json
"description": "Take notes while browsing courses and modules"
```

**Rules:**
- Maximum 200 characters
- Should clearly explain the app's purpose
- Displayed in marketplace listings

### Distribution

#### `distribution_type` (string)
Determines how your app is distributed.

```json
"distribution_type": "public"
```

**Values:**
- `"private"`: Only your organization can install (default)
- `"public"`: Listed in marketplace for all organizations

:::info
See [Deployment Guide](./advanced-topics/deployment#distribution-types) for detailed information on private vs public distribution.
:::

### UI Extension

#### `ui_extension` (object, optional)
Defines where and how your app displays in the platform.

:::info
The `ui_extension` field is optional. Apps without it can function as backend integrations listening to platform events.
:::

##### `views` (array)
List of views your app provides.

```json
"ui_extension": {
  "views": [
    {
      "viewport": "teachfloor.dashboard.course.list",
      "component": "CourseListView"
    },
    {
      "viewport": "teachfloor.dashboard.course.detail",
      "component": "CourseDetailView"
    }
  ]
}
```

**View Object:**
- `viewport` (string): Where the view displays (must be an exact match to an available viewport)
- `component` (string): React component name (must match filename without extension)

:::caution
Viewports require exact string matches. Wildcard patterns are not supported. See [Viewports System](./viewports) for available viewports.
:::

##### `permissions_policy` (object)
Browser permissions your app needs (microphone, camera, etc.).

```json
"ui_extension": {
  "permissions_policy": {
    "microphone": ["http://localhost:3000", "https://app.teachfloor.com"],
    "camera": ["http://localhost:3000"],
    "purpose": "Enable video recording for assignments"
  }
}
```

**Available Permissions:**
- `microphone`: Audio input
- `camera`: Video input
- `geolocation`: Location access
- `clipboard-write`: Clipboard access

**Fields:**
- Permission name: Array of allowed origins
- `purpose`: User-facing explanation (required)

### Permissions

#### `permissions` (array)
Platform permissions your app needs to access Teachfloor resources.

```json
"permissions": [
  {
    "permission": "course_read",
    "purpose": "Display course information in widgets"
  },
  {
    "permission": "user_events_read",
    "purpose": "Track learning progress"
  }
]
```

**Permission Object:**
- `permission` (string): Permission identifier
- `purpose` (string): User-facing explanation of why you need it

**Important**:
- Only request permissions you actually use
- Provide clear, user-facing explanations
- Users see permission requests during installation
- Write permissions (`*_write`) automatically include read access

:::info
See [Permissions Reference](./advanced-topics/permissions) for the complete list of available permissions, their descriptions, and permission hierarchy.
:::

### Post-Install Action

#### `post_install_action` (object)
Defines what happens after a user installs your app.

```json
"post_install_action": {
  "type": "settings"
}
```

**Type: Settings**
Redirect to app settings page:
```json
{
  "type": "settings"
}
```

**Type: External**
Redirect to external URL:
```json
{
  "type": "external",
  "url": "https://example.com/setup?user=123"
}
```

**Use Cases:**
- Configuration wizard
- Account connection
- Welcome tutorial
- Feature introduction

## Manifest Validation

The CLI automatically validates your manifest before upload.

### Validation Rules

#### Required Fields
- `id`, `version`, `name` must be present

#### Version Format
- Must match semver pattern: `^\d+\.\d+\.\d+(-[\w.]+)?$`
- Valid: `1.0.0`, `2.1.5`, `1.0.0-beta.1`
- Invalid: `1.0`, `v1.0.0`, `1.0.0.0`

#### Component Names
- Must be valid React component names
- PascalCase only
- Valid: `MyView`, `CourseDetailView`
- Invalid: `myView`, `my-view`, `my_view`

#### Viewport Names
- Must match known viewport patterns
- See [Viewports documentation](./viewports)

### Manual Validation

The manifest is automatically validated when you run:

```bash
teachfloor apps start
# or
teachfloor apps upload
```

## Managing Manifests

### Updating Metadata

#### Via CLI Commands

Update distribution type:
```bash
teachfloor apps set distribution
```

Add permission:
```bash
teachfloor apps grant permission
```

Remove permission:
```bash
teachfloor apps revoke permission
```

Add view:
```bash
teachfloor apps add view
```

Remove view:
```bash
teachfloor apps remove view
```

#### Manual Editing

1. Open `teachfloor-app.json` in your editor
2. Make changes
3. Save the file
4. Run `teachfloor apps start` or `teachfloor apps upload`

The CLI will validate and upload the updated manifest.

### Version Management

Once a version is published, it becomes locked and cannot be modified. To release updates, increment the version number and upload again.

:::info
See [Deployment Guide](./advanced-topics/deployment#version-management) for complete information on version states, semantic versioning, and deployment process.
:::

### Multi-Environment Manifests

Use different manifests for development and production:

**Development** (`teachfloor-app.dev.json`):
```json
{
  "id": "abc123",
  "version": "1.0.0-dev",
  "name": "My App (Dev)",
  "distribution_type": "private",
  "ui_extension": {
    "permissions_policy": {
      "microphone": ["http://localhost:3000"]
    }
  }
}
```

**Production** (`teachfloor-app.json`):
```json
{
  "id": "abc123",
  "version": "1.0.0",
  "name": "My App",
  "distribution_type": "public",
  "ui_extension": {
    "permissions_policy": {
      "microphone": ["https://app.teachfloor.com"]
    }
  }
}
```

Start with custom manifest:
```bash
teachfloor apps start --manifest teachfloor-app.dev.json
```

## Next Steps

→ Continue to [Viewports System](./viewports)

## Additional Resources

- [Best Practices](./references/best-practices) - Naming, descriptions, permissions, and versioning guidelines
- [Troubleshooting Guide](./references/troubleshooting) - Common manifest errors and solutions
- [Examples](./references/examples) - Complete manifest examples
- [Permissions Reference](./advanced-topics/permissions)
- [CLI Commands](./references/cli)