Scope Linking

Scope linking allows you to create parent-child relationships between scopes, enabling child scopes to inherit dimensions, materials, and other properties from a parent scope. This dramatically reduces data entry for repeated work areas with similar characteristics.

info

Scope linking is single-level only — a parent scope cannot have its own parent. This keeps the hierarchy simple and predictable.

Use Cases

🗂️

Repeated Elements

Multiple foundation pads with the same dimensions but different locations

📏

Standardized Work

Driveway sections that all use the same mix design and rebar specs

📚

Phased Construction

Parking lot bays with identical dimensions but built in separate phases

🧱

Material Consistency

Ensure child scopes use the same concrete mix, rebar, and formwork as parent

How Scope Linking Works

Parent-Child Relationship

🔍 Click diagram to expand

Inheritance Rules

Property	Inherited	Overridable
Length	✅ Yes	✅ Yes
Width	✅ Yes	✅ Yes
Height/Depth	✅ Yes	✅ Yes
Diameter	✅ Yes	✅ Yes
Cubic Yards	✅ Yes (auto-calculated)	❌ No (derived)
Rebar Waste Override	✅ Yes	✅ Yes
Shape	❌ No	❌ No
Name	❌ No	❌ No

note

Shape and name are NOT inherited — each scope must have its own identity. Only dimensional and material properties are inherited.

Creating Linked Scopes

Create Parent Scope

Create a "template" parent scope with standard dimensions:

Navigate to bid detail page
Click "Add Scope"
Enter scope name (e.g., "Foundation Pad Template")
Select shape (Slab, Cylinder, etc.)
Enter dimensions:
- Length: 20 ft
- Width: 20 ft
- Depth: 1.5 ft
Click "Save"

Create Child Scope

Create a child scope that will inherit from the parent:

Click "Add Scope" again
Enter scope name (e.g., "Pad A - North Corner")
Select shape (should match parent for consistency)
Leave dimensions empty for now (will inherit)
Click "Save"

Link Child to Parent

Link the child scope to the parent:

Open the child scope (Pad A)
Click the "Link to Parent" button
Select parent scope from dropdown: "Foundation Pad Template"
Configure inheritance settings:
- ✅ Inherit dimensions
- ✅ Inherit rebar waste override
Click "Link"

Verify Inheritance

Check that child scope now has parent's dimensions:

Child scope shows: Length 20 ft, Width 20 ft, Depth 1.5 ft
Cubic yards auto-calculated: 1.11 CY
Badge shows: "Linked to: Foundation Pad Template"

Overriding Inherited Properties

Child scopes can override any inherited property:

Override Dimensions
Override Rebar Waste
Revert to Parent

Scenario: Pad B is larger than the template.

Steps:

Open child scope (Pad B)
Click "Edit"
Change dimensions:
- Length: 25 ft (override)
- Width: 25 ft (override)
- Depth: 1.5 ft (inherited)
Click "Save"

Result:

Pad B now has custom dimensions
Still linked to parent (can revert later)
Other properties still inherited

warning

Overriding a property breaks inheritance for that property only. To re-inherit, clear the field (set to blank/null).

Unlinking Scopes

To remove the parent-child relationship:

Open Child Scope

Navigate to the child scope you want to unlink.

Click Unlink

Click the "Unlink from Parent" button.

Confirm Unlinking

A confirmation modal appears:

"Unlinking will preserve current values but stop inheritance. Continue?"

Click "Unlink".

Verify Unlinking

Child scope is now independent:

Current dimensions are preserved (frozen at last inherited values)
Link badge removed
Future parent changes won't affect this scope

note

Unlinking preserves current values — it doesn't delete data. The child scope keeps its current dimensions but becomes independent.

Updating Parent Scopes

When you update a parent scope, all linked child scopes update automatically:

Example Flow

Initial State

Parent Scope (Foundation Pad Template):

Length: 20 ft
Width: 20 ft
Depth: 1.5 ft

Child Scopes (Pad A, B, C):

All inherit: 20 × 20 × 1.5 ft
Cubic Yards: 1.11 CY each

Update Parent

Edit parent scope dimensions:

Length: 22 ft (updated)
Width: 20 ft
Depth: 1.5 ft

Children Auto-Update

