System Design (LLD)Defining Relationships

Defining Relationships in Low-Level Design

LevelIntermediate

Duration60 mins

TopicDefining Relationships

3 / 4

Navigability

The Paths Through Your Object Graph

Knowing that Order and Customer are related is fundamental. But a deeper question shapes your design: Who needs to find whom? Does an order need to access its customer? Does a customer need to access their orders? Both? Neither?

Navigability defines the direction of traversal in a relationship. It determines which object holds a reference to the other, directly impacting API design, data access patterns, memory usage, and maintenance complexity.

Get navigability wrong, and you'll either have circular dependencies creating memory leaks and testing nightmares, or you'll find yourself constantly traversing through intermediate objects because you can't get from A to B directly.

What You Will Learn

By the end of this page, you will understand unidirectional vs bidirectional navigation, know when to use each, master techniques for managing bidirectional relationships, and recognize the trade-offs involved.

Understanding Navigability

Navigability describes which direction(s) you can traverse a relationship in code.

Types of Navigability:

Unidirectional (→): Only one class holds a reference to the other
- A knows about B, but B doesn't know about A
- Simpler to implement and maintain
- Lower coupling
Bidirectional (↔): Both classes hold references to each other
- A knows about B, and B knows about A
- More flexible access patterns
- Higher coupling, more complex maintenance
Non-navigable: The relationship exists conceptually but neither class holds a direct reference
- Relationship managed externally (e.g., by a repository or service)
- Useful for very loose coupling

Navigability Decision Factors
Question	Unidirectional	Bidirectional
Who needs access?	Only one side queries the other	Both sides need to query each other
Complexity	Simple—one reference to manage	Complex—must keep references in sync
Coupling	Lower—only one class depends on other	Higher—both classes depend on each other
Memory	Lower—fewer references	Higher—references on both sides
Use case	Parent→children, Service→dependency	Mutual associations, networks

Unidirectional Navigation

Unidirectional navigation is the default choice and should be preferred unless there's a compelling reason for bidirectionality.

When to Use Unidirectional:

Parent→Child relationships where children don't need parent
Aggregations where the whole navigates to parts
Service classes using other services/repositories
Any relationship where only one direction of access is needed

Benefits:

Simpler to implement and test
No synchronization issues
Clearer data flow
Easier to reason about

unidirectional-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// Unidirectional: Order → OrderItems
// Order knows about its items, items don't need to know about order
 
class OrderItem {
    // No reference back to Order - unidirectional
    constructor(
        public readonly sku: string,
        public readonly name: string,
        public readonly quantity: number,
        public readonly unitPrice: number
    ) {}
    
    getSubtotal(): number {
        return this.quantity * this.unitPrice;
    }
}
 
class Order {
    private readonly items: OrderItem[] = [];
    
    constructor(
        public readonly orderId: string,
        public readonly customerId: string
    ) {}
    
    // Order navigates TO items
    addItem(sku: string, name: string, qty: number, price: number): void {
        this.items.push(new OrderItem(sku, name, qty, price));
    }
    
    getItems(): ReadonlyArray<OrderItem> {
        return this.items;
    }
    
    getTotal(): number {
        return this.items.reduce((sum, item) => sum + item.getSubtotal(), 0);
    }
    
    getItemCount(): number {
        return this.items.length;
    }
}
 
// Unidirectional: Service → Repository
// OrderService uses OrderRepository; repository doesn't know about service
 
interface OrderRepository {
    findById(id: string): Promise<Order | null>;
    save(order: Order): Promise<void>;
    findByCustomerId(customerId: string): Promise<Order[]>;
}
 
class OrderService {
    // Service navigates TO repository
    constructor(private readonly orderRepository: OrderRepository) {}
    
    async createOrder(customerId: string): Promise<Order> {
        const order = new Order(`ORD-${Date.now()}`, customerId);
        await this.orderRepository.save(order);
        return order;
    }
    
    async getCustomerOrders(customerId: string): Promise<Order[]> {
        return this.orderRepository.findByCustomerId(customerId);
    }
}

Default to Unidirectional

Always start with unidirectional navigation. Only add bidirectionality when you have a concrete use case that requires it. It's easy to add a back-reference later but hard to remove one that code has come to depend on.

Bidirectional Navigation

Bidirectional navigation allows traversal in both directions but comes with significant complexity.

When Bidirectional is Needed:

