# How Macro Implements Bidirectional @linking Between Entities

> Discover how Macro implements bidirectional @linking using a directed-graph table and symmetric lookup helpers for efficient reverse traversal.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: internals
- Published: 2026-08-17

---

**Macro implements bidirectional @linking through a lightweight directed-graph table named `macro_user_links` that stores unidirectional edges from primary to child users, paired with symmetric lookup helpers enabling reverse traversal.**

The **macro-inc/macro** repository handles cross-entity references such as mentions and inbox delegation through a sophisticated linking system. This article examines how the codebase achieves **bidirectional @linking** between entities using a single table design with dual-direction query capabilities.

## The `macro_user_links` Table: Directed Graph Storage

The foundation of Macro's linking system rests in the **`macro_user_links`** table managed within [`crates/macro_db_client/src/macro_user_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs). Each row stores a directed edge containing three critical components: a *primary* Macro user ID, a *child* Macro user ID, and the **`link_id`** referencing a specific row in the `email_links` table.

Although the physical storage represents a single direction (primary → child → link), the schema enables precise scoping where each edge grants access to exactly one inbox. This design allows the system to revoke specific inbox access without affecting other delegations between the same users.

## Core Operations and Edge Management

The database client provides atomic operations for manipulating delegation edges. These functions ensure idempotent inserts and safe deletion of links.

### Inserting and Removing Edges

The **`insert_edge`** function creates delegation relationships while ignoring duplicate entries, making it safe for repeated calls. Located at [`macro_user_links.rs:12-38`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L12-L38), this operation establishes the primary-to-child connection for a specific inbox.

```rust
// Grant primary `alice` access to child `bob`'s inbox identified by `link_id`
macro_user_links::insert_edge(&db, "alice", "bob", link_id).await?;

```

To remove access, the **`delete_edge`** function at [`macro_user_links.rs:40-64`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L40-L64) removes the specific triple from the table. The **`edge_exists`** helper at [`macro_user_links.rs:66-94`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L66-L94) validates whether a delegation is active before performing authorization-sensitive operations.

### Authorization Checks

Before processing delegated requests, the system verifies edges using the existence check:

```rust
let has_edge = macro_user_links::edge_exists(&db, "alice", "bob", link_id).await?;

```

## Bidirectional Lookup Helpers

To achieve **bidirectional @linking** without storing duplicate reverse edges, Macro implements symmetric query functions that traverse the graph in both directions.

### Forward Traversal: Finding Child Inboxes

The **`children_for_primary`** function at [`macro_user_links.rs:96-115`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L96-L115) enables forward traversal by returning all child Macro IDs accessible to a given primary user. The email service uses this to union linked inboxes with a user's own inbox when fetching messages.

```rust
// List all child inboxes alice can read
let children = macro_user_links::children_for_primary(&db, "alice").await?;

```

### Reverse Traversal: Finding Primary Users

For reverse lookups, two specialized functions enable children to discover who can access their content. The **`get_primaries_for_child`** function at [`macro_user_links.rs:117-137`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L117-L137) returns every primary user with delegation rights to a specific child.

When scoped to a particular inbox, **`get_primaries_for_link`** at [`macro_user_links.rs:139-161`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs#L139-L161) identifies exactly which primaries can read that specific `link_id`. This powers the notification system's fan-out mechanism:

```rust
// Find every primary that can read bob's inbox `link_id`
let primaries = macro_user_links::get_primaries_for_link(&db, "bob", link_id).await?;

```

## Integration Across the Stack

The linking system integrates throughout Macro's architecture, from database to user interface.

### Email Service Integration

In [`crates/email/src/outbound/email_pg_repo/link.rs`](https://github.com/macro-inc/macro/blob/main/crates/email/src/outbound/email_pg_repo/link.rs), the system creates and deletes `email_links` rows that serve as the targets for `macro_user_links` references. The email service combines these with **`children_for_primary`** queries to aggregate accessible inboxes for primary users.

### Notification Fan-Out

The notification system leverages **`get_primaries_for_link`** to distribute child-inbox events to every authorized primary user. This ensures real-time updates propagate correctly across delegation boundaries without requiring duplicate storage of reverse relationships.

### Frontend Exposure

The web client consumes these relationships through the `GET /email/links` endpoint, which returns an `is_primary` flag based on `macro_user_links` queries. The UI hook `useEmailLinksQuery` in [`apps/web/src/lib/queries/email/link.ts`](https://github.com/macro-inc/macro/blob/main/apps/web/src/lib/queries/email/link.ts) surfaces these permissions to determine interface rendering.

### Authorization API

The authentication service exposes link existence checks via [`services/authentication_service/src/api/user/get_user_link_exists.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/api/user/get_user_link_exists.rs), allowing API endpoints to verify delegation rights before processing cross-user requests.

## Summary

- Macro implements **bidirectional @linking** through the `macro_user_links` table, storing directed edges from primary to child users scoped to specific inbox IDs.
- The **`insert_edge`**, **`delete_edge`**, and **`edge_exists`** functions in [`macro_user_links.rs`](https://github.com/macro-inc/macro/blob/main/macro_user_links.rs) provide atomic, idempotent operations for managing delegation.
- **Forward traversal** uses `children_for_primary` to find all child inboxes a primary can access.
- **Reverse traversal** uses `get_primaries_for_child` and `get_primaries_for_link` to discover which primaries can view specific children or inboxes.
- The system integrates across the stack, powering email aggregation, notification fan-out, and UI permission flags while maintaining storage efficiency through single-direction edges with symmetric queries.

## Frequently Asked Questions

### What database table stores Macro's @link relationships?

The **`macro_user_links`** table stores all delegation relationships as directed edges containing a primary user ID, child user ID, and `link_id` referencing the specific inbox being shared. This table is defined and managed in [`crates/macro_db_client/src/macro_user_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_db_client/src/macro_user_links.rs).

### How does Macro achieve bidirectional lookups without storing duplicate data?

Macro uses **symmetric query helpers** rather than duplicate storage. While edges store only the primary → child direction, the `get_primaries_for_child` and `get_primaries_for_link` functions perform reverse lookups by querying the same table with inverted WHERE clauses, enabling efficient bidirectional traversal without data duplication.

### Can multiple primaries access the same child's inbox?

Yes. The schema supports many-to-many relationships where multiple primary users can have edges pointing to the same child and `link_id` combination. The `get_primaries_for_link` function specifically handles this case by returning all primaries authorized for a specific child's inbox.

### How does the system prevent duplicate link creation?

The **`insert_edge`** function is idempotent by design. When attempting to create an edge that already exists, the operation ignores the duplicate insert rather than failing, ensuring safe repeated calls without requiring prior existence checks.