Child Scopes (Pad A, B, C) now show:

Length: 22 ft (inherited from parent)
Width: 20 ft
Depth: 1.5 ft
Cubic Yards: 1.22 CY (recalculated)

Unless overridden:

If Pad B had a custom length, it keeps its custom value
If Pad C inherited everything, it updates to 22 ft

Cost Rollup Triggered

All child scopes trigger cost recalculation:

Concrete items recalculate based on new cubic yards
Scope totals update
Bid total updates

info

Linked scopes update in real-time when parent changes. No manual refresh needed.

Single-Level Hierarchy Only

ForgeX enforces single-level hierarchy to keep relationships simple:

✅ Allowed:
Parent Scope
├── Child Scope A
├── Child Scope B
└── Child Scope C

❌ Not Allowed:
Parent Scope
└── Child Scope A
    └── Grandchild Scope (NOT SUPPORTED)

Why Single-Level?

Simplicity

Multi-level hierarchies introduce complexity:

Which properties override which?
How do changes propagate through multiple levels?
What happens if middle parent is deleted?

Single-level avoids these issues.

Predictability

With single-level:

Changes flow in one direction: Parent → Child
No cascading inheritance chains
Easy to visualize and debug

Performance

Multi-level hierarchies require recursive queries:

Slow database lookups
Complex cost rollup calculations
Potential for circular references

Single-level is fast and efficient.

warning

Attempting to link a scope that already has children will fail with an error: "Parent scope cannot have its own parent."

Validation Rules

ForgeX enforces these rules when linking scopes:

Rule	Description	Error Message
No Self-Linking	A scope cannot be linked to itself	"A scope cannot be linked to itself"
Same Bid Only	Parent and child must be in the same bid	"Scopes must be in the same bid"
No Multi-Level	Parent cannot have its own parent	"Only single-level hierarchy is allowed"
No Circular References	Parent cannot be a child of the child	"Cannot create circular reference"

API Validation

const { validateLinking } = require('../services/scopeLinkingService');

// Before linking
const validation = await validateLinking(childScopeId, parentScopeId);

if (!validation.valid) {
  return res.status(400).json({ error: validation.error });
}

// Proceed with linking

Viewing Linked Scopes

Parent Scope View

Parent scopes show a list of linked children:

┌────────────────────────────────────┐
│ Foundation Pad Template        Edit│
├────────────────────────────────────┤
│ Length: 20 ft                      │
│ Width: 20 ft                       │
│ Depth: 1.5 ft                      │
│ Cubic Yards: 1.11 CY               │
│                                    │
│ 🔗 Linked Children: 3              │
│  • Pad A - North Corner            │
│  • Pad B - South Corner            │
│  • Pad C - East Wing               │
└────────────────────────────────────┘

Child Scope View

Child scopes show their parent link:

┌────────────────────────────────────┐
│ Pad A - North Corner           Edit│
├────────────────────────────────────┤
│ 🔗 Linked to: Foundation Pad       │
│    Template                [Unlink]│
│                                    │
│ Length: 20 ft (inherited)          │
│ Width: 20 ft (inherited)           │
│ Depth: 1.5 ft (inherited)          │
│ Cubic Yards: 1.11 CY               │
└────────────────────────────────────┘

API Endpoints

Link Scope to Parent

POST /api/scopes/:scopeId/link

Request Body:
{
  "parentScopeId": "parent-scope-uuid"
}

Response:
{
  "id": "child-scope-uuid",
  "parentScopeId": "parent-scope-uuid",
  "length": 20,  // Inherited
  "width": 20,   // Inherited
  "depth": 1.5   // Inherited
}

Unlink Scope from Parent

DELETE /api/scopes/:scopeId/link

Response:
{
  "id": "child-scope-uuid",
  "parentScopeId": null,
  "length": 20,  // Preserved (no longer inherited)
  "width": 20,   // Preserved
  "depth": 1.5   // Preserved
}

Get Linked Children

GET /api/scopes/:scopeId/children

Response:
[
  {
    "id": "child-1-uuid",
    "name": "Pad A - North Corner",
    "length": 20,
    "width": 20
  },
  {
    "id": "child-2-uuid",
    "name": "Pad B - South Corner",
    "length": 25,  // Overridden
    "width": 25    // Overridden
  }
]

