> Source: https://builder-docs.ema.ai/core-concepts/frontier-apps
> Title: Frontier Apps

# Frontier Apps

Frontier Apps are custom web applications that run on the Ema platform and connect to AI Employees. They extend the platform's capabilities beyond the built-in interaction interfaces (chat, dashboard, document editor) by allowing deployment of purpose-built applications.

## What Frontier Apps Are

A Frontier App is a containerized web application deployed and managed through the Ema platform. Each app:

-   Is provisioned from a **catalog entry** that defines its image, configuration parameters, and resource requirements.
-   Connects to one or more **AI Employees** via named slots (AI Employee (AIE) bindings).
-   Runs on Ema-managed infrastructure with a dedicated subdomain and URL.
-   Optionally receives a provisioned database.

### AIE Interaction Patterns

Every Frontier App is built on top of AI Employees (AIEs). There are three integration patterns, each suited to a different use case:

Pattern

Description

Best For

**Dashboard AIE**

Structured input/output. Submit data, AI processes it, get structured results back.

Document parsing, data extraction, classification, report generation.

**Chat AIE**

Conversational. Send messages, receive replies in a back-and-forth exchange.

Q&A bots, assistants, interactive workflows.

**Docgen AIE**

Document generation. Provide inputs and receive generated documents.

Report generation, templated document creation.

The template includes pre-built API routes, React Query hooks, and MongoDB models for both the Dashboard and Chat patterns. You configure your AIEs and build the UI -- the plumbing is handled for you.

## App Catalog

The catalog is a registry of available app templates. Each catalog entry specifies:

Field

Description

**Name and slug**

Human-readable name and URL-safe identifier.

**Description**

What the app does.

**Category**

Organizational category (e.g., analytics, customer-facing).

**Visibility**

`PUBLIC` (available to all tenants) or `RESTRICTED` (limited access).

**Configurable parameters**

Named parameters the deployer can set (e.g., API keys, feature flags). Each has a name, type (`string`, `number`, `boolean`), required flag, default value, and description.

**Required AIE slots**

Named slots that must be bound to AI Employees. Each slot specifies an expected interaction type (e.g., `PERSONA_INTERACTION_TYPE_DASHBOARD`) and optional input/output schemas.

**Resource spec**

CPU and memory requirements.

**Health check path**

Endpoint the platform uses to verify the app is running.

## App Lifecycle

A deployed Frontier App transitions through the following states:

```
DEPLOYING --> RUNNING --> STOPPED --> DELETED
 | ^
 | |
 v (start)
 FAILED
```

State

Description

`DEPLOYING`

