Relations are the core concept that makes CodeDB more than a simple editor. They let you define typed connections between files, creating a knowledge graph of your codebase.

A relation connects a source file to a target file with a type. For example:

• app.js imports utils.js
• api.py depends_on database.py
• README.md documents main.go
• test_auth.py tests auth.py

There are several ways to add a relation:

1. Open a file in the editor
2. Open the bottom panel (⌘J) and click the Relations tab
3. The panel shows two sections: Dependencies (outgoing) and Links & Tags (incoming)
4. Use the controls to add a new relation

1. Right-click a file in the sidebar
2. Select Add Relation
3. Choose the target file and relation type

1. Press ⌘R to quickly add a relation from the current file

You can use any relation type string. Common types include:

• imports — file imports or includes another
• depends_on — file depends on another
• extends — file extends or inherits from another
• tests — test file for a source file
• documents — documentation for a file
• related_to — general association
• calls — file calls functions from another
• configures — configuration file for a module

The Relations panel at the bottom of the editor shows all connections for the active file:

• Dependencies — files that the current file depends on (outgoing relations)
• Links & Tags — files that depend on or link to the current file (incoming relations)

Each relation shows the connected file name, relation type, and can be clicked to navigate to that file.

Relations can store optional metadata as key-value pairs. This is useful for adding context like version constraints, notes, or categories to a relationship.

Relations are stored in the relations table:

CREATE TABLE relations (
  id INTEGER PRIMARY KEY,
  source_id INTEGER REFERENCES files(id),
  target_id INTEGER REFERENCES files(id),
  relation_type TEXT NOT NULL,
  metadata TEXT
);

You can query relations directly in the Query Console.