# Usage

### <mark style="color:red;">What is UI Protocol?</mark>

UI Protocol provides a standardized way for micro-frontend applications to communicate with their host (shell) applications. Built on the `postMessage` API, it handles:

* **Data Sharing** - Pass data from shell to client applications
* **Actions** - Trigger shell-side operations from client applications
* **Navigation** - Coordinate routing between applications
* **UI Helpers** - Display modals, toasts, and other UI elements

### <mark style="color:red;">Architecture</mark>

```
┌───────────────────────────────────────────────────────────┐
│                    Shell Application                      │
│                  (Omnitron, Seller Center)                │
│  ┌─────────────────────────────────────────────────────┐  │
│  │                  AppShellProvider                   │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │  │
│  │  │   Client    │  │   Client    │  │   Client    │  │  │
│  │  │  (iframe)   │  │  (iframe)   │  │  (iframe)   │  │  │
│  │  │             │  │             │  │             │  │  │
│  │  │ AppClient   │  │ AppClient   │  │ AppClient   │  │  │
│  │  │  Provider   │  │  Provider   │  │  Provider   │  │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘
```

#### Shell Application

The **shell** (or host) is the main application that embeds micro-frontends. It uses `@akinon/app-shell` to:

* Register and manage micro-frontend applications
* Share data with embedded clients
* Define actions that clients can invoke
* Handle navigation requests

Examples: Omnitron, Seller Center

#### Client Application

A **client** is a micro-frontend embedded within a shell via iframe. It uses `@akinon/app-client` to:

* Receive shared data from the shell
* Invoke shell-defined actions
* Request navigation changes
* Display UI elements (modals, toasts)

Examples: Marketplace Dashboard, AI Powered Search, custom plugins

### <mark style="color:red;">Application Types</mark>

#### Fullpage Applications

Fullpage applications occupy the entire content area within the shell. They function as complete user interfaces with their own routing and state management.

```
┌──────────────────────────────────────┐
│  Shell (Header, Sidebar)             │
│  ┌────────────────────────────────┐  │
│  │                                │  │
│  │     Fullpage Client App        │  │
│  │        (entire area)           │  │
│  │                                │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘
```

#### Plugin Applications

Plugin applications are smaller widgets embedded in specific sections of a page. Multiple plugins can coexist on the same page.

```
┌──────────────────────────────────────┐
│  Shell Page                          │
│  ┌──────────┐  ┌──────────────────┐  │
│  │ Plugin A │  │   Shell Content  │  │
│  └──────────┘  │                  │  │
│  ┌──────────┐  │                  │  │
│  │ Plugin B │  │                  │  │
│  └──────────┘  └──────────────────┘  │
└──────────────────────────────────────┘
```

### <mark style="color:red;">Prerequisites</mark>

| Requirement | Version            |
| ----------- | ------------------ |
| Node.js     | Hydrogen or higher |
| React       | 18.2.0 or higher   |

### <mark style="color:red;">Installation</mark>

Choose the library based on your application type:

#### For Shell Applications

```bash
pnpm add @akinon/app-shell
```

#### For Client Applications

We recommend using the CLI to scaffold client applications. See the [CLI](/akinon-ui/cli/introduction.md) documentation for details.

```bash
pnpm create akinon-app
```

Or install manually:

```bash
pnpm add @akinon/app-client
```

### <mark style="color:red;">Communication Flow</mark>

1. **Shell initializes** with shared data, actions, and navigation config
2. **Client loads** inside an iframe and connects to the shell
3. **Shell broadcasts** data to all connected clients
4. **Client requests** actions or navigation changes
5. **Shell executes** the request and optionally responds

```
Shell                              Client
  │                                   │
  │◄──────── Client connects ─────────│
  │                                   │
  │────────── Share data ────────────►│
  │                                   │
  │◄─────── Request action ───────────│
  │                                   │
  │──────── Execute & respond ───────►│
  │                                   │
```

### <mark style="color:red;">Benefits</mark>

* **Modularity** - Develop and deploy micro-frontends independently
* **Consistency** - Standardized communication patterns across all applications
* **Security** - Isolated iframes with controlled message passing
* **Scalability** - Easy to add new micro-frontends without modifying the shell
* **Developer Experience** - Type-safe APIs with React hooks

### <mark style="color:red;">Next Steps</mark>

* [Quick Start](/akinon-ui/ui-protocol/quick-start.md) - Create your first client application
* [ACC Integration](/akinon-ui/ui-protocol/acc-integration.md) - Deploy your application in Akinon Commerce Cloud
* [Shell Application](/akinon-ui/ui-protocol/shell-application.md) - Build a shell application
* [Client Application](/akinon-ui/ui-protocol/client-application.md) - Build a client application


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/akinon-ui/ui-protocol/usage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.