@elevasis/core 0.10.0 → 0.11.1

package/src/organization-model/organization-graph.mdx

@@ -1,272 +1,89 @@
----
-title: Organization Graph
-description: Organization OS Graph layer documentation for the Cytoscape-based organization graph, derived from the organization model and bridged with Command View runtime topology through the shared feature provider.
----
-
-## Overview
-
-Within Organization OS, the organization graph is the dedicated **Graph** layer. It treats the organization model as the top-level ontology and bridges in Command View runtime topology so one graph can support semantic exploration and operations-oriented tracing. Command View is now one lens over this shared graph, not a separate live graph renderer.
-
-Graph contracts live in `@repo/core` alongside the organization model. Rendering lives in `@repo/ui` with Cytoscape.js. The command-center route is a thin wrapper over the shared page.
-
-## Status
-
-First implementation slices are live end-to-end. Command View now delegates to the graph through a command-view lens preset. Layout iteration on the one-panel graph + command surface is ongoing; graph contracts and provider bridge are stable.
-
-Graph types are intentionally **not** part of the published `@elevasis/core` surface yet. Graph adoption remains monorepo-first.
-
-## Source of Truth
-
-- `packages/core/src/organization-model/graph/types.ts` -- node/edge DTO shapes
-- `packages/core/src/organization-model/graph/schema.ts` -- runtime validation
-- `packages/core/src/organization-model/graph/build.ts` -- `buildOrganizationGraph(...)` derivation
-- `packages/core/src/organization-model/__tests__/graph.test.ts` -- derivation and bridge tests
-- `packages/ui/src/features/operations/OrganizationGraphPage.tsx` -- shared Cytoscape page
-- `packages/ui/src/features/operations/CommandViewPage.tsx` -- command-view lens delegating to the graph
-- `packages/ui/src/features/operations/organization-graph/` -- filter helpers, detail-state helpers, path tracing, operational summary
-- `packages/ui/src/features/operations/manifest.ts` -- `organizationGraph.surfaceId = 'operations.organization-graph'`
-- `apps/command-center/src/routes/operations/organization-graph.index.tsx` -- route wrapper
-
-## Product Jobs
-
-The graph helps users:
-
-- orient themselves in the organization model
-- discover how features, capabilities, surfaces, entities, resources, and workflows connect
-- trace upstream/downstream dependencies
-- understand ownership and implementation boundaries
-- assess blast radius before changing a workflow, agent, feature, or integration
-- operate across strategy, operations, and debugging through different lenses on the same graph
-
-The graph does not replace workflow editors, execution-run visualizers, or builder-style authoring canvases. React Flow remains the better fit for editor/execution visuals; Cytoscape fits the exploration-oriented ontology graph.
-
-## Architecture
-
-### Unified graph model
-
-The implementation uses one typed graph, not separate semantic and implementation taxonomies.
-
-- Node kinds: `organization`, `feature`, `surface`, `entity`, `capability`, `resource`
-- Edge kinds: `contains`, `references`, `exposes`, `maps_to`
-- `resource` nodes carry `resourceType` metadata: `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint`
-- `references` edges may also carry `relationshipType`: `triggers`, `uses`, or `approval`
-
-This means runtime topology is represented as bridged `resource` nodes plus relationship metadata on shared edge types, rather than as a second disconnected edge/node vocabulary. `maps_to` is the main crossover edge: the builder emits it from organization-model resource mappings, and the UI presence helpers also treat it as topology-facing when classifying which non-resource nodes participate in runtime-adjacent views.
-
-### Compatibility rules with the organization model
-
-- `OrganizationModelSchema` is the source of truth for semantic structure. The graph does not introduce a second ontology.
-- Graph node IDs and references reuse organization-model IDs wherever those IDs already exist.
-- `surface` nodes derive from `organizationModel.navigation.surfaces`; graph routing respects surface `path` and `defaultSurfaceId`.
-- Feature gating and labels respect `organizationModel.features.enabled` and `.labels`.
-- Implementation-resource bridging prefers `organizationModel.resourceMappings`.
-- Semantic grouping now comes from the unified `organizationModel.features` array. The builder no longer emits separate `domain` nodes.
-- Command View resource `domains` metadata is currently bridged onto `feature` references, not onto a distinct domain-node layer.
-- The 2026-04-20 reality-domain expansion (identity, customers, offerings, roles, goals, statuses, operations, techStack) does not introduce new graph node kinds. Those domains are model-layer data; they are not independently represented as graph nodes. They can be surfaced as metadata on the organization root node when a consumer needs to expose them through a graph lens.
-- Graph defaults remain valid when produced by `resolveOrganizationModel()`.
-- If the graph needs a concept the model cannot express, extend the model first.
-
-### Shared DTO
-
-```ts
-type OrganizationGraphNodeKind =
-  | 'organization'
-  | 'feature'
-  | 'surface'
-  | 'entity'
-  | 'capability'
-  | 'resource'
-
-type OrganizationGraphEdgeKind = 'contains' | 'references' | 'exposes' | 'maps_to'
-
-interface OrganizationGraph {
-  version: 1
-  organizationModelVersion: OrganizationModel['version']
-  nodes: OrganizationGraphNode[]
-  edges: OrganizationGraphEdge[]
-}
-```
-
-`OrganizationGraphNode` also includes optional `sourceId`, `description`, `enabled`, `featureId`, `surfaceType`, and `resourceType`. `OrganizationGraphEdge` includes optional `label` and `relationshipType`.
-
-### Build pipeline
-
-```ts
-interface BuildOrganizationGraphInput {
-  organizationModel: OrganizationModel
-  commandViewData?: CommandViewData
-}
-```
-
-`buildOrganizationGraph` accepts optional topology input so the semantic graph still renders when operational bridging is sparse. The derivation flow is additive and upsert-oriented:
-
-1. Resolve the active organization model.
-2. Derive semantic nodes and edges from features, surfaces, entities, capabilities, and resource mappings.
-3. Upsert bridged runtime resources from Command View data into shared `resource` nodes.
-4. Bridge Command View runtime topology onto the same DTO as `references` edges between `resource` nodes, using `relationshipType` for runtime relationship labels.
-5. Hand the resulting graph to UI-level lensing, filtering, and Cytoscape projection.
-
-Keeping assembly outside the renderer keeps graph semantics testable without UI and prevents Cytoscape concepts from leaking into business logic.
-
-### Ownership split
-
-- `@repo/core` owns normalized node/edge types, schemas, and build/derivation helpers.
-- `@repo/ui` owns Cytoscape element conversion, layout presets, selection state, path tracing, viewport mechanics, detail panels, and presentation helpers.
-- `apps/command-center` owns route wiring and page-level integration.
-
-## Interaction Model
-
-### Lenses
-
-The graph ships with two lens presets in UI code:
-
-- `default` -- title "Organization Graph", initial mode `map`, no preset filters
-- `command-view` -- title "Command View", initial mode `trace`, filters preset to `nodeKinds: ['resource']` and `topologyPresence: 'topology-only'`
-
-Lenses do not change the core DTO. They configure how the shared graph is initially presented.
-
-The command-view preset is intentionally narrow. It starts from topology-focused `resource` nodes so runtime traces stay readable, even though the underlying graph still contains semantic nodes and bridge edges.
-
-### Modes
-
-- **Map mode** -- clustered for broad graph orientation
-- **Trace mode** -- directed layout that privileges path readability
-- **Impact mode** -- centered radial/concentric layout around the current focus
-
-Layouts are deterministic presets, not unconstrained force simulation:
-
-- `map` uses Cytoscape `cose`
-- `trace` uses directed `breadthfirst`
-- `impact` uses degree-based `concentric`
-
-### Interactions
-
-Primary set in the current shared page:
-
-- click node for detail panel
-- click edge for relationship meaning
-- switch mode
-- highlight shortest directed paths between two visible nodes in trace mode
-- filter by node kind, topology presence, and free-text search
-
-Deferred: freeform node placement, collaborative annotations, graph editing/authoring, arbitrary canvas drawing.
-
-### Filtering
-
-The filter state lives in `useOrganizationGraphFilters()` and the toolbar UI in `OrganizationGraphFilterToolbar`.
-
-Filter inputs:
-
-- `search`
-- `nodeKinds`
-- `topologyPresence: 'all' | 'semantic-only' | 'topology-only'`
-
-Presence is derived per node in UI helpers:
-
-- `resource` nodes are `topology-only`
-- non-resource nodes with only semantic edges are `semantic-only`
-- non-resource nodes with `maps_to` edges or runtime relationship edges alongside semantic edges are treated as `bridge` nodes internally
-
-`bridge` is an internal classification used by the filtering helpers. The public filter control only exposes `all`, `semantic-only`, and `topology-only`, so bridge nodes appear when presence is `all`.
-
-Search matches node IDs, labels, descriptions, source IDs, feature IDs, surface/resource types, edge labels, edge kinds, and `relationshipType`.
-
-The page applies `useDeferredValue()` to the active filters so graph search stays responsive while typing.
-
-### Path tracing
-
-The visible Cytoscape surface projects a **filtered** shared graph DTO rather than rendering the full graph unconditionally. Path tracing resolves and highlights directed paths inside the current visible projection, so filtering and tracing stay coherent.
-
-Renderer-agnostic helpers under `packages/ui/src/features/operations/organization-graph/path-tracing/` implement shortest-path logic independent of Cytoscape.
-
-## Provider Integration
-
-The graph is exposed through `ElevasisFeaturesProvider` rather than as app-local glue:
-
-- `FeatureModule.organizationGraph.surfaceId` declares a manifest's bridge point.
-- `operationsManifest` declares `organizationGraph.surfaceId = 'operations.organization-graph'`.
-- The provider resolves that against `organizationModel.navigation.surfaces` and exposes the result as `organizationGraph` in context.
-- Shared UI/operations code stays manifest-driven while remaining aware of semantic organization topology.
-
-This provider bridge resolves the canonical shared graph surface, not a Command View-specific surface. Command View still has its own navigation surface (`operations.command-view`), but the live page delegates into the shared graph renderer.
-
-## Command View Integration
-
-`CommandViewPage` now delegates to `OrganizationGraphPage` through a command-view lens preset. The shared page adds command-view operational context through:
-
-- command-view summary cards rendered in `OrganizationGraphPage`
-- selection-aware resource and human-checkpoint summaries inside the shared graph detail panel
-- follow-up actions for recent executions and pending tasks inside the detail panel
-- dedicated command-view sidebar content alongside the shared graph controls
-
-Operational summary and drill-down derivation is covered by tests under `packages/ui/src/features/operations/organization-graph/__tests__/`.
-
-The detail experience is shared through `OrganizationGraphDetailPanel`, which can render both semantic context and command-view-specific follow-up sections.
-
-Keep the current seam explicit:
-
-- The graph canvas, selection model, path tracing, shared filters, and detail panel all live in `OrganizationGraphPage`.
-- `OperationsSidebarMiddle` still renders `CommandViewSidebarContent` for `/operations/command-view`.
-- That sidebar remains a companion operational panel with some legacy store/filter assumptions and is not the source of truth for the shared graph's filter state.
-- Older React Flow Command View code still exists in the repo, but it is no longer the live renderer for the current Command View route.
-
-## Cytoscape Responsibility Split
-
-Cytoscape owns:
-
-- element rendering
-- compound/group visualization
-- neighborhood traversal and selection state
-- path highlighting
-- collapsed/expanded cluster behavior
-- layout execution
-- viewport mechanics (pan, zoom, fit, focus)
-
-React owns:
-
-- mode switching
-- side panels and inspectors
-- filter toolbar search and trace controls
-- route state and deep-linking
-- server data fetching
-
-## Package Boundary
-
-- `packages/ui/package.json` declares Cytoscape on the published UI surface.
-- `packages/ui/tsup.config.ts` and `packages/ui/rollup.dts.config.mjs` keep Cytoscape **externalized** for publish output.
-- Graph DTO types, schemas, and builders live in monorepo `@repo/core` organization-model modules.
-- Cytoscape rendering, lens presets, filtering helpers, and detail/runtime presentation live in `@repo/ui`.
-- The published `@elevasis/core` wrapper still exposes only the narrow organization-model API; this graph contract should be treated as monorepo-internal for now.
-
-## Theming
-
-The shared Cytoscape page reads CSS custom properties at runtime via `window.getComputedStyle(document.documentElement)`. Nodes, edges, overlays, and glass panels stay aligned with the active UI theme instead of relying on a fixed graph-only palette.
-
-## Cytoscape States
-
-The renderer applies CSS-class-style state markers to highlight context and traces:
-
-- `.is-faded`
-- `.is-context`
-- `.is-selected`
-- `.is-connected`
-- `.is-trace-node`
-- `.is-trace-endpoint`
-- `.is-trace-edge`
-
-These classes drive neighborhood focus, selection emphasis, and trace-path highlighting without changing the underlying DTO.
-
-## Migration Guardrails
-
-- Do not move canonical graph interfaces into `packages/ui`.
-- Do not redefine organization-model semantics in app-local graph config.
-- Do not make the graph contract depend on Cytoscape-specific types.
-- Existing Command View relationships bridge into `relationshipType = triggers | uses | approval` -- do not overload those operational labels with new semantic meaning.
-
-## Verification
-
-- `pnpm --filter @repo/core test -- organization-model graph`
-- `pnpm --filter @repo/ui test -- commandViewDrillDown commandViewOperationalSummary organizationGraphDetail`
-- `pnpm --filter @repo/ui build`
-- `pnpm --filter @repo/ui build:publish`
-- `pnpm --filter command-center build`
+---
+title: Organization Graph
+description: Organization OS graph layer documentation for the organization graph derived from flat Organization Model features and resource metadata links.
+---
+
+## Overview
+
+The organization graph treats the organization model as the top-level ontology and bridges in Command View runtime topology. Command View is a lens over the shared graph, not a separate semantic model.
+
+Graph contracts live in `@repo/core`; rendering lives in `@repo/ui`.
+
+## Source of Truth
+
+- `packages/core/src/organization-model/graph/types.ts`
+- `packages/core/src/organization-model/graph/schema.ts`
+- `packages/core/src/organization-model/graph/build.ts`
+- `packages/core/src/organization-model/graph/link.ts`
+- `packages/core/src/organization-model/__tests__/graph.test.ts`
+- `packages/ui/src/features/operations/OrganizationGraphPage.tsx`
+- `packages/ui/src/features/operations/organization-graph/`
+
+## Model
+
+Node kinds:
+
+- `organization`
+- `feature`
+- `entity`
+- `capability`
+- `resource`
+- `integration`
+
+Edge kinds:
+
+- `contains`
+- `references`
+- `exposes`
+- `maps_to`
+- `operates-on`
+- `uses`
+
+Feature nodes come from the flat `OrganizationModel.features` array. Their graph IDs use `feature:<id>`, such as `feature:sales.crm`.
+
+Resource edges come from resource metadata:
+
+```ts
+links: [
+  { nodeId: 'feature:sales.lead-gen', kind: 'operates-on' },
+  { nodeId: 'integration:instantly', kind: 'uses' }
+]
+```
+
+## Build Pipeline
+
+```ts
+interface BuildOrganizationGraphInput {
+  organizationModel: OrganizationModel
+  commandViewData?: CommandViewData
+}
+```
+
+`buildOrganizationGraph`:
+
+1. Reads flat Organization Model features and derives `feature:*` nodes.
+2. Reads entities, capabilities, integrations, and resources.
+3. Emits authored graph links from resource/entity/capability metadata.
+4. Bridges Command View runtime topology into resource nodes and relationship edges.
+5. Returns a renderer-agnostic DTO.
+
+## Lenses
+
+UI lenses change presentation, not data:
+
+- `default` -- broad map view.
+- `command-view` -- operations-focused trace view.
+
+## Package Boundary
+
+- `@repo/core` owns graph DTOs, schemas, and build helpers.
+- `@repo/ui` owns Cytoscape conversion, filtering, path tracing, panels, and presentation.
+- `apps/command-center` owns route wiring.
+
+## Verification
+
+```bash
+pnpm --filter @repo/core test -- organization-model graph
+pnpm --filter @repo/ui test -- organizationGraph
+pnpm --filter command-center build
+```