Best Practices

🏷️

Name Templates Clearly

Use names like "Foundation Pad Template" or "Driveway Bay Standard" for parent scopes.

⬇️

Start with Parent First

Create parent scope before children. It's easier to link during creation than retrofit later.

📝

Document Overrides

Add notes to child scopes explaining why they override parent properties.

👁️

Review Before Unlinking

Unlinking is irreversible. Verify you want to break inheritance before proceeding.

Common Scenarios

Multiple Foundation Pads

Scenario: 10 foundation pads, all 20×20×1.5 ft, but 2 are larger.

Steps:

Create parent: "Foundation Pad Standard" (20×20×1.5 ft)
Create 10 child scopes, link all to parent
Override dimensions for the 2 larger pads
If standard size changes, update parent → 8 scopes update automatically

Phased Parking Lot Bays

Scenario: 20 parking lot bays, built in 4 phases of 5 bays each.

Steps:

Create parent: "Parking Bay Template" (9×18×0.5 ft)
Create 20 child scopes:
- Bay 1-5 (Phase 1)
- Bay 6-10 (Phase 2)
- Bay 11-15 (Phase 3)
- Bay 16-20 (Phase 4)
All bays inherit dimensions
Use scope multipliers (5×) per phase if bays are identical

Driveway Sections with Consistent Mix

Scenario: 3 driveway sections, different dimensions, same concrete mix.

Steps:

Create parent: "Driveway Section" (custom dimensions)
Create 3 child scopes, link to parent
Override dimensions for each child (different lengths)
Add concrete items to parent → children inherit mix design
If mix design changes, update parent → all children update

Converting Unlinked Scopes to Linked

Scenario: You have 5 scopes with duplicate dimensions. Retrofit them to use linking.

Steps:

Pick one scope as the "template" parent
For each other scope:
- Link to parent
- Clear dimension fields (to inherit)
- Verify dimensions match parent
Delete duplicate dimensions, keep only parent
Future updates only need parent changes

Troubleshooting

Common Issues

Issue	Cause	Solution
Can't link scopes	Scopes in different bids	Move scopes to same bid or unlink
Parent has children, can't link	Attempting multi-level hierarchy	Unlink children first, then link
Child not updating	Property overridden in child	Clear child property to re-inherit
Circular reference error	Attempting to link parent to child	Check link direction

Future Enhancements

note

Planned features for scope linking:

Bulk linking: Link multiple scopes to parent at once
Link inheritance toggles: Choose which properties to inherit per child
Visual hierarchy view: Tree view showing parent-child relationships
Template library: Save parent scopes as reusable templates
Multi-level hierarchy (optional): Configurable depth limit for complex projects

Next Steps

🧮

Scope Multipliers

Learn how multipliers scale costs for repeated areas

📄

Creating a Bid

Complete guide to bid creation workflow

Use Cases​

Repeated Elements

Standardized Work

Phased Construction

Material Consistency

How Scope Linking Works​

Parent-Child Relationship​

Inheritance Rules​

Creating Linked Scopes​

Overriding Inherited Properties​

Unlinking Scopes​

Updating Parent Scopes​

Example Flow​

Single-Level Hierarchy Only​

Why Single-Level?​

Validation Rules​

API Validation​

Viewing Linked Scopes​

Parent Scope View​

Child Scope View​

API Endpoints​

Link Scope to Parent​

Unlink Scope from Parent​

Get Linked Children​

Best Practices​

Name Templates Clearly

Start with Parent First

Document Overrides

Review Before Unlinking

Common Scenarios​

Troubleshooting​

Common Issues​

Future Enhancements​

Next Steps​

Scope Multipliers

Creating a Bid

Use Cases

How Scope Linking Works

Parent-Child Relationship

Inheritance Rules

Creating Linked Scopes

Overriding Inherited Properties

Unlinking Scopes

Updating Parent Scopes

Example Flow

Single-Level Hierarchy Only

Why Single-Level?

Validation Rules

API Validation

Viewing Linked Scopes

Parent Scope View

Child Scope View

API Endpoints

Link Scope to Parent

Unlink Scope from Parent

Get Linked Children

Best Practices

Common Scenarios

Troubleshooting

Common Issues

Future Enhancements

Next Steps