The app is being built and provisioned. See [deploy stages](#deploy-stages) below.

`RUNNING`

The app is live and accessible at its URL.

`ACTIVE`

Alias for RUNNING in some contexts.

`STOPPED`

The app has been manually stopped. Can be restarted.

`FAILED`

Deployment or runtime error. Check logs for details.

`DEGRADED`

The app is running but experiencing issues (e.g., partial failures or reduced performance).

`DELETED`

The app has been permanently removed.

### Deploy Stages

During the `DEPLOYING` state, the app progresses through internal stages:

1.  **BUILDING** -- Container image is being built or pulled.
2.  **PROVISIONING\_DB** -- Database is being created (if required).
3.  **INSTALLING** -- App is being deployed to the cluster.
4.  **AWAITING\_IP** -- Waiting for an external IP assignment.
5.  **CHECKING\_HEALTH** -- Verifying the app responds on its health check endpoint.

### Platform-Injected Configuration

At deploy time, the platform automatically creates a ConfigMap with the following environment variables:

Variable

Source

Example

`AUTH_JWKS_URL`

Platform's JWKS endpoint

`http://frontier-apps.frontier-apps-platform:8000/jwks`

`AUTH_ISSUER`

From Helm values

`dev.ema.co`

`NEXT_PUBLIC_AI_EMPLOYEE_API_URL`

From Helm values

`https://api.dev.ema.co`

`MONGODB_URI`

Provisioned by deployer

`mongodb://myapp_user:...@10.10.0.12:27017/frontier_myapp`

`AIE_*_PERSONA_ID`

From tenant's AIE bindings

`AIE_RESUME_PARSER_PERSONA_ID=424a03bc-...`

## Deploying a Frontier App

1.  Navigate to the **Apps** page from the main navigation.
2.  Browse the catalog or search for an app by name.
3.  Click **Deploy** (or the equivalent action) on a catalog entry.
4.  In the deploy modal, configure:
    -   **Parameter values**: Fill in any configurable parameters defined by the catalog entry.
    -   **AIE bindings**: For each required AIE slot, select an AI Employee from your tenant. The slot's interaction type determines which AI Employees are eligible.
5.  Submit to start deployment. The app enters `DEPLOYING` state.

### Post-Deployment

After all deploy stages complete, the app is live at `https://<slug>.apps.dev.ema.co`.

### Updating a Deployed App

To update an already-deployed app:

1.  Push new code to `main` -- GitHub Actions builds a new container image automatically.
2.  In the platform UI, the app can be redeployed with the new image tag.
3.  AIE bindings and configurable parameters can be changed via the platform UI's **Update** flow, which triggers a redeployment.

## Managing Deployed Apps

The **My Apps** tab on the Apps page shows all apps deployed in your tenant.

Available operations:

Operation

Description

**Stop**

Pause a running app. The app becomes `STOPPED` and is no longer accessible.

**Start**

Resume a stopped app.

**Delete**

Permanently remove the app and its resources.

Each deployed app shows:

-   App name and description (from the catalog entry).
-   Current status.
-   App URL (accessible when status is `RUNNING`).
-   Deployed image tag and deployment timestamp.

## AIE Bindings

AIE bindings connect a Frontier App to one or more AI Employees. Each binding maps a named **slot** in the app to a specific AI Employee (persona).

```json
{
 "slot_name": "primary_assistant",
 "persona_id": "abc-123-def"
}
```

The slot definition in the catalog entry can specify:

-   **Interaction type**: The expected interface type (e.g., dashboard, chat).
-   **Input schema**: The data structure the app sends to the AI Employee.
-   **Output schema**: The data structure the app expects back.

### How Slots Work at Runtime

When a tenant deploys your app and binds a persona to a slot, the platform injects the persona ID as an environment variable into the app's ConfigMap. For example, if the slot is named `AIE_RESUME_PARSER_PERSONA_ID`, the platform sets:

```
AIE_RESUME_PARSER_PERSONA_ID=424a03bc-fc5d-4a71-8acf-36d1f9ba7344
```

Your app reads this env var automatically -- no code changes are needed per tenant.

## Technical Details

-   Each app gets a unique **subdomain** and **app URL** within the Ema platform.
-   Apps are deployed as containers with configurable CPU and memory resources.
-   The platform manages **health checking** via the configured health check path and port.
-   **Database provisioning** is automatic for catalog entries that require it. The database name is tracked per deployment.

### Architecture

Each Frontier App is an isolated Next.js application with its own MongoDB database, deployed to a shared Kubernetes namespace. The app communicates with two backends:

```
Browser (React)
|
| fetch('/api/...') <- same-origin, your app's API
v
Your App's API Routes (/api/*)
| - Authentication via JWT
| - MongoDB read/write
| - Business logic
|
| AIE SDK calls (server-side only)
v
Ema Core API
- AI Employee processing
```

Backend

URL

Used By

**This app's API**

`/api/*` (same origin)

Client components, React Query hooks

**Ema Core API**

Via `NEXT_PUBLIC_AI_EMPLOYEE_API_URL`

Server-side AIE SDK only

> [WARNING]
> **Important:** Client components must never call the Ema Core API directly. All AIE communication goes through your app's API routes, which handle authentication, caching, and the AIE SDK calls.

### Key Design Principles

Principle

How It's Achieved

**Database Isolation**

Each app gets its own MongoDB database on the shared cluster.

**Shared Auth**

JWT tokens from ema-app SSO, verified via JWKS endpoint.

**Self-Service**

Fork the starter template; GitHub Actions handle provisioning and deployment.

**Consistent UX**

Ema Design System provides a shared component library.

* * *

**Previous**: [Projects](/legacy-docs/core-concepts/projects) | **Back to**: [Core Concepts Index](/legacy-docs/core-concepts/frontier-apps)