# Introduction

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

It manages the integration of micro-frontend applications, handling data sharing, user actions, navigation, and communication.

### <mark style="color:red;">What is a Shell Application?</mark>

A shell application is the host that embeds and manages micro-frontend clients. Examples include Omnitron and Seller Center. The shell provides:

* **Layout and Navigation** - Header, sidebar, and routing
* **Shared Data** - User info, permissions, configuration
* **Actions** - Functions that clients can invoke
* **Communication Channel** - Message passing via postMessage API

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

#### Data Management

* Share data with all connected micro-frontends
* Synchronize state changes across applications
* Maintain data isolation between different clients

#### User Actions

* Define actions that clients can invoke (e.g., show toast, open modal)
* Process action requests and return results
* Handle built-in actions (navigation, UI helpers)

#### Navigation

* Manage routing for fullpage applications
* Handle navigation requests from clients
* Coordinate URL and query parameter changes

#### Application Lifecycle

* Register and configure micro-frontend applications
* Load/unload clients via iframes
* Manage communication channels per client

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

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

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

Wrap your application with `AppShellProvider`:

```tsx
import { AppShellProvider } from '@akinon/app-shell';

const App = () => {
  return (
    <AppShellProvider
      apps={registeredApps}
      navigation={navigationConfig}
      data={sharedData}
      actions={shellActions}
    >
      {/* Your shell application */}
    </AppShellProvider>
  );
};
```

#### Provider Props

| Prop         | Type                 | Required | Description                                    |
| ------------ | -------------------- | -------- | ---------------------------------------------- |
| `apps`       | `RegisteredApp[]`    | Yes      | List of registered micro-frontend applications |
| `navigation` | `ShellNavigation`    | Yes      | Navigation helper functions                    |
| `data`       | `ApplicationData`    | No       | Shared data available to all clients           |
| `actions`    | `ApplicationActions` | No       | Custom actions that clients can invoke         |

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

The `apps` prop contains the list of micro-frontend applications that can be rendered:

```tsx
import type { RegisteredApp } from '@akinon/app-shell';

const registeredApps: RegisteredApp[] = [
  {
    pk: 1,
    name: 'Marketplace Dashboard',
    config: {
      web_url: 'https://marketplace.example.com',
      visible_type: 'full_page'
    },
    is_visible: true,
    is_active: true
  },
  {
    pk: 2,
    name: 'Analytics Widget',
    config: {
      web_url: 'https://analytics.example.com',
      visible_type: 'plugin',
      placeholder: 'dashboard-sidebar'
    },
    is_visible: true,
    is_active: true
  }
];
```

### <mark style="color:red;">How It Works</mark>

1. **Shell initializes** with `AppShellProvider` and registered apps
2. **Client iframe loads** and sends `SET_CONFIG` event
3. **Shell responds** with `SET_DATA` and `SET_APP_ID`
4. **Communication established** via [framebus](https://github.com/braintree/framebus) library
5. **Ongoing communication** for actions, navigation, and data updates

```
┌─────────────────────────────────────────┐
│            AppShellProvider             │
│  ┌───────────────────────────────────┐  │
│  │          Shell Content            │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │   AppRenderer (fullpage)    │  │  │
│  │  │   or PluginRenderer         │  │  │
│  │  │   ┌─────────────────────┐   │  │  │
│  │  │   │   Client iframe     │   │  │  │
│  │  │   │   (micro-frontend)  │   │  │  │
│  │  │   └─────────────────────┘   │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

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

* [Configuration](/akinon-ui/ui-protocol/shell-application/configuration.md) - Configure data sharing, actions, and navigation
* [Hooks](/akinon-ui/ui-protocol/shell-application/useappshell.md) - Shell-side React hooks
* [Components](/akinon-ui/ui-protocol/shell-application/components.md) - AppRenderer, PluginRenderer, ModalRenderer
* [API Reference](/akinon-ui/ui-protocol/shell-application/api-reference.md) - Complete API documentation


---

# 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/shell-application/introduction.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.