Dependencies

ProBeya's Dependencies module lets teams map relationships between items on a project board -- who blocks whom, what is related to what, and which chain of items forms the critical path through the project. The system uses DFS-based cycle detection to prevent circular blocking chains and provides critical path analysis for schedule-driven planning.

Dependencies are essential for any team managing work items with sequencing constraints: you cannot start testing until development is done, you cannot ship until testing passes, and delays on the longest chain delay the entire project.

Overview

When teams manage complex projects with dozens or hundreds of work items, understanding sequencing is critical. Without explicit dependency tracking, teams discover blocking relationships only when someone is already stuck waiting. Without critical path analysis, project managers cannot identify which delays actually threaten the deadline versus which have float.

ProBeya's dependency system addresses both needs:

1. Dependency mapping -- Create directed relationships between items (blocks, is_blocked_by, related_to).
2. Cycle prevention -- DFS-based cycle detection rejects any new dependency that would create a circular blocking chain.
3. Critical path -- Compute the longest path through the dependency DAG to identify schedule-critical items.

Getting Started

1. Navigate to a project and select Dependencies from the sidebar.
2. The page renders a DAG (Directed Acyclic Graph) visualization of all item dependencies.
3. To add a dependency, select a source item and a target item, then choose the relationship type.
4. The system validates the dependency (ownership, self-reference, cycle detection) before creating it.
5. Use the Critical Path view to highlight the longest dependency chain that determines the project's minimum duration.

Key Concepts

Term	Definition
Dependency	A directed relationship between two items indicating a sequencing or informational constraint.
Source Item	The "from" side of the dependency (the item that blocks or is related to the target).
Target Item	The "to" side of the dependency (the item that is blocked by or related to the source).
Blocks	Source item blocks target item. Target cannot proceed until source is complete.
Is Blocked By	Source item is blocked by target item. Semantically the reverse of "blocks" -- target blocks source.
Related To	An informational relationship with no blocking semantics. Used to link related but independent items.
DAG	Directed Acyclic Graph. The dependency graph must remain acyclic for blocking relationships to be logically consistent.
Critical Path	The longest chain of blocking dependencies through the project. Any delay on the critical path delays the project end date.
Cycle	A circular dependency chain (A blocks B, B blocks C, C blocks A). Cycles make the schedule unsolvable and are prevented by the system.

How It Works

Dependency Types

ProBeya supports three dependency types, each with different behavioral implications:

Type	Direction	Blocking?	Cycle Detection?
blocks	Source → Target	Yes. Target waits for source.	Yes
is_blocked_by	Source ← Target	Yes. Source waits for target.	Yes
related_to	Bidirectional	No. Informational only.	No

The blocks and is_blocked_by types are semantically equivalent with reversed perspectives. For cycle detection, is_blocked_by edges are internally normalized to the blocks direction (if A is_blocked_by B, then B blocks A).

Cycle Detection

Before creating any blocking dependency, the system runs DFS-based cycle detection:

1. Load all existing blocking edges for the organization
2. Normalize is_blocked_by edges to the blocks direction
3. Determine the effective blocking direction of the proposed new edge
4. Run a depth-first search from the target to see if it can reach the source through existing edges
5. If a path exists, the new edge would create a cycle and is rejected with a clear error message

The detectCycle function from the dependency-graph library performs this check. The algorithm is run against the full set of organization-scoped blocking edges to catch cross-board cycles within the same organization.

Critical Path Analysis

The getCriticalPath endpoint computes the longest path through the blocking dependency DAG using the getCriticalPath function from the graph library. The result identifies:

• The sequence of items forming the critical path
• Each item's position in the chain
• The total critical path length

Items on the critical path are highlighted in the DAG visualization, making it immediately clear which work streams have zero float and which have scheduling flexibility.

Validation Rules

The dependency creation process enforces several business rules:

Rule	Enforcement
No self-dependencies	An item cannot depend on itself. Caught before any database queries.
Cross-tenant isolation	Both source and target items must belong to the caller's organization. Verified in parallel for efficiency.
No duplicate dependencies	A unique constraint on (sourceItemId, targetItemId) prevents duplicates. Duplicate attempts return a user-friendly CONFLICT error.
No cycles	DFS cycle detection for blocking types. Related-to type skips this check since it has no blocking semantics.

DAG Visualization

The Dependencies page renders an interactive DAG view built on the DependenciesPageClient component. The visualization:

• Displays items as nodes with dependency arrows between them
• Color-codes critical path items
• Supports pan and zoom for large graphs
• Allows creating and removing dependencies directly from the graph

Configuration

Dependencies do not require separate configuration. They operate within the existing project and board structure:

Setting	Description
Board/Project	Dependencies are created between items on a board. The page resolves the board from the project slug.
Dependency Types	Three types are available: blocks, is_blocked_by, related_to. No configuration needed.
Unique Constraint	Enforced at the database level. A pair of items can have at most one dependency.

Permissions

Role	Capabilities
Board Viewer	View the dependency DAG and critical path
Board Member	Create and delete dependencies between items they can access
Board Admin	Full dependency management across all board items
Organization Admin	Full access across all boards

Dependency deletion verifies that the dependency involves items belonging to the caller's organization. The error message is intentionally vague ("Item not found") to avoid leaking information about items in other tenants.

Tips & Best Practices

Use "related_to" for informational links

Not every relationship is a blocking dependency. Use "related_to" for items that are conceptually connected but can proceed independently. This keeps the DAG clean and the critical path accurate.

Review the critical path weekly

The critical path changes as items are completed or re-estimated. Regular review ensures the team is focused on the work that actually determines the project end date.

Break long dependency chains

If the critical path passes through 15+ sequential items, look for opportunities to parallelize. Long chains amplify delay risk because a slip on any single item delays everything downstream.

Clean up resolved dependencies

When a blocking item is completed, the dependency still exists in the graph. While it does not affect ongoing work, removing completed dependencies keeps the DAG readable.

Troubleshooting

Issue	Resolution
"Circular blocking chain" error	The proposed dependency would create a cycle. Trace the existing chain to understand the conflict and choose an alternative structure.
"A dependency already exists" error	The unique constraint prevents duplicate edges. Remove the existing dependency first if you need to change the type.
"Item not found" error	One or both items do not exist or belong to a different organization. Verify item IDs and organization membership.
Critical path not showing	The critical path requires at least two items connected by blocking dependencies. Related-to dependencies are excluded from critical path computation.
DAG visualization not rendering	Verify the project has a board with items. The page resolves the board from the project and returns a 404 if either is missing.

Related Features

• KPI Boards -- Board items are the primary entities that dependencies link together.
• Action Log -- Actions may have dependencies when one corrective action must complete before another can start.
• Estimates -- Three-point estimates on dependent items feed into schedule risk analysis via Monte Carlo simulation.
• Gantt / Timeline -- The timeline view uses dependency data to draw relationship arrows and identify scheduling conflicts.
• OKR Management -- Project dependencies may impact the timeline for achieving key results linked to portfolio OKRs.