TenantAtlas/specs/042-inventory-dependencies-graph/spec.md

Feature Specification: Inventory Dependencies Graph

Feature Branch: feat/042-inventory-dependencies-graph
Created: 2026-01-07
Status: Draft

Purpose

Represent and surface dependency relationships between inventory items and foundational Intune objects so admins can understand blast radius and prerequisites.

MVP shows direct inbound/outbound edges only; depth > 1 traversal is out of scope for this iteration.

Clarifications

Session 2026-01-10

• Q: Should FR3 be paginated or limit-only for MVP? → A: Limit-only (no pagination).
• Q: Where should unknown/unsupported reference warnings be persisted? → A: On the inventory sync run record (e.g., InventorySyncRun.error_context.warnings[]).
• Q: For unknown assignment target shapes, should we create a missing edge or warning-only? → A: Warning-only (no edge created).
• Q: Should foundation_object edges always store metadata.foundation_type? → A: Yes (required).
• Q: Should the UI show 50 edges total or 50 per direction? → A: 50 per direction (up to 100 total when showing both directions).

Session 2026-01-10 (042.2)

• Q: Should the Dependencies UI do Entra/Graph lookups to resolve names (e.g., Groups)? → A: No. UI resolution is DB-only.
• Q: How should the UI avoid "Unknown" targets long-term? → A: Render a stable, typed DTO per edge target via a resolver layer (batch queries, no N+1). Definitions:
• Blast radius: All resources directly affected by a change to a given item (outbound edges only; no transitive traversal in MVP).
• Prerequisite: A hard dependency required for an item to function; missing prerequisites are explicitly surfaced.
• Inbound edge: A relationship pointing TO this item (e.g., "Policy A is assigned to Group X" → Group X has inbound edge from Policy A).
• Outbound edge: A relationship pointing FROM this item (e.g., "Policy A is scoped by ScopeTag Y" → Policy A has outbound edge to ScopeTag Y).

User Scenarios & Testing

Scenario 1: View dependencies for an item

• Given an inventory item
• When the user opens its dependencies view
• Then they can see inbound and outbound relationships (e.g., “uses”, “assigned to”, “scoped by”)

Scenario 2: Identify missing prerequisites

• Given an item references a prerequisite object not present in inventory
• When the user views dependencies
• Then missing prerequisites are clearly indicated (red badge, "Missing" label, tooltip with last-known displayName if available)

Scenario 3: Zero dependencies

• Given an item has no inbound or outbound edges
• When the user opens dependencies view
• Then a "No dependencies found" message is shown

Scenario 4: Filter dependencies by relationship type

• Given multiple relationship types exist
• When the user filters by relationship type (single-select dropdown, default: "All")
• Then only matching edges are shown (empty selection = all edges visible)

Scenario 6 (042.2): Resolve target names when available

• Given dependency edges to foundation objects (scope tags, assignment filters, groups)
• When the user views dependencies
• Then each edge target is labelled deterministically (no "Unknown")
• And names are resolved only when the target exists in the local DB (no UI Graph lookups)
• And external references (AAD groups) are rendered as external refs without links

Scenario 5: Only missing prerequisites

• Given an item where all referenced targets are unresolved (no matching inventory or foundation objects)
• When the user opens the dependencies view and selects "Outbound" or "All"
• Then all shown edges are annotated as "Missing" with a red badge and tooltip; filtering still works and zero resolvable targets do not error

Functional Requirements

• FR1: Relationship taxonomy
  Define a normalized set of relationship types covering inventory→inventory and inventory→foundation edges.
  Supported types (MVP):

  • assigned_to (Policy → AAD Group) (legacy/general)
  • assigned_to_include (Policy → AAD Group; include assignment)
  • assigned_to_exclude (Policy → AAD Group; exclude assignment)
  • uses_assignment_filter (Policy → Assignment Filter; metadata filter_mode=include|exclude)
  • scoped_by (Policy → Scope Tag)
  • targets (Update Policy → Device Category, conditional logic)
  • depends_on (Generic prerequisite, e.g., Compliance Policy referenced by Conditional Access)

  Each type has:

  • name (string, e.g., "assigned_to")
  • display_label (string, e.g., "Assigned to")
  • directionality (enum: outbound, inbound, bidirectional)
  • description (brief explanation)

• FR2: Dependency edge storage
  Store edges in an inventory_links table with fields:

• id (PK)

• tenant_id (FK, indexed)

• source_type (string: inventory_item, foundation_object)

• source_id (UUID or stable ref)

• target_type (string: inventory_item, foundation_object, missing)