Both sides frequently need to access each other
The relationship is symmetric (e.g., friends, colleagues)
Navigation from child to parent is required for business logic
ORM frameworks sometimes prefer bidirectional for lazy loading

The Core Challenge: With bidirectional relationships, you must keep both sides synchronized. If A references B, and B references A, adding or removing from one side must update the other. This is the source of many bugs.

bidirectional-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
// Bidirectional: Employee ↔ Department
// Employees need their department; departments need their employees
 
class Employee {
    private department: Department | null = null;
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    // INTERNAL: Only Department should call this
    _setDepartment(dept: Department | null): void {
        this.department = dept;
    }
    
    getDepartment(): Department | null {
        return this.department;
    }
    
    // PUBLIC: Use this to transfer departments
    transferTo(newDepartment: Department | null): void {
        if (this.department === newDepartment) return;
        
        // Remove from old department
        if (this.department) {
            this.department._removeEmployee(this);
        }
        
        // Add to new department
        if (newDepartment) {
            newDepartment._addEmployee(this);
        }
        
        this.department = newDepartment;
    }
}
 
class Department {
    private readonly employees = new Set<Employee>();
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    // INTERNAL: Only Employee should call these
    _addEmployee(employee: Employee): void {
        this.employees.add(employee);
        employee._setDepartment(this);
    }
    
    _removeEmployee(employee: Employee): void {
        this.employees.delete(employee);
        employee._setDepartment(null);
    }
    
    // PUBLIC: Use this to hire
    hire(employee: Employee): void {
        if (this.employees.has(employee)) return;
        employee.transferTo(this);
    }
    
    getEmployees(): ReadonlySet<Employee> {
        return this.employees;
    }
    
    getEmployeeCount(): number {
        return this.employees.size;
    }
}
 
// Usage preserves consistency
const engineering = new Department("D1", "Engineering");
const alice = new Employee("E1", "Alice");
 
engineering.hire(alice);
console.log(alice.getDepartment()?.name); // "Engineering"
console.log(engineering.getEmployeeCount()); // 1
 
const product = new Department("D2", "Product");
alice.transferTo(product);
console.log(engineering.getEmployeeCount()); // 0
console.log(product.getEmployeeCount()); // 1

Managing Bidirectional Consistency

The biggest challenge with bidirectional relationships is keeping both sides consistent. Here are proven patterns:

Consistency Patterns

•Owning Side Pattern: Designate one side as the 'owner' that manages the relationship. All modifications go through the owner, which updates both sides.
•Synchronization Methods: Create helper methods that update both references atomically. Never expose raw setters that could break consistency.
•Internal Methods: Use naming conventions (like _setX or package-private) to indicate methods that shouldn't be called directly by client code.
•Defensive Checks: Always check for existing relationships before adding/removing to prevent duplicates or orphans.
•Immutable After Creation: For some relationships, make them immutable after creation to avoid synchronization issues entirely.

consistency-pattern
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Pattern: Owning Side (Author owns the relationship to Books)
class Book {
    private _author: Author | null = null;
    
    constructor(
        public readonly isbn: string,
        public readonly title: string
    ) {}
    
    get author(): Author | null {
        return this._author;
    }
    
    // Internal: Only Author should call this
    _setAuthor(author: Author | null): void {
        this._author = author;
    }
}
 
class Author {
    private readonly _books = new Set<Book>();
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    get books(): ReadonlySet<Book> {
        return this._books;
    }
    
    // Author is the OWNING SIDE - manages both directions
    addBook(book: Book): void {
        if (this._books.has(book)) return;
        
        // Remove from previous author
        const previousAuthor = book.author;
        if (previousAuthor) {
            previousAuthor._books.delete(book);
        }
        
        // Add to this author
        this._books.add(book);
        book._setAuthor(this);
    }
    
    removeBook(book: Book): void {
        if (!this._books.has(book)) return;
        
        this._books.delete(book);
        book._setAuthor(null);
    }
}
 
// Client code only uses Author's methods
const author = new Author("1", "J.K. Rowling");
const book = new Book("978-0-7475-3269-9", "Harry Potter");
 
author.addBook(book); // Both sides updated
console.log(book.author?.name); // "J.K. Rowling"
console.log(author.books.size); // 1

Circular Reference Pitfalls

Bidirectional relationships create circular references. While modern garbage collectors handle these for memory, they cause other problems:

