---
title: System Shell & Provider Runtime
description: Current system shell contract for Organization Model systems, manifests, route matching, sidebars, and breadcrumbs.
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


## Overview

The system shell derives app navigation from `OrganizationModel.systems`. System manifests provide implementation hooks such as icons and sidebars; they do not own structural navigation.

## Source Of Truth

- `packages/core/src/organization-model/defaults.ts` -- default system list
- `packages/core/src/organization-model/helpers.ts` -- `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`
- `packages/ui/src/features/registry/types.ts` -- `SystemModule`
- `packages/ui/src/provider/ElevasisSystemsProvider.tsx` -- runtime resolver
- `packages/ui/src/components/navigation/useBreadcrumbs.ts` -- breadcrumb derivation

## SystemModule

```ts
export interface SystemModule {
  key: string
  systemId: string
  capabilityIds?: string[]
  icon?: SystemIconComponent
  sidebar?: SystemSidebarComponent
  organizationGraph?: { systemId: string }
}
```

`systemId` must match an Organization Model system ID. Structural fields such as route lists, nav labels, and nested links belong on `OrganizationModel.systems`.

## Shell Model

`useElevasisSystems()` exposes `shellModel`:

```ts
{
  systems,
  findByPath,
  findById,
  childrenOf,
  ancestorsOf,
  parentOf,
  topLevel,
  uiPositionFor,
  requiresAdminFor,
  devOnlyFor
}
```

Sidebar rendering walks `topLevel()` and `childrenOf(id)`. Breadcrumbs resolve `findByPath(location.pathname)` and then map `ancestorsOf(id)`.

## Access

System access is keyed by Organization Model system ID. `requiresAdmin` and `devOnly` inherit from ancestor system nodes and are applied when deriving visible sidebar entries.

Routes still need guards:

```tsx
<ProtectedRoute>
  <AccessGuard accessKey="sales.crm">
    <Outlet />
  </AccessGuard>
</ProtectedRoute>
```

Use `AccessKeys.platformAdmin` with `AccessGuard` for pages that require platform-admin privileges.

## External Shells

Host apps pass `SYSTEM_MANIFESTS` or their own `SystemModule[]` into `ElevasisSystemsProvider` and derive sidebar links locally from `shellModel`. There is no separate nav config file to keep in sync.