• target_id (UUID or stable ref, nullable if missing)

• relationship_type (FK to taxonomy or enum)

• metadata (JSONB, optional: last_known_name, raw_ref, etc.; for target_type='foundation_object', metadata.foundation_type is required)

• created_at, updated_at

In-scope foundation object types (MVP):

• AAD Groups (aad_group)
• Scope Tags (scope_tag)
• Device Categories (device_category)
• Assignment Filters (assignment_filter)

Out-of-scope foundation types (for this iteration): Conditional Access Policies, Compliance Policies as foundation nodes (only as inventory items).

• FR3: Query inbound/outbound edges
  Provide service methods:

  • getOutboundEdges(item_id, relationship_type?, limit=50) → returns edges where item is source
  • getInboundEdges(item_id, relationship_type?, limit=50) → returns edges where item is target

  Both return up to limit edges, ordered by created_at DESC.

  UI supports filtering by relationship_type via a single-select dropdown (default: "All"; empty selection behaves as "All").

• FR4: Missing prerequisites
  When a target reference cannot be resolved:

  • Create edge with target_type='missing', target_id=null
  • Store metadata.last_known_name and metadata.raw_ref if available
  • UI displays "Missing" badge + tooltip

  No separate "deleted" or "archived" state in core inventory; missing is purely an edge property.

  Unknown/unsupported reference shapes do not create edges; they are handled via warnings (see NFR2).

• FR5: Tenant scoping and access control

  • All edges filtered by tenant_id matching Tenant::current()
  • Read access: any authenticated tenant user
  • No cross-tenant queries allowed (enforced at query builder level)

Non-Functional Requirements

• NFR1: Idempotency
  Dependency extraction must be idempotent:

  • Unique key: (tenant_id, source_type, source_id, target_type, target_id, relationship_type)
  • On re-run: upsert (update updated_at, replace metadata if changed)
  • Orphan edges (source/target no longer in inventory) are NOT auto-deleted; cleanup is manual or scheduled separately

• NFR2: Graceful unknown-reference handling
  If an unknown/unsupported reference shape is encountered:

  • Log warning with severity info (not error)
  • Do NOT create an edge for unsupported types (including unknown assignment target shapes)
  • Record warning in sync run metadata at InventorySyncRun.error_context.warnings[] with shape: {type: 'unsupported_reference', policy_id, raw_ref, reason}
  • Sync run continues without failure

Graph Traversal & Cycles (Out of Scope for MVP)

• Depth > 1 traversal (transitive “blast radius”) is out of scope for this iteration.
• The UI shows only direct inbound/outbound edges.
• Future work may add depth-capped traversal with cycle handling and explicit cycle visualization.

Success Criteria

• SC1: Blast radius determination
  Admins can determine prerequisites (inbound edges) and blast radius (outbound edges; direct only) for any item in under 2 minutes:

  • Measured from: clicking "View Dependencies" on an item detail page
  • To: able to answer "What would break if I delete this?" and "What does this depend on?"
  • Acceptance: <2s page load, ≤50 edges per direction shown initially (≤100 total when showing both directions), clear visual grouping by relationship type

• SC2: Deterministic output
  For supported relationship types, dependency edges are consistent across re-runs:

  • Given identical inventory state (same items, same Graph API responses)
  • Edge set equality: same (source, target, relationship_type) tuples (order-independent)
  • Acceptance: automated test re-runs extraction twice on fixed test data; assert edge sets match (ignoring updated_at)

Security & Privacy

• All data is tenant-scoped; no cross-tenant queries or joins.
• Foundation object visibility:
  • Display name shown only if available from tenant-authorized sources (inventory metadata or prior sync payloads).
  • If not available, show a masked or abbreviated identifier (e.g., first 6 characters of ID) with no external lookup.
• Stored metadata for edges must avoid PII beyond display names surfaced by Graph within the tenant; raw references may be stored but not enriched from outside the tenant scope.

Traceability

• FR1 (taxonomy) → SC2 (deterministic types), tests: unit taxonomy load/assert
• FR2 (storage) → SC2 (edge equality), tests: feature upsert and equality
• FR3 (queries) → SC1 (answer in <2 min), tests: service returns inbound/outbound within limits
• FR4 (missing) → SC1 (clear prerequisite view), tests: feature missing badge/tooltip
• FR5 (tenant scope) → SC1/SC2 (correct data, deterministic set), tests: tenant isolation

Out of Scope

• Automatic remediation.
• Cross-tenant dependency graphs.

Related Specs

• Program: specs/039-inventory-program/spec.md
• Core: specs/040-inventory-core/spec.md