Common Pitfalls

•Infinite Recursion in toString()/equals(): If A.toString() includes B and B.toString() includes A, you get stack overflow.
•Serialization Loops: JSON serialization of circular references causes infinite loops or requires special handling.
•Testing Complexity: Setting up test fixtures requires creating multiple objects with proper linkage.
•Lazy Loading Issues: In ORMs, bidirectional relationships can trigger unexpected database queries.
•Memory Bloat: In caching scenarios, circular references prevent objects from being garbage collected.

solving-circular-issues
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// Problem: JSON serialization of circular references
class Department {
    employees: Employee[] = [];
    toJSON() { return { name: this.name, employees: this.employees }; }
}
class Employee {
    department: Department;
    toJSON() { return { name: this.name, department: this.department }; }
}
// JSON.stringify(dept) → infinite loop!
 
// Solution 1: Custom toJSON that breaks the cycle
class Employee {
    department: Department;
    
    toJSON() {
        return {
            name: this.name,
            departmentId: this.department?.id // Reference by ID, not object
        };
    }
}
 
// Solution 2: Use a library like flatted for circular JSON
import { stringify, parse } from 'flatted';
const json = stringify(circularObject); // Handles cycles
 
// Solution 3: Exclude back-references in serialization
class Department {
    @Exclude() // Decorator to exclude from serialization
    employees: Employee[] = [];
}
 
// Solution 4: Make toString() cycle-aware
class Employee {
    toString(): string {
        // Don't include department details, just ID
        return `Employee(${this.name}, dept:${this.department?.id})`;
    }
}

Representing Navigability in UML

UML provides specific notation for navigability:

UML Navigability Symbols
Symbol	Meaning	Example
A——→B	Unidirectional: A navigates to B	Order→Customer
A←——→B	Bidirectional: Both navigate	Employee↔Department
A——×B	Non-navigable: A cannot reach B	A×——B (neither can reach other)
A——B (no arrows)	Unspecified/both ways	Early design phase

UML Tip

In UML, an arrowhead indicates navigability. The class at the arrow's origin can navigate to the class at the arrowhead. An 'X' explicitly marks a non-navigable end. No symbol means navigability is unspecified.

Summary: Navigability Best Practices

Key Takeaways

•Default to unidirectional — Only add bidirectionality when genuinely needed
•Designate an owning side — One class controls the relationship and maintains consistency
•Never expose raw setters — Use methods that update both sides atomically
•Watch for circular reference issues — Especially in serialization and toString()
•Consider the query patterns — Navigability should reflect how you'll actually access the data
•Document bidirectional constraints — Make it clear how the relationship should be managed

Page Complete

You now understand navigability and its implications for design. In the final page of this module, we'll cover relationship validation—ensuring your relationships are correct, complete, and consistent.

3 / 4

Loading learning content...

System Design (LLD)Defining Relationships

Defining Relationships in Low-Level Design

LevelIntermediate

Duration60 mins

TopicDefining Relationships

3 / 4

Navigability

The Paths Through Your Object Graph

What You Will Learn

Understanding Navigability

Navigability describes which direction(s) you can traverse a relationship in code.

Types of Navigability:

Unidirectional (→): Only one class holds a reference to the other
- A knows about B, but B doesn't know about A
- Simpler to implement and maintain
- Lower coupling
Bidirectional (↔): Both classes hold references to each other
- A knows about B, and B knows about A
- More flexible access patterns
- Higher coupling, more complex maintenance
Non-navigable: The relationship exists conceptually but neither class holds a direct reference
- Relationship managed externally (e.g., by a repository or service)
- Useful for very loose coupling

Navigability Decision Factors
Question	Unidirectional	Bidirectional
Who needs access?	Only one side queries the other	Both sides need to query each other
Complexity	Simple—one reference to manage	Complex—must keep references in sync
Coupling	Lower—only one class depends on other	Higher—both classes depend on each other
Memory	Lower—fewer references	Higher—references on both sides
Use case	Parent→children, Service→dependency	Mutual associations, networks

Unidirectional Navigation

Unidirectional navigation is the default choice and should be preferred unless there's a compelling reason for bidirectionality.

When to Use Unidirectional:

Parent→Child relationships where children don't need parent
Aggregations where the whole navigates to parts
Service classes using other services/repositories
Any relationship where only one direction of access is needed

Benefits:

