npm package: @ortha/admin-platform-core
Description: Root shell of the admin application — provides the `CorePlugin`, `CoreApp` component, Zustand stores for auth and user state, an Axios-based HTTP client with token refresh, permission utilities, and the UI slot rendering infrastructure.
Latest version: 0.0.4

# @ortha/admin-platform-core

Root shell of the admin application — provides the `CorePlugin`, `CoreApp` component, Zustand stores for auth and user state, an Axios-based HTTP client with token refresh, permission utilities, and the UI slot rendering infrastructure.

## Installation

Internal monorepo dependency — import directly:

```ts
import { CoreApp, useAuthStore, httpClient } from '@ortha/admin-platform-core';
```

## Usage

### HTTP client

```ts
import { httpClient } from '@ortha/admin-platform-core';

// GET request — Bearer token is injected automatically
const users = await httpClient.get('/api/users');

// POST request
await httpClient.post('/api/projects', { name: 'New Project' });
```

### Auth store (Zustand)

```ts
import { useAuthStore } from '@ortha/admin-platform-core';

const Component = () => {
    const { accessToken, login, logout } = useAuthStore();

    // login() stores tokens, logout() clears them
};
```

### Permission checks

```ts
import { PermissionGuard, useHasPermission } from '@ortha/admin-platform-core';

// Hook-based check
const canEdit = useHasPermission(['update:admin:user']);

// Component guard
<PermissionGuard permissions={['create:admin:project']}>
    <CreateButton />
</PermissionGuard>
```

### Rendering slot fills

```ts
import { SlotRenderer, SLOT_TOPBAR_NAV_MAIN_ACTIONS } from '@ortha/admin-platform-core';

// Renders all components registered for this slot, sorted by order
<SlotRenderer slotKey={SLOT_TOPBAR_NAV_MAIN_ACTIONS} />
```

## API Reference

### Components

| Export            | Kind      | Description                                                |
| ----------------- | --------- | ---------------------------------------------------------- |
| `CoreApp`         | component | Root React component — `BrowserRouter`, routes, layout     |
| `ProtectedRoute`  | component | Route guard — redirects unauthenticated users              |
| `SlotRenderer`    | component | Renders all fills for a named slot key                     |
| `PermissionGuard` | component | Renders children only when user holds required permissions |

### Stores

| Export           | Kind  | Description                                       |
| ---------------- | ----- | ------------------------------------------------- |
| `useAuthStore()` | store | Zustand — JWT tokens, login/logout, token refresh |
| `useUserStore()` | store | Zustand — current user data, roles, permissions   |

### Hooks

| Export               | Kind | Description                                          |
| -------------------- | ---- | ---------------------------------------------------- |
| `useRouterService()` | hook | Access routes — throws if used outside provider      |
| `useSlotService()`   | hook | Access slots — throws if used outside provider       |
| `useHasPermission()` | hook | Returns `true` when user holds all given permissions |

### Contexts

| Export                 | Kind    | Description                             |
| ---------------------- | ------- | --------------------------------------- |
| `RouterServiceContext` | context | React context providing `RouterService` |
| `SlotServiceContext`   | context | React context providing `SlotService`   |

### Utilities

| Export                         | Kind     | Description                                          |
| ------------------------------ | -------- | ---------------------------------------------------- |
| `httpClient`                   | util     | Custom Axios HTTP client with auth interceptors      |
| `axiosInstance`                | util     | Raw Axios instance (prefer `httpClient`)             |
| `hasPermission()`              | util     | Pure function — checks owned vs required permissions |
| `SLOT_TOPBAR_NAV_MAIN_ACTIONS` | constant | Slot key for top navigation bar actions              |

## Internal Structure

```
src/lib/
├── corePlugin/index.ts             # CorePlugin definition
├── components/
│   ├── CoreApp/index.tsx           # Root app shell with routing
│   ├── PermissionGuard/index.tsx   # Permission-based visibility guard
│   ├── ProtectedRoute/index.tsx    # Auth route guard
│   └── SlotRenderer/index.tsx      # Generic slot renderer
├── contexts/
│   ├── index.ts                    # Barrel
│   ├── RouterServiceContext/index.ts
│   └── SlotServiceContext/index.ts
├── hooks/
│   ├── index.ts                    # Barrel
│   └── useHasPermission/index.ts   # Permission check hook
├── stores/
│   ├── authStore/index.ts          # Zustand + persist (localStorage)
│   └── userStore/index.ts          # Zustand user state
├── utils/
│   ├── index.ts                    # Barrel
│   └── hasPermission/index.ts      # Pure permission matching logic
├── httpClient/index.ts             # Axios instance + interceptors
└── slots/index.ts                  # Slot key constants
```

## Key Patterns

- **httpClient interceptors**: request interceptor injects Bearer token from `useAuthStore`; response interceptor handles 401 with a token refresh queue (prevents concurrent refresh calls).
- **Auth store** uses `zustand/persist` with `localStorage` for token persistence across page reloads.
- **Context hooks** throw descriptive errors if used outside their providers.
- **CorePlugin** is auto-prepended by bootstrap — never include it manually in the plugins array.
- **Lazy loading**: route components should use `lazy(() => import(...))` with `<Suspense>`.

## Dependencies

- `@ortha/admin-platform-plugin-registry` — plugin types and services
- `@ortha/design-system` — theme provider and components

## Building

```bash
nx build admin-platform-core
```