---
title: Organization Model
description: Organization OS Model layer documentation for the System hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
---

## Overview

The organization model is the semantic contract that maps an organization's System hierarchy, business semantics, shell navigation, resource governance, action/entity vocabulary, and graph binding. It is schema-first, versioned, and validated.

The model is authored in `@repo/core` and published through the curated `@elevasis/core/organization-model` surface.

## Source of Truth

- `packages/core/src/organization-model/schema.ts`
- `packages/core/src/organization-model/types.ts`
- `packages/core/src/organization-model/defaults.ts`
- `packages/core/src/organization-model/helpers.ts`
- `packages/core/src/organization-model/graph/link.ts`
- `packages/core/src/organization-model/published.ts`
- `packages/core/src/__tests__/template-core-compatibility.test.ts`

## Contract Shape

Top-level fields on `OrganizationModel`:

- `version`
- `domainMetadata`
- `branding`
- `navigation`
- `identity`
- `customers`
- `offerings`
- `roles`
- `goals`
- `systems`
- `resources`
- `actions`
- `entities`
- `policies`
- `knowledge`

The pure collection domains are id-keyed maps: `systems`, `roles`, `goals`, `customers`, `offerings`, `resources`, `actions`, `entities`, `policies`, and `knowledge`. The map key must match the entry `id`. Entries carry `order` for deterministic ordered views; use `listDomain(record)` when order matters.

Resource identity is authored inside `OrganizationModel.resources`. Runtime workflows, agents, integrations, and scripts import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.

## System Shape

`OrganizationModel.systems` is the canonical semantic domain map. Hierarchy is authored with recursive `subsystems`; dotted paths such as `sales.crm` are derived from position in that tree. `parentSystemId` and `id` remain accepted compatibility fields during the migration.

```ts
systems: {
  dashboard: { id: 'dashboard', order: 10, label: 'Dashboard', lifecycle: 'active' },
  sales: { id: 'sales', order: 20, label: 'Sales', lifecycle: 'active' },
  clients: { id: 'clients', order: 30, label: 'Clients', lifecycle: 'active' },
  projects: { id: 'projects', order: 40, label: 'Projects', lifecycle: 'active' }
}
```

Authored fields:

- `id`
- `label`
- `description`
- `kind`
- `parentSystemId`
- `ui`
- `lifecycle`
- `requiresAdmin`
- `actions`
- `policies`
- `content`
- `subsystems`
- `order`

Systems describe ownership, hierarchy, lifecycle, access, and governance. Sidebar presentation lives in `navigation.sidebar`, not on System entries. UI-backed Systems may still provide `ui.path` for route matching during the migration, but `ui.surfaces` is not an authored contract. `lifecycle` replaces the old feature enabled/dev-only split.

## Navigation Shape

`OrganizationModel.navigation.sidebar` is the authored shell tree. It has `primary` and `bottom` sections whose records contain recursive group nodes and routeable surface nodes:

```ts
navigation: {
  sidebar: {
    primary: {
      dashboard: {
        type: 'surface',
        order: 10,
        label: 'Dashboard',
        path: '/',
        surfaceType: 'dashboard',
        targets: { systems: ['dashboard'] }
      },
      business: {
        type: 'group',
        order: 20,
        label: 'Business',
        children: {
          sales: {
            type: 'surface',
            order: 10,
            label: 'Sales',
            path: '/sales',
            surfaceType: 'page',
            targets: { systems: ['sales'] }
          },
          clients: {
            type: 'surface',
            order: 20,
            label: 'Clients',
            path: '/clients',
            surfaceType: 'list',
            targets: { systems: ['clients'] }
          }
        }
      }
    },
    bottom: {}
  }
}
```

Dashboard is ordered before Business in the primary sidebar. Business is a navigation group only; it is not a System and it is not a URL namespace. Routeable leaves are projected into flat surface DTOs by `projectOrganizationSurfaces(model)`.

## Graph IDs and Resource Descriptors

Cross-collection links use kind-prefixed graph IDs:

- `system:sales.crm`
- `integration:instantly`
- `resource:lead-import`
- `action:operations.queue.review`

Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources` and derives runtime `resourceId` / `type` while attaching executable behavior.

```ts
import { defineResources } from '@elevasis/core/organization-model'

export const resourceDescriptors = defineResources({
  leadImport: {
    id: 'lgn-01c-apollo-import-workflow',
    title: 'Apollo Import',
    description: 'Imports Apollo company records into the lead generation pipeline.',
    kind: 'workflow',
    systemPath: 'sales.lead-gen',
    ownerRoleId: 'role-ops-lead',
    status: 'active',
    ontology: {
      actions: ['sales.lead-gen:action/company.apollo-import'],
      primaryAction: 'sales.lead-gen:action/company.apollo-import'
    },
    codeRefs: [
      {
        path: 'packages/elevasis-operations/src/sales/prospecting/scrape/apollo-import.ts',
        role: 'entrypoint',
        symbol: 'lgnApolloImportWorkflow'
      }
    ]
  }
})

export const resourceGovernanceModel = {
  systems,
  resources: resourceDescriptors
} as const
```

Legacy `sys.*` paths may still appear in older examples and external compatibility mirrors.
For new Organization OS examples, prefer the current semantic System path.

## Domain Semantics

The model keeps business semantics in named domains:

- `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
- `systems` -- bounded contexts that group governed operational resources and system-local content
- `actions` -- stable business verbs exposed or consumed by systems
- `entities` -- durable business nouns and their semantic links
- `resources` -- governance-only workflow, agent, integration, and script descriptors
- `policies` -- operational governance rules over systems, actions, resources, and roles
- `knowledge` -- playbooks, strategies, references, and graph-governing links

System-local operational catalogs live under `System.ontology.catalogTypes`, including pipeline, stage, template, template-step, status-flow, and status records. System-local settings live in `System.config`. The legacy compound and status domains should not be used for new authoring.

## Authoring and Resolution

- `defineOrganizationModel()` is a typed authoring helper.
- `resolveOrganizationModel(partial)` deep-merges a partial override into `DEFAULT_ORGANIZATION_MODEL` and validates the result.
- `createFoundationOrganizationModel(partial)` resolves the canonical model and returns template-facing helpers.
- Plain objects merge recursively.
- Id-keyed domain maps merge additively by key.
- Arrays replace defaults.

## Referential Integrity

`OrganizationModelSchema` validates:

- unique System IDs
- ancestor existence for dotted System IDs and `parentSystemId`
- UI path rules for Systems with UI presence
- valid sidebar positions
- reality-domain cross references such as offering target segments and role reporting lines
- system, resource, role, knowledge, and goal cross references used by resource governance

`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.

## Provider Integration

`ElevasisSystemsProvider` uses the organization model to:

1. validate each manifest's `systemId`
2. resolve effective system access
3. derive sidebar entries from `navigation.sidebar`
4. expose shell helpers such as `childrenOf`, `ancestorsOf`, and `findByPath`
5. bridge the operations graph into shared UI

## Published Package

`@elevasis/core` exposes a curated browser-safe surface:

- root barrel
- `./organization-model`

The organization graph builder remains monorepo-internal until there is a concrete external contract need.

## Verification

```bash
pnpm --filter @repo/core test -- organization-model
pnpm --filter @repo/core build:publish
pnpm -C external/_template/core test
```