Simpler to implement and test
No synchronization issues
Clearer data flow
Easier to reason about

unidirectional-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
// Unidirectional: Order → OrderItems
// Order knows about its items, items don't need to know about order
 
class OrderItem {
    // No reference back to Order - unidirectional
    constructor(
        public readonly sku: string,
        public readonly name: string,
        public readonly quantity: number,
        public readonly unitPrice: number
    ) {}
    
    getSubtotal(): number {
        return this.quantity * this.unitPrice;
    }
}
 
class Order {
    private readonly items: OrderItem[] = [];
    
    constructor(
        public readonly orderId: string,
        public readonly customerId: string
    ) {}
    
    // Order navigates TO items
    addItem(sku: string, name: string, qty: number, price: number): void {
        this.items.push(new OrderItem(sku, name, qty, price));
    }
    
    getItems(): ReadonlyArray<OrderItem> {
        return this.items;
    }
    
    getTotal(): number {
        return this.items.reduce((sum, item) => sum + item.getSubtotal(), 0);
    }
    
    getItemCount(): number {
        return this.items.length;
    }
}
 
// Unidirectional: Service → Repository
// OrderService uses OrderRepository; repository doesn't know about service
 
interface OrderRepository {
    findById(id: string): Promise<Order | null>;
    save(order: Order): Promise<void>;
    findByCustomerId(customerId: string): Promise<Order[]>;
}
 
class OrderService {
    // Service navigates TO repository
    constructor(private readonly orderRepository: OrderRepository) {}
    
    async createOrder(customerId: string): Promise<Order> {
        const order = new Order(`ORD-${Date.now()}`, customerId);
        await this.orderRepository.save(order);
        return order;
    }
    
    async getCustomerOrders(customerId: string): Promise<Order[]> {
        return this.orderRepository.findByCustomerId(customerId);
    }
}

Default to Unidirectional

Bidirectional Navigation

Bidirectional navigation allows traversal in both directions but comes with significant complexity.

When Bidirectional is Needed:

Both sides frequently need to access each other
The relationship is symmetric (e.g., friends, colleagues)
Navigation from child to parent is required for business logic
ORM frameworks sometimes prefer bidirectional for lazy loading

bidirectional-example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
// Bidirectional: Employee ↔ Department
// Employees need their department; departments need their employees
 
class Employee {
    private department: Department | null = null;
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    // INTERNAL: Only Department should call this
    _setDepartment(dept: Department | null): void {
        this.department = dept;
    }
    
    getDepartment(): Department | null {
        return this.department;
    }
    
    // PUBLIC: Use this to transfer departments
    transferTo(newDepartment: Department | null): void {
        if (this.department === newDepartment) return;
        
        // Remove from old department
        if (this.department) {
            this.department._removeEmployee(this);
        }
        
        // Add to new department
        if (newDepartment) {
            newDepartment._addEmployee(this);
        }
        
        this.department = newDepartment;
    }
}
 
class Department {
    private readonly employees = new Set<Employee>();
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    // INTERNAL: Only Employee should call these
    _addEmployee(employee: Employee): void {
        this.employees.add(employee);
        employee._setDepartment(this);
    }
    
    _removeEmployee(employee: Employee): void {
        this.employees.delete(employee);
        employee._setDepartment(null);
    }
    
    // PUBLIC: Use this to hire
    hire(employee: Employee): void {
        if (this.employees.has(employee)) return;
        employee.transferTo(this);
    }
    
    getEmployees(): ReadonlySet<Employee> {
        return this.employees;
    }
    
    getEmployeeCount(): number {
        return this.employees.size;
    }
}
 
// Usage preserves consistency
const engineering = new Department("D1", "Engineering");
const alice = new Employee("E1", "Alice");
 
engineering.hire(alice);
console.log(alice.getDepartment()?.name); // "Engineering"
console.log(engineering.getEmployeeCount()); // 1
 
const product = new Department("D2", "Product");
alice.transferTo(product);
console.log(engineering.getEmployeeCount()); // 0
console.log(product.getEmployeeCount()); // 1

Managing Bidirectional Consistency

The biggest challenge with bidirectional relationships is keeping both sides consistent. Here are proven patterns:

Consistency Patterns

•Owning Side Pattern: Designate one side as the 'owner' that manages the relationship. All modifications go through the owner, which updates both sides.
•Synchronization Methods: Create helper methods that update both references atomically. Never expose raw setters that could break consistency.
•Internal Methods: Use naming conventions (like _setX or package-private) to indicate methods that shouldn't be called directly by client code.
•Defensive Checks: Always check for existing relationships before adding/removing to prevent duplicates or orphans.
•Immutable After Creation: For some relationships, make them immutable after creation to avoid synchronization issues entirely.

consistency-pattern
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Pattern: Owning Side (Author owns the relationship to Books)
class Book {
    private _author: Author | null = null;
    
    constructor(
        public readonly isbn: string,
        public readonly title: string
    ) {}
    
    get author(): Author | null {
        return this._author;
    }
    
    // Internal: Only Author should call this
    _setAuthor(author: Author | null): void {
        this._author = author;
    }
}
 
class Author {
    private readonly _books = new Set<Book>();
    
    constructor(
        public readonly id: string,
        public readonly name: string
    ) {}
    
    get books(): ReadonlySet<Book> {
        return this._books;
    }
    
    // Author is the OWNING SIDE - manages both directions
    addBook(book: Book): void {
        if (this._books.has(book)) return;
        
        // Remove from previous author
        const previousAuthor = book.author;
        if (previousAuthor) {
            previousAuthor._books.delete(book);
        }
        
        // Add to this author
        this._books.add(book);
        book._setAuthor(this);
    }
    
    removeBook(book: Book): void {
        if (!this._books.has(book)) return;
        
        this._books.delete(book);
        book._setAuthor(null);
    }
}
 
// Client code only uses Author's methods
const author = new Author("1", "J.K. Rowling");
const book = new Book("978-0-7475-3269-9", "Harry Potter");
 
author.addBook(book); // Both sides updated
console.log(book.author?.name); // "J.K. Rowling"
console.log(author.books.size); // 1

Circular Reference Pitfalls

Bidirectional relationships create circular references. While modern garbage collectors handle these for memory, they cause other problems:

Common Pitfalls

•Infinite Recursion in toString()/equals(): If A.toString() includes B and B.toString() includes A, you get stack overflow.
•Serialization Loops: JSON serialization of circular references causes infinite loops or requires special handling.
•Testing Complexity: Setting up test fixtures requires creating multiple objects with proper linkage.
•Lazy Loading Issues: In ORMs, bidirectional relationships can trigger unexpected database queries.
•Memory Bloat: In caching scenarios, circular references prevent objects from being garbage collected.

solving-circular-issues
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// Problem: JSON serialization of circular references
class Department {
    employees: Employee[] = [];
    toJSON() { return { name: this.name, employees: this.employees }; }
}
class Employee {
    department: Department;
    toJSON() { return { name: this.name, department: this.department }; }
}
// JSON.stringify(dept) → infinite loop!
 
// Solution 1: Custom toJSON that breaks the cycle
class Employee {
    department: Department;
    
    toJSON() {
        return {
            name: this.name,
            departmentId: this.department?.id // Reference by ID, not object
        };
    }
}
 
// Solution 2: Use a library like flatted for circular JSON
import { stringify, parse } from 'flatted';
const json = stringify(circularObject); // Handles cycles
 
// Solution 3: Exclude back-references in serialization
class Department {
    @Exclude() // Decorator to exclude from serialization
    employees: Employee[] = [];
}
 
// Solution 4: Make toString() cycle-aware
class Employee {
    toString(): string {
        // Don't include department details, just ID
        return `Employee(${this.name}, dept:${this.department?.id})`;
    }
}

Representing Navigability in UML

UML provides specific notation for navigability:

UML Navigability Symbols
Symbol	Meaning	Example
A——→B	Unidirectional: A navigates to B	Order→Customer
A←——→B	Bidirectional: Both navigate	Employee↔Department
A——×B	Non-navigable: A cannot reach B	A×——B (neither can reach other)
A——B (no arrows)	Unspecified/both ways	Early design phase

UML Tip

Summary: Navigability Best Practices

Key Takeaways

•Default to unidirectional — Only add bidirectionality when genuinely needed
•Designate an owning side — One class controls the relationship and maintains consistency
•Never expose raw setters — Use methods that update both sides atomically
•Watch for circular reference issues — Especially in serialization and toString()
•Consider the query patterns — Navigability should reflect how you'll actually access the data
•Document bidirectional constraints — Make it clear how the relationship should be managed

Page Complete

3 / 4